feat: Add tool annotations for improved LLM tool understanding

[bryankthompson]

Summary

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

Changes

• Added readOnlyHint: true to read-only tools (queries, extractions)
• Added idempotentHint: true to deterministic operations
• Added destructiveHint: true to cache_clear (permanently deletes files)
• Added human-readable title annotations to all tools

Tool Annotation Summary

Tool	Title	ReadOnly	Destructive	Idempotent
extract_file	Extract File	✓	-	✓
extract_bytes	Extract Bytes	✓	-	✓
batch_extract_files	Batch Extract Files	✓	-	✓
detect_mime_type	Detect MIME Type	✓	-	✓
cache_stats	Cache Stats	✓	-	✓
cache_clear	Clear Cache	-	✓	-

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 can auto-approve read-only operations and warn on destructive ones

Testing

• Server builds successfully (cargo build --package kreuzberg)
• Format check passes (cargo fmt --check)
• MCP-related tests pass
• Live verification: Started server and confirmed tools/list returns annotations
• Annotation values match actual tool behavior

Before/After

Before:

{
  "name": "extract_file",
  "description": "Extract content from a file..."
}

After:

{
  "name": "extract_file",
  "description": "Extract content from a file...",
  "annotations": {
    "title": "Extract File",
    "readOnlyHint": true,
    "idempotentHint": true
  }
}

🤖 Generated with Claude Code