feat: Add tool annotations for improved LLM tool understanding

[bryankthompson]

Summary

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

Changes

• Added readOnlyHint: true to read-only tools:

  • search-content - Search recorded content
  • find-elements - Find UI elements (macOS)

• Added destructiveHint: true to tools that interact with the system:

  • pixel-control - Mouse/keyboard control
  • click-element - Click UI elements (macOS)
  • fill-element - Type text into elements (macOS)
  • scroll-element - Scroll elements (macOS)
  • open-application - Open applications
  • open-url - Open URLs in browser

• Added title annotations for human-readable display

• Bump MCP SDK dependency from unversioned to >=1.8.0 for annotation support

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
• readOnlyHint tools can be called freely for information gathering
• destructiveHint tools signal to LLMs that extra caution is warranted

Testing

• Dependencies install successfully (uv sync)
• Python syntax validation passes
• Tool annotations appear correctly in tools/list response
• Annotation values match actual tool behavior

Before/After

Before:

types.Tool(
    name="search-content",
    description="Search through screenpipe recorded content...",
    inputSchema={...}
)

After:

types.Tool(
    name="search-content",
    description="Search through screenpipe recorded content...",
    inputSchema={...},
    annotations=ToolAnnotations(
        title="Search Content",
        readOnlyHint=True,
    ),
)

🤖 Generated with Claude Code

[github-actions]

🧪 testing bounty created!

a testing bounty has been created for this PR: view testing issue

testers will be awarded $20 each for providing quality test reports. please check the issue for testing requirements.