Clangaroo provides 19 C++ analysis tools with consistent naming patterns (cpp_* prefix, verb-noun structure) and detailed descriptions. All tools have input schemas with proper typing. However, output schemas are largely undocumented, error handling lacks recovery guidance, and descriptions, while present, do not systematically address 'when to use this vs. similar tool' or prerequisites. The server mixes read-only and write operations (cpp_format_file, cpp_rename_symbol) without destructive operation warnings or confirmation patterns. AI-powered tools (cpp_analyze_with_ai, cpp_analyze_call_patterns) lack token/cost guidance. Parameter descriptions are generally adequate but could be more prescriptive about formats and constraints. Missing pagination for potentially large result sets (e.g., cpp_find_references, cpp_get_workspace_symbols).

• Document output schemas for all 19 tools. Include field names, types (string, number, array), and nested structure. Example: 'Returns {files: string[], count: number, filter_pattern: string}'. This is CRITICAL for LLM chaining.
• Add destructiveHint=true and a confirmation/dry-run step to cpp_format_file and cpp_rename_symbol. Example: 'This modifies source files. Call with dry_run=true first to preview changes.'
• Implement pagination for result-heavy tools: add 'limit' (default 20, max 100) and 'offset' params to cpp_find_references, cpp_get_workspace_symbols, cpp_get_document_symbols. Return total_count and has_more in output.
• For cpp_analyze_with_ai and cpp_analyze_call_patterns, document expected latency, token cost, and when each context_level is appropriate. Example: 'minimal = <1s, full = 5-10s for large functions. Use minimal for quick checks.'
• Clarify parameter constraints in descriptions. E.g., 'pattern: Optional glob pattern (e.g. *.cpp, src/**/*.h). If omitted, lists all C++ files.' Use enum for analysis_type and context_level enums if available.
• Add recovery hints to error-prone tools. E.g., cpp_get_definition description: 'If the symbol is not found, try cpp_get_workspace_symbols with the symbol name, then use the returned file/line coordinates.'
• Adopt MCP 2026-07-28 patterns: add tool annotations (readOnlyHint, destructiveHint, idempotentHint) to tool definitions to let clients apply UI hints and safety checks. Mark all read-only tools with readOnlyHint: true.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry