Skip to content

feat(tools): add safety annotations for tool compliance - #579

Merged
dcramer merged 5 commits into
mainfrom
add-mcp-tool-safety-annotations
Oct 23, 2025
Merged

dcramer merged 5 commits into
mainfrom
add-mcp-tool-safety-annotations

Conversation

@codyde

@codyde codyde commented Oct 22, 2025

Copy link
Copy Markdown
Contributor

Per feedback from Anthropic on MCP Safety Guidelines and policy to be in their registry, adding the tool safety annotations as follows -

  • Add readOnlyHint: true to tools that only read data without modification (such as authentication checks, listing operations, searching, and documentation retrieval)
  • Add destructiveHint: false to tools that perform only additive updates (such as creating teams, projects, and DSNs)
  • Explicitly set destructiveHint: true for tools that modify or update existing data (such as update operations)
  • Consider adding idempotentHint: true for operations that can be safely repeated with the same arguments

Ensure all 19 tools have appropriate safety annotations

  • Introduced safety annotations to all tools for MCP directory compliance, including readOnlyHint, destructiveHint, idempotentHint, and openWorldHint.
  • Updated relevant tools to include these annotations, ensuring clear communication of tool behavior and data modification capabilities.
  • Added documentation on required annotations and their usage patterns to docs/adding-tools.mdc.

- Introduced safety annotations to all tools for MCP directory compliance, including `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`.
- Updated relevant tools to include these annotations, ensuring clear communication of tool behavior and data modification capabilities.
- Added documentation on required annotations and their usage patterns to `docs/adding-tools.mdc`.
cursor[bot]

This comment was marked as outdated.

@codyde
codyde requested a review from dcramer October 22, 2025 07:34
cursor[bot]

This comment was marked as outdated.

Comment thread packages/mcp-server/src/tools/types.ts Outdated
codyde and others added 2 commits October 22, 2025 18:29
Resolved conflict in server.ts by:
- Keeping inline handler structure from main (cleaner code)
- Adding tool.annotations parameter as 4th argument to server.tool()
- Respecting main's removal of MCP client metadata fields (mcpClientName, mcpClientVersion, mcpProtocolVersion) per commit 96089be

The annotations feature adds MCP directory compliance by marking tools with:
- readOnlyHint: Tool doesn't modify data
- destructiveHint: Tool may modify/delete existing data
- idempotentHint: Repeated calls have no additional effect
- openWorldHint: Tool interacts with external services

Co-Authored-By: Claude Code <noreply@anthropic.com>
@dcramer
dcramer merged commit 68f6919 into main Oct 23, 2025
11 of 13 checks passed
@dcramer
dcramer deleted the add-mcp-tool-safety-annotations branch October 23, 2025 16:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants