feat(mcp): add titles, inspector tags and structured output to agent tools

[erkamyaman]

What and why

The "tool titles / tags / structuredContent" item from #372.

Titles. Every built-in agent tool (89) has a short title, inline on its registerTool call: sentence case, 40 characters or fewer, unique, no "Pangular" (for example List connected pages, Inspect a component). devframe sends it as the MCP title and annotations.title, and browser tools (WebMCP) pass it through too. The RPC-backed get-* and build-meta tools already had titles. Plugin tools keep the titles their plugins give them.

Tags. Every tool is tagged with its inspector key through devframe's tags field, using the same keys as AGENT_INSPECTOR (new agentTags(id) in config.ts). clear-recordings gets http, router and analog; plugin tools get plugins; shared tools (list-pages, open-in-panel, audit, build-meta) get none. devframe 1.2.5 keeps tags in its agent manifest but does not send them over MCP tools/list, so MCP clients don't see them yet. No wire format of our own is added, and the docs don't mention tags.

Structured output. The registerTool tools answer with a { markdown } object, which devframe sends as JSON text. 29 of them now declare MARKDOWN_OUTPUT_SCHEMA (a valibot schema converted with @valibot/to-json-schema, type: object), so devframe also sends the same object as structuredContent. The text content does not change. With build-meta, which already had one, 30 tools send structuredContent:

• every list-* tool;
• every inspect-* tool;
• analog-routes, analog-api-routes, analog-server-functions, analog-server-calls, analog-content.

Left out on purpose:

