Server provides 13 tools with consistent naming (verb_resource pattern), documented descriptions, and schemas. However, several critical gaps limit production readiness: (1) no input validation or error handling guidance visible in source; (2) parameters lack format constraints (e.g., document_id description does not specify expected format); (3) output schemas are not formally documented in tool definitions; (4) no indication of pagination cursors or continuation tokens for large result sets; (5) destructive tool (mendeley_delete_document) lacks confirmation/dry-run pattern. Tool naming is strong (search_, get_, list_, create_, add_, remove_, update_, delete_) and descriptions are present but generic (avg ~100 chars, below production baseline of 194 chars). Schema completeness is mixed: parameters have types and basic descriptions, but lack constraints, ranges, and format specifications critical for LLM reasoning.
Tools (13)
mendeley_add_catalog_documentwriteauth50/100
Add a document from the Mendeley catalog to your library.
Parameter descriptions lack format specifications and constraints. 'document_id' and 'folder_id' descriptions do not specify format, length, or valid character sets, forcing LLMs to guess.
Output schemas not formally documented. Tool descriptions reference returned fields but do not provide JSON Schema definitions for LLM composition. format_document() in code returns dict but LLM has no schema visibility.
mendeley_search_librarymendeley_get_document
Recommendations
Add confirmation/dry-run step to mendeley_delete_document. Implement a 'dry_run' boolean parameter that returns what would be deleted without committing the deletion, or require explicit 'confirm=true' parameter.
Expand parameter descriptions with format constraints. For document_id and folder_id parameters, specify: format (hex string, UUID, alphanumeric), expected length, and valid character set. Example: 'document_id (string): The Mendeley document UUID (format: hex string, 36 characters).'
Document output schemas explicitly in tool definitions. Add a 'returns' section to each tool description listing JSON structure. Example for mendeley_get_document: 'Returns object with fields: id (string), title (string), authors (array of objects), year (integer), abstract (string), keywords (array), tags (array), has_pdf (boolean), citation (string).'
Implement pagination cursors. Add optional 'next_cursor' parameter and include 'total_count' and 'next_cursor' in search/list responses. Clarify: 'Returns up to N results. If more exist, use next_cursor to fetch the next batch.'
Enhance error messages with recovery guidance. Update error responses to follow pattern: '[ErrorCode] Brief message. Action: [retry / lookup alternative / ask user / none].' Example: 'DocumentNotFound. Action: Call mendeley_search_library to find documents by title or author.'
Expand tool descriptions to 150-250 chars. Include WHEN to use each tool and distinguish from similar tools. Example for search_library vs search_catalog: 'Search your personal library (use when looking for documents you have already imported). To find new papers to add, use mendeley_search_catalog instead.'
Score history
Overall score trend
↑ 15 points across a rubric change (v1 → v2)
61/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
C
61
2025-06-18+
v2
2026-03-09
F
46
-
v1
50/100
Get all documents in a specific Mendeley folder/collection with their metadata.
mendeley_get_pdfread onlyauth50/100
Download and extract text from a document's PDF, or embed the PDF file itself if it is not too large.
Search the authenticated Mendeley library by title, authors, abstract, or notes and return concise document metadata, citation text, and PDF availability.
No error handling guidance visible. Source shows error responses as JSON strings but does not guide LLM on recovery actions (retry, lookup alternative, ask user).
Pagination not clearly handled. Search and list tools accept 'limit' but no visible 'offset', 'page', or 'next_cursor' support. Large result sets risk context window overflow.
Tool descriptions are generic and brief (avg ~60-75 chars). Baseline for production tools is 194 chars. Descriptions do not explain WHEN to use each tool vs alternatives (e.g., when to call search_library vs search_catalog).
No tool annotations visible (readOnlyHint, destructiveHint, idempotentHint). Server declares risk levels in metadata but MCP tool definitions lack formal annotations required by current spec.
Add tool annotations to MCP tool registration. Implement readOnlyHint=true for read-only tools (search, get, list), destructiveHint=true for delete_document, and idempotentHint=true for get/search tools. This informs clients about tool safety profile.
Add validation examples to descriptions. For parameters accepting specific formats, include inline validation guidance. Example: 'limit (integer): Maximum results to return (1-100, default 20). LLM will adapt to API limits if a higher value is requested.'
Clarify idempotency and retry behavior. Document which tools are safe to retry (all read-only + get) vs which may have side effects on retry (create, add, update). State clearly: 'This tool is idempotent, calling it multiple times with same inputs produces same result.'
Return result metadata for chaining. Ensure search/list responses include sufficient IDs for downstream calls. If mendeley_get_folder_documents returns documents, each should include document_id and folder_id so agent can immediately call mendeley_remove_document_from_folder.