Aurora-grimoire exposes a single search_docs tool with a reasonably complete input schema and a clear, action-oriented description. However, the tool lacks critical guidance on output structure, error handling, and recovery paths. The schema is present and parameters are typed, but descriptions for individual parameters are sparse or missing altogether. No documentation of what the tool returns, what fields to expect, or how to interpret confidence thresholds. Per-tool analysis follows.

• Document the output schema explicitly: 'Returns an object with fields: {results: [{source_url, source_url_with_anchor, content?, context?, relevance_score}], no_knowledge: boolean, search_duration_ms: number}. If no_knowledge is true, results will be empty.',
• Convert retrieval_mode and knowledge_threshold to explicit enum types in the JSON Schema input definition instead of embedding enum values in the description.
• Add a bounds constraint and default to top_k: 'Number of chunks to return (1 - 50, default 8). Limiting to 50 prevents token waste and latency.',
• Expand parameter descriptions: 'with_content: Include the full cleaned documentation text in each result (may be lengthy; use false for snippet-only mode)', 'with_context: Return LLM-optimized context segments with full cleaned content and source metadata for immediate use in prompt'.
• Add error handling guidance to the tool description: 'If no_knowledge is true, the documentation does not contain reliable information matching the query, suggest the user refine their question or check for typos. If the request times out, retry with a smaller top_k or simpler query.'
• Document how doc_version filtering works: 'If doc_version is specified and not found in the knowledge base, the tool returns no_knowledge=true. Valid versions are X.Y.Z format (e.g., 5.2.0). If omitted, all versions are searched.'
• Add clarity on rerank parameter: 'When true, rerank results by semantic relevance using a cross-encoder model (adds ~500ms latency). Default false.'