AstraMap exposes 10 read-only code analysis tools via STDIO. Tool names lack action verbs (search, overview, functions, module, data, node, callers, callees, impact, status). Descriptions are present but minimal (10-80 chars, well below the 194-char baseline). Input schemas are visible and typed, but parameter descriptions are sparse or missing entirely. No output schemas documented. No error handling guidance. No pagination support despite tools returning potentially large result sets (e.g., functions, callers). Tools are narrowly scoped (good) but descriptions do not explain WHEN to use each tool or how they compose. No tool annotations (readOnlyHint, etc.). Overall: functional but well below production quality.

• Rename tools to verb_noun pattern: 'get_overview', 'list_functions', 'get_graph_data', 'get_node_details', 'get_status'. This enables LLMs to infer intent from names alone.
• Expand descriptions to 100-200 chars. For each tool, answer: What does it do? When should I call it instead of a similar tool? What structure does it return? Example: 'Get all functions in the codebase. Use this to discover entry points before analyzing call chains. Returns array of {id, name, kind, file, line}.'
• Document output schemas for all tools. Specify field names, types, and whether arrays are paginated. Include example responses in comments or a separate schema file.
• Add pagination support: accept 'limit' (default 20, max 100) and 'offset' or 'cursor' parameters. Return 'total_count' and 'next_cursor' in responses. Cap results at 50 items by default.
• Add tool annotations: mark all tools with readOnlyHint=true since they are read-only. This helps agents understand they are safe to retry and do not modify state.