feat: Add tool annotations based on HTTP method

[triepod-ai]

Summary

Add MCP tool annotations to generated tools to improve AI assistant understanding of tool capabilities:

• readOnlyHint: true for GET operations
• destructiveHint: true for DELETE operations
• openWorldHint: true for all operations (they call external APIs)
• title set to the operation ID

Motivation

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:

• readOnlyHint tells the AI a tool won't modify any data
• destructiveHint warns the AI a tool may destroy resources
• openWorldHint indicates the tool interacts with external systems

Since 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:

• Added ToolAnnotations creation based on HTTP method
• Passed annotations to the Tool constructor

Test plan

• All 89 existing tests pass
• 83% test coverage maintained

🤖 Generated with Claude Code

[parente]

Curious how this compares to #253 which has more flexibility in how hints can be applied.

[horus-bot]

Consider adding destructiveHint=True for PUT/POST/PATCH methods as well, since they can also modify or create resources.

[triepod-ai]

Great question! These two approaches are complementary:

• PR Add support for tool annotations via OpenAPI extensions #253 (yours): Explicit annotations via x-mcp-annotations - gives developers fine-grained control
• PR feat: Add tool annotations based on HTTP method #258 (this one): HTTP method-based defaults - provides sensible annotations with zero configuration

Ideal outcome: Both PRs merge, with explicit annotations (PR #253) taking precedence over defaults (PR #258). This gives developers the best of both worlds:

1. Out-of-the-box annotations for common patterns (GET=readOnly, POST/PUT/PATCH/DELETE=destructive)
2. Explicit override capability when default behavior doesn't match actual tool semantics

For example, a POST endpoint that's actually idempotent (returns cached result) could use x-mcp-annotations to override the default destructiveHint=True.

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 destructiveHint to include POST/PUT/PATCH methods (not just DELETE), since they can also modify or create resources.

[triepod-ai]

Fix: Corrected destructiveHint Semantics

Updated 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 idempotent

Semantic Meaning

Method	destructiveHint	Reason
GET	false	Read-only
POST	false	Creates (additive)
PUT	false	Updates (replaces, doesn't destroy)
PATCH	false	Partial update (doesn't destroy)
DELETE	true	Actually destroys data

Per MCP spec: destructiveHint means the tool may DELETE or DESTROY data, not just "writes data".