ProtocolBox provides 8 tools with complete input schemas and descriptions for all tools. Naming follows verb_noun conventions (heal_json, safe_math, remember, recall, scrape, web_search, get_time, get_transcript). However, descriptions are concise but lack LLM-optimized depth, they explain WHAT but not WHEN or WHY to use the tool. Parameter descriptions are present but minimal (typically 1 - 2 sentences). Output schemas are not documented in the source code. Error handling is basic, no recovery guidance or actionable error messages. The tools are well-composed and single-purpose, but descriptions fall short of production baselines (target 50 - 200 chars per description; these average ~80 chars, which is lean). No tool annotations (readOnlyHint, destructiveHint) despite clear read/write risk distinctions. The 'remember' tool has WRITE risk but no confirmation or dry-run pattern.

• Add tool annotations: use @mcp.tool(readOnlyHint=True) for read-only tools (heal_json, safe_math, recall, scrape, web_search, get_time, get_transcript) and @mcp.tool(destructiveHint=True) for remember. This signals tool intent to clients and helps LLMs plan.
• Document output schemas in tool docstrings. E.g., heal_json returns {'dict': {...}} on success or {'error': str, 'input_snippet': str} on failure. Include field types and whether results are paginated.
• Enhance error messages with recovery guidance. Instead of {'error': 'Failed'}, return {'error': 'Failed to repair JSON', 'reason': 'Syntax error at position X', 'suggestion': 'Check for unmatched braces or quotes'}. This guides the LLM toward self-correction.
• Expand tool descriptions to 100 - 200 chars. Current baseline ~80 chars. Add WHEN-to-use context and any required setup. E.g., 'Store a key-value pair in persistent memory (saved to ~/.protocolbox/memory.json). Use this for agent state that persists across sessions. Call recall(key) to retrieve stored values.'
• Add min/max bounds to numeric parameters. E.g., web_search max_results: integer, minimum 1, maximum 100. Describe get_time timezone enum or link to IANA timezone documentation.
• Implement a dry-run or preview mode for remember. E.g., add an optional 'dry_run' bool parameter; when true, return the data that would be stored without persisting it. This lets agents verify intent before modifying state.
• Add parameter cross-reference hints. E.g., 'After calling web_search, use scrape(url) to fetch the full content of promising results.' This surfaces tool chaining and reduces trial-and-error planning.