ZotMCP provides 3 read-only tools with clear, descriptive names and documented schemas. All tools follow verb_noun naming conventions (semantic_search, get_document_full_text, get_document_metadata). Descriptions are present and functional (75-150 chars each), meeting the 10-1024 char baseline. Input parameters have types and descriptions. However, output schemas are not explicitly documented in the source code, only inferred from implementation context. The tools lack structured error handling guidance, missing the 'recovery guide' pattern. No tool annotations (readOnlyHint, etc.) are present despite tools being strictly read-only. Parameter descriptions could be more detailed about expected formats and constraints. No information about pagination for semantic_search results despite accepting max_results (potentially returns large lists). Overall above-average for a small utility server but with room for production-grade hardening.

• Document output schemas for all three tools. Specify: for semantic_search, return [{document_id, title, authors, publication_year, similarity_score, preview_text}]; for get_document_full_text, return {document_id, full_text, size_bytes}; for get_document_metadata, return {document_id, title, authors, doi, url, zotero_key, zotero_url, tags, publication_date}.
• Add recovery guidance to error responses. In get_document_full_text and get_document_metadata handlers, catch DocumentNotFound and respond: 'Document ID "<id>" not found in ChromaDB. Try semantic_search("<approximate topic>") to find the correct document_id.'
• Add tool annotations in FastMCP registration: @tool(readOnlyHint=true) for all three tools, signaling safety for agents.
• Enhance semantic_search description with pagination guidance: 'Returns up to max_results (default 10, max 100) documents ranked by semantic similarity. For large result sets, use offset parameter to paginate through results.'
• Add numeric bounds and format details to parameter descriptions. Query: 'Natural language search query (1-500 characters, ASCII). Semantic meaning matters, "transformer models" works better than single words.' max_results: 'Maximum results to return (integer, 1-100, default 10). Higher values increase latency and token cost.'
• Document the ChromaDB dependency and startup failure modes. If ChromaDB is not initialized, return: 'ChromaDB not initialized. Ensure /chromadb volume is mounted and sync-chromadb.sh has completed.'
• Consider adding a helper tool like list_available_documents() or describe_library() to help agents discover what's available before searching, reducing blind searches.

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

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