mcp-rag-server defines 3 tools with reasonable descriptions and basic input schemas. All tools have names starting with action verbs (knowledge_base_search, web_search, ingest_document). Descriptions are present and provide context on when to use each tool (10 - 1024 character range). However, schemas lack formal type constraints (enums, ranges), parameter descriptions are minimal in JSON Schema form, and output schemas are not documented. Error handling is basic, tools return error strings but do not guide recovery or suggest next steps. The server implements pattern:tool and pattern:tool-description partially, but falls short on pattern:constrained-input and pattern:response-shaper. No tool annotations (readOnlyHint/destructiveHint) are present despite clear security distinctions (knowledge_base_search and web_search are READ_ONLY; ingest_document is WRITE with side effects).

• Add tool annotations to each tool: readOnlyHint=true for knowledge_base_search and web_search; idempotentHint=false, destructiveHint=true for ingest_document. This signals to LLMs which tools are safe to retry and which modify state.
• Add formal constraints to input schemas. Example: top_k should be {type: 'integer', minimum: 1, maximum: 50, description: 'Number of results to return (default: 10, max: 50).'}. filepath should include a pattern or enum for file extensions, and a description noting that only .md, .txt, .pdf are supported.
• Document output schemas formally. For knowledge_base_search, specify the response structure: array of objects with fields like {source: string, section?: string, page?: number, relevance: number, excerpt: string}. For ingest_document, return {document_id: string, title: string, chunks_indexed: number} so the LLM can reference the document in follow-up queries.
• Enhance error responses with recovery guidance. Replace 'Error: Knowledge base is not initialized.' with 'Error: Knowledge base failed to initialize. This is a server startup issue. Please check logs. Retry after server restart.' Categorize errors: 'This is a retryable error' vs 'This is a user error' vs 'This is a fatal server error.'
• Add pagination to knowledge_base_search. Accept optional offset and limit parameters (default offset=0, limit=20). Return {results: [...], total_count: number, offset: number, limit: number} so the LLM can iterate if needed.
• For ingest_document, return a document_id in the response so the LLM can tell users how to reference the newly ingested document in future searches. Example: 'Ingested document_id: abc123 with title: User Guide. 42 chunks indexed.' User can then say 'search for X in abc123' to narrow searches.