feat(mcp): ToolAnnotations hints on tools/list and GET /tools

[SutuSebastian]

Summary

• Add central mcp-tool-annotations.ts map with readOnlyHint / destructiveHint / idempotentHint for all 20 MCP tools
• Thread annotations into every registerTool call via withToolAnnotations()
• Extend HTTP GET /tools catalog with the same hint fields (dedupe tool list onto MCP_TOOL_NAMES)
• Document hints in agent-content skill + docs/agents.md

Test plan

• bun test src/application/mcp-tool-annotations.test.ts src/application/mcp-server.test.ts src/application/http-server.test.ts
• bun run typecheck
• Pre-commit hook (format, lint, typecheck, tests) passed on commit

Summary by CodeRabbit

• New Features

  • Tool endpoints now expose advisory metadata hints for each tool, including read-only, destructive, and idempotent flags via the MCP tools listing and HTTP GET /tools endpoint, helping consumers understand tool capabilities.

• Documentation

  • Updated documentation to reflect new tool annotation metadata available in responses.

[changeset-bot]

🦋 Changeset detected

Latest commit: 030d9a3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@stainless-code/codemap	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Warning

Review limit reached

@SutuSebastian, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 46 minutes and 52 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8cc301ef-6135-41a3-b6e2-8c23d2cac076

📥 Commits

Reviewing files that changed from the base of the PR and between 98e0b3f and 030d9a3.

📒 Files selected for processing (12)

• .changeset/mcp-tool-annotations.md
• docs/agents.md
• docs/architecture.md
• docs/plans/apply-write-safety.md
• docs/plans/mcp-tool-annotations.md
• docs/roadmap.md
• src/application/http-server.test.ts
• src/application/mcp-server.test.ts
• src/application/mcp-server.ts
• src/application/mcp-tool-annotations.test.ts
• src/application/mcp-tool-annotations.ts
• templates/agent-content/skill/10-recipes-context.md

📝 Walkthrough

Walkthrough

This PR introduces tool annotation metadata—read-only, destructive, and idempotent hints—that inform MCP and HTTP clients about tool safety semantics. A new MCP_TOOL_ANNOTATIONS mapping defines expected hints per tool, which are then exposed in both MCP tools/list responses and HTTP GET /tools endpoints.

Changes

Tool Annotations Across MCP and HTTP

Layer / File(s)	Summary
Annotation contract and metadata mapping src/application/mcp-tool-annotations.ts	Defines CodemapToolAnnotationHints interface and populates MCP_TOOL_ANNOTATIONS with per-tool hint values (readOnlyHint, destructiveHint, idempotentHint).
Annotation lookup and HTTP catalog entry builder src/application/mcp-tool-annotations.ts	Implements getMcpToolAnnotations(name) to retrieve hint metadata, and buildHttpToolCatalogEntry(name) to construct HTTP catalog entry objects with annotation fields.
Annotation contract validation tests src/application/mcp-tool-annotations.test.ts	Validates that all tools have annotations defined, confirms expected hints for tool categories (read-only query tools, destructive apply tools), and verifies HTTP catalog entries reflect annotation values.
MCP server tool registration with annotations src/application/mcp-server.ts, src/application/mcp-server.test.ts	Imports annotation lookup, introduces withToolAnnotations helper, wraps each tool registration config to attach optional annotations metadata, and adds test coverage for annotation exposure in MCP listTools() response.
HTTP server tool catalog with annotations src/application/http-server.ts, src/application/http-server.test.ts	Updates /tools endpoint to map tool names through buildHttpToolCatalogEntry, refactors tool allowlist to use centralized MCP_TOOL_NAMES, and validates hint fields in HTTP responses.
User documentation and templates docs/agents.md, templates/agent-content/skill/10-recipes-context.md	Documents advisory hint fields in MCP and HTTP /tools responses, clarifying which tools are read-only versus destructive.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• stainless-code/codemap#35: Scaffolds the MCP server and initial tool taxonomy that this PR extends with per-tool annotation hint metadata.
• stainless-code/codemap#39: Adds individual MCP tools (show, snippet) to the registry that this PR now augments with consistent annotation metadata wiring.
• stainless-code/codemap#133: Extends MCP_TOOL_NAMES and the HTTP tool catalog infrastructure that this PR now enhances with per-tool annotation hints.

Poem

🐰 Annotations hop through tools so bright,
Read-only here, destructive there—oh my!
Hints guide the way with gentle might,
Safe choices bloom, no surprise! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main feature: adding ToolAnnotations hints to both MCP tools/list and HTTP GET /tools endpoints.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/mcp-tool-annotations

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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