Graphia demonstrates solid tool design with 12 well-named, action-oriented tools (all start with verbs: search_, get_, find_, analyze_). All tools have descriptions (avg ~100 chars, within baseline 34-392 range) and complete JSON Schema input definitions with typed parameters. However, output schemas are entirely undocumented, LLMs cannot predict response structure for planning. Parameter descriptions are present but terse (avg ~50 chars vs baseline 72). No error handling guidance visible in tool definitions. Missing tool annotations (readOnlyHint, destructiveHint). All tools are READ_ONLY by design, which is appropriate but should be formally declared.

• Document output schemas for all 12 tools. For each, specify the response structure: e.g., graphia_search_symbol returns {results: [{symbol: string, kind: string, file: string, score: number}], total: number}. This enables LLMs to plan multi-step queries.
• Add tool annotations to input schemas. Set 'readOnlyHint': true for all tools (they are all read-only). This signals to agents that these tools are safe to retry and do not modify state.
• Expand parameter descriptions to 80-150 chars. E.g., 'depth' in graphia_find_callers should read: 'Call graph traversal depth. Depth 1 returns direct callers; depth 2 includes callers of callers. Default: 1. Max: 20.'
• Add error handling guidance to tool descriptions. E.g., graphia_get_symbol: 'If symbol not found, try graphia_search_symbol() with a partial name to discover the correct symbol.'
• Document pagination and result limits in descriptions. E.g., 'Returns up to 50 results by default. Use limit parameter to adjust (max 500). If more results exist, use offset or cursor-based pagination.' Currently, limit behavior is unclear.