• get-routes, get-components, get-pipes, get-signals, get-providers and get-ngrx-store return JSON arrays. Wrapping them in an object would change the text (the devframe feat: add fetch SSR tracing, a waterfall, store history and a TanStack Query inspector #400 pitfall).
• screenshot-component answers with image blocks and no structuredContent, so a schema would make clients reject it.
• Action, destructive and the other read tools stay as they are for now.

Fix found along the way. Calling inspect-component or highlight without selector while a page reported threw a TypeError, which reached the agent as a raw tool error. Both now answer with what to pass.

Docs: a "Titles and structured output" section in the MCP server page, with the table of tools that send structuredContent, and a link to it from the agent tools page. Tool counts are unchanged.

Refs #372.

How it was verified

• pnpm commit:check
• pnpm format:check
• pnpm typecheck
• pnpm test:devtools (3111) and pnpm test:panel. New tool-metadata.test.ts (9 tests):
  • titles are present, short and unique, and sent as title and annotations.title;
  • tags match the inspector;
  • only object output schemas are advertised, and the set matches the docs;
  • every schema tool is called through the hub's MCP endpoint (no page, a pushed page, an unknown page), and its structuredContent validates and equals the parsed text;
  • the text of list-pages, list-components and get-routes is byte-for-byte unchanged;
  • a missing selector gets a clear answer.
• pnpm skills:check
• Docs in apps/docs updated and pnpm docs:build passes
• pnpm extension:build (no app/ change)
• Extra end-to-end check, not committed: the official @modelcontextprotocol/client against the hub listed 95 tools, all titled, 30 with an output schema, and validated 179 tool calls.

Summary by CodeRabbit

• Documentation
  • Documented tool titles, annotations, structured responses, and which tools return schemas, arrays, or images.
  • Clarified that list and inspect tools provide structured answers.
• Improvements
  • Added clearer, more consistent titles and inspector tags across developer tools.
  • Standardized structured output for more tools, making responses easier for compatible clients to interpret.
  • Improved handling of invalid component selectors.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 6e870292-55eb-4983-9a71-72386f92f0cc

📥 Commits

Reviewing files that changed from the base of the PR and between 2e71bcc and 5e07f3a.

📒 Files selected for processing: 20

• apps/docs/src/content/agents/mcp-server.md
• apps/docs/src/content/agents/tools.md
• packages/devtools/src/__tests__/tool-metadata.test.ts
• packages/devtools/src/config.ts
• packages/devtools/src/devframe.ts
• packages/devtools/src/rpc/agent-output.ts
• packages/devtools/src/rpc/analog-register.ts
• packages/devtools/src/rpc/audit-register.ts
• packages/devtools/src/rpc/component-edits.ts
• packages/devtools/src/rpc/component-screenshots.ts
• packages/devtools/src/rpc/errors-register.ts
• packages/devtools/src/rpc/injection-explain.ts
• packages/devtools/src/rpc/leaks-register.ts
• packages/devtools/src/rpc/ngrx-session-tools.ts
• packages/devtools/src/rpc/plugins-register.ts
• packages/devtools/src/rpc/provider-values.ts
• packages/devtools/src/rpc/query-register.ts
• packages/devtools/src/rpc/redux-stores-register.ts
• packages/devtools/src/rpc/ssr-override-tools.ts
• packages/devtools/src/rpc/startup-register.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📝 Walkthrough

Agent tools gain display titles and inspector tags. Selected tools declare a shared Markdown output schema. Component inspection and highlighting now prompt for a nonempty selector. Tests and documentation cover the metadata and response formats.

Changes: Agent tool metadata

Layer / File(s)	Summary
Shared metadata contracts and wiring packages/devtools/src/rpc/agent-output.ts, packages/devtools/src/config.ts, packages/devtools/src/devframe.ts	Adds the shared Markdown output schema and agentTags helper. Registration wiring applies configured tags to regular and plugin tools.
Built-in tool metadata and selector checks packages/devtools/src/devframe.ts, packages/devtools/src/rpc/component-edits.ts, packages/devtools/src/rpc/component-screenshots.ts	Built-in tools gain titles and selected tools declare the Markdown schema. Component inspection and highlighting prompt for a selector when it is not a nonempty string.
RPC tool titles and output schemas packages/devtools/src/rpc/*	RPC tools gain or update titles. Selected tools declare the shared Markdown output schema.
Metadata verification and documentation packages/devtools/src/__tests__/tool-metadata.test.ts, apps/docs/src/content/agents/*	Tests check titles, tags, schema declarations, structured results, selector prompts, and selected text responses. Documentation describes tool titles and structured-content responses.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Merge Risk: ⚪ Minimal · up to 5e07f

No actionable merge-blocking issue is identified; the change is ready for normal merge checks.

Security architecture risk: 🔵 Low · up to 5e07f

The change adds a parallel structured representation of existing tool results without an identified expansion of tool permissions or data access. Risk is low, although compatibility across deployed clients has not been established.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The assessed exposure is the existing enabled tool surface and the application data those tools already return. No additional service authority, credential access, or data source was identified through the schema and registration changes.

Trust Boundaries and Controls

• observed — Inspector tags are added after existing exposure decisions. Registration continues to apply agentAllowed or agentExposed and the configured safety tier; tags are metadata rather than replacement authorization checks.

Resilience and Maintainability Implications

• observed — The selector guards introduce no reservation or partial mutation: rejected input returns before broadcasts or selection changes. For accepted inspection requests, the existing wait checks both page and instance identity, removes its waiter on completion or timeout, and reports timeout without claiming selection rollback. These recovery semantics predate the PR.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely summarizes the main changes: MCP tool titles, inspector tags, and structured output for agent tools.
Docstring Coverage		Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 20 functions across 18 files. (2 skipped: 2…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

🚀 Deploying Preview to Cloudflare 🚀

Preview Deployments by commit

Status	Deployment URL	Commit	Updated (UTC)	See this deployment's details
Build: Failed ❌ View logs ↗		5e07f3a	2026-10-15T20:13:40.917Z	View logs ↗

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 5e07f3a

Command	Status	Duration	Result
nx affected -t test build	✅ Succeeded	1m 41s	View ↗

💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗

---

☁️ Nx Cloud last updated this comment at 2026-10-15 20:15:20 UTC