feat: Add tool annotations for improved LLM tool understanding

[bryankthompson]

Summary

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

Changes

• Added readOnlyHint: true to read-only tools (queries, fetches):

  • get_document, search_documents, download_document
  • list_tags, list_correspondents, list_document_types

• Added destructiveHint: true to tools that create/update/delete data:

  • bulk_edit_documents, post_document
  • create_tag, update_tag, delete_tag, bulk_edit_tags
  • create_correspondent, bulk_edit_correspondents
  • create_document_type, bulk_edit_document_types

• 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

• Server builds successfully (npm run build)
• Live verification: Started server and confirmed tools/list returns annotations
• All 16 tools have correct annotation values:
  • 6 read-only tools with readOnlyHint: true
  • 10 destructive tools with destructiveHint: true

Verification Output

Total tools: 16

Tool Name                      Title                     ReadOnly   Destructive
---------------------------------------------------------------------------
bulk_edit_documents            Bulk Edit Documents       N/A        True      
post_document                  Post Document             N/A        True      
get_document                   Get Document              True       N/A       
search_documents               Search Documents          True       N/A       
download_document              Download Document         True       N/A       
list_tags                      List Tags                 True       N/A       
create_tag                     Create Tag                N/A        True      
update_tag                     Update Tag                N/A        True      
delete_tag                     Delete Tag                N/A        True      
bulk_edit_tags                 Bulk Edit Tags            N/A        True      
list_correspondents            List Correspondents       True       N/A       
create_correspondent           Create Correspondent      N/A        True      
bulk_edit_correspondents       Bulk Edit Correspondents  N/A        True      
list_document_types            List Document Types       True       N/A       
create_document_type           Create Document Type      N/A        True      
bulk_edit_document_types       Bulk Edit Document Types  N/A        True

🤖 Generated with Claude Code

[lcrostarosa]

+1 to this @nloui using this in my local branch now