ctx-sys has clear tool naming and structured schemas, but suffers from several definition gaps. All 5 tools are explicitly registered with names, descriptions, and input schemas in src/mcp/tool-registry.ts. Tool names are action-oriented (project, entity, index, graph, context_query), though not all follow strict verb_noun convention. Descriptions are present and moderately detailed (60-200 chars), but lack specific guidance on when to use each tool vs. alternatives. Parameter descriptions are generally present but vary in completeness, some parameters (e.g., 'depth' in index tool) lack specifics about range, format, or valid values. Output schemas are NOT documented in the source code, the handler implementations return results, but the expected response structure is not declared in tool definitions. Error handling logic is minimal; handlers throw generic errors without recovery guidance. The entity, index, graph, and context_query tools use polymorphic 'action' enums to combine multiple operations, increasing parameter complexity and reducing clarity.

• Document output schema for each tool. Add an 'outputSchema' field to the Tool interface and declare expected response fields and types. E.g., project.list should return {projects: [{name, path, lastIndexed, isActive}], activeProject}.
• Split polymorphic tools into single-action tools or add detailed per-action parameter documentation. Rather than one 'entity' tool with action={add|get|search|delete}, consider create_entity, get_entity, search_entities, delete_entity. If consolidation is preferred, add a 'Parameters by action' section to the description clarifying which fields apply where.
• Add constraints to all parameters. For each parameter, specify: type (already present), enum values (if applicable), min/max ranges (for numbers), length limits (for strings), format patterns (for dates, IDs, etc.). E.g., 'limit: number (1-100, default 10)', 'depth: string enum of [shallow|medium|deep]'.
• Rename tools to start with action verbs. 'project' → 'manage_project' (or split); 'entity' → 'manage_entity'; 'index' → 'index_code'; 'graph' → 'query_graph'; 'context_query' → 'search_context' or 'retrieve_context'. Verify tool names match the LLM's mental model of 'what action does this take?'
• Enhance descriptions with LLM-optimized context. Add 1 - 2 sentences explaining: (1) what domain does this tool operate on? (2) when should the LLM call this vs. similar tools? E.g., 'search_entities finds code symbols and documents matching a query. Use this to discover relevant code before viewing its full content with get_entity.' Current descriptions list actions but lack guidance.