Single tool 'query_knowledge' has a well-structured description (180+ chars) explaining purpose, when to use it, and difficulty levels. Input schema is present with three parameters (question, difficulty, top_k), all with types and descriptions. However, the output schema is completely undocumented, the tool returns a dict with 'difficulty', 'seed_entities', 'entities', 'relations' fields, but this structure is never formally declared. The _format_context function shows the expected output shape, but LLMs cannot see implementation details. No error handling guidance, no recovery paths, no validation constraints on difficulty enum values. Parameter descriptions lack format/constraint details (e.g., top_k range, question length limits). Tool is read-only (safe), but lacks idempotent/readonly annotations. Overall: good naming and description, but missing critical output schema documentation and error handling.

• Add formal output schema documentation: declare the return type as an object with fields 'difficulty' (string), 'seed_entities' (array of {name, score}), 'entities' (array of {name, description, layer}), 'relations' (array of {head, relation, tail}). Include field descriptions and types.
• Add error handling guidance to tool description: 'If the knowledge graph is unavailable, returns error code GRAPH_UNAVAILABLE. If no results match the query, returns empty entities/relations arrays. If difficulty is invalid, returns error INVALID_DIFFICULTY with allowed values.'
• Constrain top_k parameter: add min=1, max=50 to schema and update description to 'Number of top results to return (1 - 50, default 10).'
• Convert difficulty description to a formal enum constraint in the schema: enum=['auto', 'entity', 'cluster', 'theme'] instead of relying on description text.
• Add tool annotations: mark as readOnlyHint=true and idempotentHint=true so LLMs know it is safe to call multiple times without side effects.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry