docs-mcp exposes 2 well-named, read-only documentation tools with clear descriptions and properly typed input schemas. Both tools follow verb_noun naming (search_docs, get_doc) and include descriptions sufficient for LLM tool selection. However, critical gaps prevent a higher score: (1) No documented output schemas visible in source, LLMs cannot infer the structure of search results or doc chunk responses, forcing them to guess downstream field names; (2) Parameter descriptions are minimal (e.g., 'query' lacks format guidance or examples of semantic vs lexical use); (3) No pagination parameters despite being a search tool likely to return many results; (4) Error handling not visible in source, no recovery guidance for failed searches or missing docs; (5) No input validation or constraint documentation (e.g., max query length, character restrictions). The tools are READ_ONLY and well-scoped but lack the production-grade details that prevent LLM mistakes.

• Add explicit output schema documentation for search_docs. Define: results (array of objects), each with fields: id, title, content, relevance_score, chunk_index. Include total_count and next_cursor (or offset) for pagination. Example: {"results": [{"id": "doc-123-chunk-5", "title": "Authentication", "content": "...", "relevance_score": 0.95, "chunk_index": 5}], "total_count": 42, "next_cursor": null}
• Add explicit output schema documentation for get_doc. Define: id, title, content, created_at, updated_at, url (if available), and any metadata fields the index stores.
• Add limit and offset/cursor parameters to search_docs. Constrain limit to 1 - 100 with default 20. Example: limit: {type: 'integer', description: 'Maximum number of results to return (1 - 100, default: 20)', minimum: 1, maximum: 100}, offset: {type: 'integer', description: 'Pagination offset (0-indexed)', minimum: 0, default: 0}
• Expand search_docs parameter descriptions. For 'query': '{type: 'string', description: 'Search query text. Use natural language for semantic search (e.g., "how to authenticate") or keywords for lexical search (e.g., "authentication bearer token"). Max 500 characters.', minLength: 1, maxLength: 500}'
• Expand get_doc parameter descriptions. For 'id': '{type: 'string', description: 'The unique identifier of the documentation chunk, typically formatted as doc-{name}-chunk-{number} or similar. Retrieve valid IDs from search_docs results.', pattern: '^[a-z0-9\-]+$'}'
• Document error responses and recovery guidance. Example: 'If search_docs returns zero results, try: (1) shorter query, (2) fewer keywords, (3) call with different search terms. If get_doc returns 404, the chunk may have been deleted, try search_docs to find current docs.'