feat: Add tool annotations for improved LLM tool understanding

[bryankthompson]

Summary

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

Changes

Command Service (1 tool)

• execute_command: Destructive (executes shell commands)

Browser Service (13 tools)

Tool	Classification
browser_navigate	Destructive (navigates browser)
browser_screenshot	Destructive (saves file to disk)
browser_click	Destructive (interacts with page)
browser_fill	Destructive (enters data)
browser_select	Destructive (changes selection)
browser_hover	Destructive (triggers events)
browser_evaluate	Destructive (executes JavaScript)
browser_debug_enable	Destructive (modifies debugger)
browser_set_breakpoint	Destructive (sets breakpoint)
browser_remove_breakpoint	Destructive (removes breakpoint)
browser_pause	Destructive (pauses execution)
browser_resume	Destructive (resumes execution)
browser_get_callstack	Read-only (observes state)

Filesystem Service (8 tools)

Tool	Classification
read_file	Read-only
list_directory	Read-only
search_files	Read-only
get_file_info	Read-only
list_allowed_directories	Read-only
write_file	Destructive
create_directory	Destructive
move_file	Destructive

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

• go build ./... passes
• All 22 tools annotated with appropriate hints
• Using existing mcp-go v0.29.0 annotation support (no SDK upgrade needed)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds MCP tool annotations to improve LLM understanding of tool behavior and enable safer tool execution. The annotations include title, readOnlyHint, and destructiveHint fields for all 22 tools across three services.

Key changes:

• Adds human-readable titles to all tools for better UI display
• Classifies tools as either read-only or destructive to guide LLM decision-making
• Enables MCP clients to potentially auto-approve read-only tools without user confirmation

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
pkg/services/filesystem/file_system.go	Annotates 8 filesystem tools (5 read-only: read_file, list_directory, search_files, get_file_info, list_allowed_directories; 3 destructive: write_file, create_directory, move_file)
pkg/services/command/command.go	Annotates execute_command as destructive with title "Execute Command"
pkg/services/browser/browser.go	Annotates 13 browser tools (1 read-only: browser_get_callstack; 12 destructive: navigation, interaction, and debugging tools)

The annotations are consistently applied and the read-only/destructive classifications are logically correct based on each tool's behavior. No issues were identified in the changes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.