feat: Add tool annotations for improved LLM tool understanding

[triepod-ai]

Summary

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

Changes

• Added readOnlyHint: true to aws_cli_help (documentation tool that only fetches help text)
• Added destructiveHint: true and openWorldHint: true to aws_cli_pipeline (executes AWS CLI commands that can create/modify/delete resources)
• Added title annotations for human-readable display

Why This Matters

• Annotations provide semantic metadata that helps LLMs understand tool behavior
• LLMs can make better decisions about when to use tools and in what order
• Enables safer tool execution by distinguishing read-only from destructive operations
• MCP clients like Claude Code can auto-approve read-only tools without user confirmation

Testing

• uv sync - dependencies install successfully
• uv run ruff check src/ - linter passes
• Module imports successfully
• Verified annotations are registered correctly via Python introspection:

  aws_cli_help: title='AWS CLI Help' readOnlyHint=True
  aws_cli_pipeline: title='AWS CLI Pipeline' destructiveHint=True openWorldHint=True
  

• Note: Live server verification requires AWS CLI installation

Before/After

Before:

@mcp.tool()
async def aws_cli_help(...):
    # No annotations

After:

@mcp.tool(
    annotations=ToolAnnotations(
        title="AWS CLI Help",
        readOnlyHint=True,
    ),
)
async def aws_cli_help(...):

🤖 Generated with Claude Code