pi-codegraph wraps codebase-memory-mcp via STDIO. Tool definitions are visible in src/cli.js with names, descriptions, and input schemas. However, critical gaps undermine quality: (1) descriptions are terse (10-50 chars), below the 50-200 char LLM-optimized baseline; (2) parameter descriptions are minimal or absent (e.g., 'depth' in trace_path lacks guidance on valid range); (3) no output schemas documented, LLMs cannot predict response structure; (4) no error handling guidance, failures offer no recovery path; (5) no parameter constraints (enums, ranges, patterns) despite tools accepting free-form strings like 'query' in search_graph. The tool names follow verb_noun convention (get_, search_, trace_, detect_, list_) which is good, but descriptions fail to explain WHEN to use each tool or what distinguishes similar ones (e.g., search_graph vs get_code_snippet). No tool annotations (readOnlyHint, destructiveHint) despite clear risk levels. index_repository is marked WRITE but has no confirmation or dry-run pattern.

• Add output schemas to all tools. Document response fields, types, and whether results are paginated. E.g., search_graph should return {results: [{name, qualified_name, file, line}], total, next_cursor}.
• Expand parameter descriptions to 50-200 chars. For trace_path.depth, specify 'Depth of trace (1-10; deeper traces may timeout)'. For search_graph.limit, add 'Maximum results (1-100, default 20)'.
• Add tool-level descriptions explaining WHEN to use each tool and dependencies. E.g., 'Call index_repository first before any query. Use search_graph for keyword search; trace_path for call graphs; get_code_snippet for source code.'
• Implement error recovery guidance. Return structured errors with actionable hints: {error: 'Project not found', hint: 'Run index_repository first or check project name via list_projects'}.
• Add tool annotations (readOnlyHint, destructiveHint) to schema. Mark index_repository with destructiveHint=true; mark read-only tools with readOnlyHint=true. This helps agents reason about side effects.