Code System Graph exposes 8 tools with READ_ONLY risk classification and basic schemas. All tools have descriptions (10-100 chars, baseline 194), but most are terse and lack actionable context for LLM selection. Schemas are present but minimal: most parameters lack descriptions (baseline 72 chars per param). No tool annotations (readOnlyHint, idempotentHint). Naming follows verb_noun convention (search, trace, impact, explore, contracts, communities, changes, status) but descriptions do not explain WHEN to use each tool vs. similar ones (e.g., search vs. contracts both query entities). Error handling and recovery guidance are absent. Output schemas are not documented. No pagination guidance despite search/contracts accepting offset/limit.

• Expand tool descriptions to 100-200 chars. For search: 'Search ranked entities in the federated snapshot by text query. Returns top matches by relevance. Use this to find functions, types, or modules by name. For contract-only results, use contracts() instead.' This clarifies WHEN and WHY.
• Add parameter descriptions with constraints. E.g., 'limit: Maximum results per page (1-100, default 20). Larger limits may timeout.' For repo_ids: 'Optional array of repository identifiers to filter results (max 10 repos per call).'
• Document output schemas for each tool. E.g., search returns [{id, name, type, repo_id, score, ...}]. trace returns {path: [{node_id, label, type}], distance, ...}. This enables LLMs to chain calls and extract required fields.
• Add readOnlyHint: true to all tool schemas. This signals to agents that these tools are safe to retry and do not modify state.
• Add error recovery hints in descriptions. E.g., 'If trace returns no path, try increasing max_depth or verify from/to node IDs exist via search().' This guides LLM fallback strategies.