mcp: fix and improve agent tool design from the October 2026 audit #331

Context

This comes from a code audit of the MCP agent tools (devframe.ts, rpc/*.ts, config.ts) done during a comparison with other devtools in October 2026. Roadmap items live in #310, #311, #312 and #313. Items marked (to confirm) were not reproduced.

Problems

Low

• No tool titles or structured output: no agent.registerTool call in devframe.ts sets title, so MCP clients show raw ids such as pangular:list-http-calls for most tools; only the RPC-backed tools (for example get-components.ts:44, build-meta.ts:28) have one. No tool sets tags or outputSchema, and every live tool returns markdown only. Add a short title and per-inspector tags to each tool, and return structuredContent next to the markdown for the list tools (list-pages, list-http-calls, list-components) so agents get stable ids without parsing text (packages/devtools/src/devframe.ts:909, 1743, 2281).
• Undeclared page on form tools: form-action and fill-form call unknownFormPage(args), which reads page, but neither inputSchema declares it, so clients never send it and the check is dead. Add page: PAGE_ARGUMENT to both schemas or remove the check (packages/devtools/src/devframe.ts:2798, 2851, 2425).
• Inconsistent page argument: highlight, inspect-component, defer-blocks and inspect-providers still accept a pageId alias next to page, while the others take only page. Use PAGE_ARGUMENT everywhere and drop the pageId aliases in a minor release (packages/devtools/src/devframe.ts:1761, 1825, 1914, 2100).
• Uncapped raw resources: the component-tree, signal-graph, injector-tree and ngrx-store resources return JSON.stringify(state, null, 2) of every page, with no size cap and no untrusted-data notice, although the strings come from the page. Cap the size, drop the indentation and add the UNTRUSTED notice (or an _untrusted field) (packages/devtools/src/devframe.ts:1616, 1625, 1634, 1643).
• Panel-only actions: clear-http-calls, clear-router-navigations, analog-clear-calls and request-component-pick have no agent tool, so an agent can't reset recorded data between repro runs. Add a clear-recordings tool (http, router, analog) gated by the matching actions.*, and list it in ACTION_TOOLS and AGENT_INSPECTOR and in agents/tools.md (packages/devtools/src/devframe.ts:623, 833, 1355, packages/devtools/src/rpc/analog-register.ts:227).
• analog-call-api path not described: path has no description and nothing says it must be a same-origin path starting with /, so agents guess whether to pass a full URL. Describe path, method and body, and spell out the confirm rule in the schema (packages/devtools/src/rpc/analog-register.ts:351-358).

Improvements

• Generate AGENT_INSPECTOR, ACTION_TOOLS and PAGE_AGENT_ENTRIES from metadata on each registerTool call (inspector, action, needs page) instead of three hand-kept lists, so a new tool can't be left out (packages/devtools/src/config.ts:407, 495, 548, packages/devtools/src/devframe.ts).
• Add MCP prompts for common workflows ("debug an invalid form", "why didn't this route load", "find slow change detection"), each chaining list-pages with the inspect and explain tools (packages/devtools/src/devframe.ts).
• Turn the six resources into per-page resource templates (pangular://page/{pageId}/component-tree) and send resources/list_changed when a page connects or expires, so clients can subscribe instead of polling (packages/devtools/src/devframe.ts:1610-1662).
• Add a general wait-for tool (app stable, navigation end, HTTP idle, @defer complete) that generalizes wait-for-form and navigate's waitFor: 'stable' (packages/devtools/src/devframe.ts:2730, 2281).
• Add a "snapshot everything" export tool (component tree, route, forms, HTTP, NgRx) for bug reports, next to the existing export-form and export-navigation (packages/devtools/src/devframe.ts:2241, 2714).
• Keep tool descriptions under about 600 characters. inspect-forms, navigate and the ngrx-store resource run past 1,000, which costs context in every client's tool list (packages/devtools/src/devframe.ts:1638, 2281, 2437).
• Add a module and lazy-chunk graph tool through the Vite plugin, as vite-plugin-mcp does (packages/devtools/src/vite.ts).

Already tracked elsewhere

• devframe_state_read and devframe://state expose data of inspectors turned off for agents: mcp: agent.tools.<inspector>=false still exposes the inspector's data through devframe_state_read #238, phase 1 of 4: safe by default, open in editor and cheap shell wins #310.
• agent.readOnly keeps tools of a destructive tier: phase 1 of 4: safe by default, open in editor and cheap shell wins #310 (three safety tiers).
• Writes such as submit, restore, dispatch and non-GET API calls are not marked destructive: phase 1 of 4: safe by default, open in editor and cheap shell wins #310.
• Inconsistent safety classes (highlight, record-pipes, change-detection, navigate, empty ACTION_TOOLS.router): phase 1 of 4: safe by default, open in editor and cheap shell wins #310.
• Missing errors, console, screenshot and open-in-editor tools: phase 1 of 4: safe by default, open in editor and cheap shell wins #310, phase 3 of 4: a devframe shell as good as Vue and Nuxt DevTools #312, phase 4 of 4: lead where no Angular devtools goes today #313. NgRx restore and SSR override agent tools: phase 4 of 4: lead where no Angular devtools goes today #313.