feat: Add tool annotations for improved LLM tool understanding

[bryankthompson]

Summary

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

Changes

• Added from mcp.types import ToolAnnotations import
• Upgraded fastmcp requirement to >=2.0.0 for annotation support
• Added annotations to all 151 tools with:
  • title: Human-readable tool names (e.g., "Nmap Scan", "AI Vulnerability Assessment")
  • readOnlyHint=False: Tools actively interact with targets
  • destructiveHint=True: Security scanning/testing can impact targets
  • openWorldHint=True: All tools interact with external systems/networks

Why This Matters

• Safety Automation: MCP clients like Claude Code can auto-approve read-only tools and require confirmation for destructive ones
• Better Tool Selection: LLMs can understand tool characteristics for safer decision-making
• Human-Readable Titles: Improves tool discoverability and display in UIs

Tool Classification Rationale

All 151 tools are cybersecurity/pentesting tools that:

• Execute external security tools (nmap, gobuster, sqlmap, metasploit, etc.)
• Actively scan and interact with target systems
• Can impact target availability or state during testing

Therefore, all tools are marked with:

• destructiveHint=True - scanning can impact targets
• openWorldHint=True - tools access external networks/systems

Testing

• Python syntax validates: python3 -m py_compile hexstrike_mcp.py
• All 151 tools annotated (verified via grep count)
• Import statement added correctly

Example Before/After

Before:

@mcp.tool()
def nmap_scan(target: str, scan_type: str = "-sV", ...) -> Dict[str, Any]:

After:

@mcp.tool(
    annotations=ToolAnnotations(
        title="Nmap Scan",
        readOnlyHint=False,
        destructiveHint=True,
        openWorldHint=True,
    ),
)
def nmap_scan(target: str, scan_type: str = "-sV", ...) -> Dict[str, Any]:

---

🤖 Generated with Claude Code