The RAG Document Server has 8 tools with consistent naming patterns (verb_noun structure: query_documents, upload_document, list_documents, delete_document, get_document_info, get_stats, generate_response, clear_all_data). All tools have descriptions (10-150 chars, within baseline range). However, there are critical gaps: (1) Parameter descriptions are present but often generic ('The question to search for' without context on expected format or length). (2) Output schemas are not formally documented, the code returns Dict[str, Any] with ad-hoc fields like 'success', 'results', 'error'. The actual response structure cannot be reliably inferred by an LLM planning downstream tool calls. (3) No enum constraints on the 'citation_style' parameter in generate_response (should be enum: 'inline', 'numbered', 'academic'). (4) Destructive operations (delete_document, clear_all_data) lack confirmation/dry-run patterns and do not guide recovery. (5) Error handling returns 'success: False' with an error message, but does not categorize errors as retryable, user-fixable, or fatal. (6) No pagination support on list_documents despite potential for large result sets. (7) Tool descriptions do not explain when to use query_documents vs generate_response (both answer questions but with different outputs, the distinction is unclear). (8) The upload_document 'force' parameter defaults to false, which is safe, but lacks explanation of what 'duplicate detection' means.

• Add formal JSON Schema output specifications for all tools. Document every field in the response object, its type, and meaning. Example: 'Returns: {success: bool, results: [{document_id: string, title: string, score: float, snippet: string}], query: string}'
• Implement confirmation-request pattern for destructive tools. Before executing delete_document or clear_all_data, return {input_required: true, confirmation_prompt: 'Delete document ABC? This cannot be undone.'} and wait for user confirmation via tool parameter.
• Constrain citation_style to an enum: ['inline', 'numbered', 'academic']. Remove free-form string; validate input and return error if not in set.
• Add pagination to list_documents: accept 'limit' (default 20, max 100) and 'offset' or 'cursor'; return 'next_cursor' if more results exist.
• Enhance error messages with recovery guidance. Example: 'Document not found: ABC. Call list_documents() to see available documents, or query_documents(question) to search by content.'
• Differentiate query_documents vs generate_response in their descriptions. Example: 'query_documents: Returns raw search results (documents matched by similarity). Use this for discovery or when you need the source documents. generate_response: Returns an LLM-synthesized answer with citations. Use this for end-user-facing answers.'
• Add parameter constraints to descriptions: 'limit: Maximum results (1-100, default 5)', 'file_path: Absolute or relative path to PDF, TXT, or DOCX file.'
• Implement error classification in responses. Return {success: false, error: 'Document not found', error_type: 'not_found', recovery: 'Call list_documents() to find valid IDs'} instead of generic error strings.

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

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