feat: Add tool annotations for improved LLM tool understanding

[triepod-ai]

Summary

Adds MCP tool annotations (readOnlyHint, destructiveHint, title) to all tools to help LLMs better understand tool behavior and make safer decisions about tool execution.

Changes

• Bump MCP SDK dependency from >=1.5.0 to >=1.8.0 (required for annotation support in FastMCP)

• Add ToolAnnotations import from mcp.types

• Add readOnlyHint: true to 8 read-only tools:

  Tool	Description
  list_schemas	Lists database schemas
  list_objects	Lists objects in a schema
  get_object_details	Shows detailed info about objects
  explain_query	Explains SQL query execution plans
  analyze_workload_indexes	Analyzes queries and recommends indexes
  analyze_query_indexes	Analyzes specific queries for indexes
  analyze_db_health	Checks database health
  get_top_queries	Reports slow/resource-intensive queries

• Add execute_sql tool with mode-aware annotations:

  • UNRESTRICTED mode: destructiveHint: true (can modify data)
  • RESTRICTED mode: readOnlyHint: true (read-only queries)

• Add title annotations for human-readable tool names

Why This Matters

• Annotations provide semantic metadata that helps LLMs understand tool behavior
• readOnlyHint tells the LLM a tool is safe to call without side effects
• destructiveHint signals the LLM should be more careful before executing
• title provides human-readable names for better UX
• MCP clients (Claude, ChatGPT) use these annotations to determine when to skip confirmation prompts

Testing

• Server builds successfully with uv sync
• Module imports correctly (from postgres_mcp.server import mcp)
• All 8 tools show correct annotations via mcp._tool_manager._tools
• Ruff linting passes
• Pyright type checking passes (0 errors)

Before/After

Before:

@mcp.tool(description="List all schemas in the database")
async def list_schemas() -> ResponseType:

After:

@mcp.tool(
    description="List all schemas in the database",
    annotations=ToolAnnotations(
        title="List Schemas",
        readOnlyHint=True,
    ),
)
async def list_schemas() -> ResponseType:

Compatibility

This PR bumps the minimum MCP SDK version from 1.5.0 to 1.8.0. The ToolAnnotations parameter in @mcp.tool() decorator was added in later SDK versions.

---

🤖 Generated with Claude Code