feat: Add tool annotations based on HTTP method #258
Conversation
Add ToolAnnotations to generated MCP tools to improve AI assistant understanding of tool capabilities: - readOnlyHint: true for GET operations - destructiveHint: true for DELETE operations - openWorldHint: true for all operations (external API calls) - title: set to the operation ID This enables AI assistants to make better decisions about tool usage safety and impact on external systems. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
Curious how this compares to #253 which has more flexibility in how hints can be applied. |
horus-bot
left a comment
horus-bot
left a comment
There was a problem hiding this comment.
Consider adding destructiveHint=True for PUT/POST/PATCH methods as well, since they can also modify or create resources.
Per MCP spec, destructiveHint indicates a tool MAY perform destructive updates. POST/PUT/PATCH methods modify or create resources, so they should be marked destructive alongside DELETE. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
Great question! These two approaches are complementary:
Ideal outcome: Both PRs merge, with explicit annotations (PR #253) taking precedence over defaults (PR #258). This gives developers the best of both worlds:
For example, a POST endpoint that's actually idempotent (returns cached result) could use There will be a merge conflict since both PRs touch the same code block, but the resolution is straightforward - use explicit annotations when available, fall back to HTTP method defaults otherwise. Also addressed @horus-bot's review feedback: expanded |
Per MCP spec, destructiveHint should only be true for operations that DELETE or DESTROY data, not for all write operations. - POST (create) → destructiveHint: false (additive) - PUT (update) → destructiveHint: false (modifies, doesn't destroy) - PATCH (partial update) → destructiveHint: false (modifies, doesn't destroy) - DELETE → destructiveHint: true (actually destroys data) Also added idempotentHint for GET, PUT, and DELETE operations. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Fix: Corrected destructiveHint SemanticsUpdated to properly distinguish between additive and destructive operations per the MCP spec. Previous (Incorrect)destructiveHint=(method in ("post", "put", "patch", "delete"))Now (Correct)destructiveHint=(method == "delete"), # Only DELETE destroys data
idempotentHint=(method in ("get", "put", "delete")), # GET, PUT, DELETE are idempotentSemantic Meaning
Per MCP spec: |
4 participants
Summary
Add MCP tool annotations to generated tools to improve AI assistant understanding of tool capabilities:
readOnlyHint: truefor GET operationsdestructiveHint: truefor DELETE operationsopenWorldHint: truefor all operations (they call external APIs)titleset to the operation IDMotivation
Tool annotations are an MCP spec feature (available since SDK 1.8.0) that help AI assistants make better decisions about tool usage. For example:
readOnlyHinttells the AI a tool won't modify any datadestructiveHintwarns the AI a tool may destroy resourcesopenWorldHintindicates the tool interacts with external systemsSince fastapi_mcp generates tools from HTTP endpoints, we can automatically derive these annotations from the HTTP method, giving all downstream users better tool metadata.
Changes
Single file change in
fastapi_mcp/openapi/convert.py:ToolAnnotationscreation based on HTTP methodToolconstructorTest plan
🤖 Generated with Claude Code