MCP server for NeoDB API integration - provides tools to search books, get book details, and retrieve user information from NeoDB catalog
This server has three tools with clear names and basic schemas, but suffers from critical gaps in parameter descriptions, output documentation, and error handling guidance. Tool names follow verb_noun conventions (get-user-info, search-books, get-book), which is good. However, parameter descriptions are minimal or absent, output schemas are completely undocumented, and error messages do not guide the LLM toward recovery. The server lacks pagination support despite search-books returning potentially large result sets. No tool annotations (readOnlyHint, idempotentHint) are present. Based on the rubric baseline of 194 chars for average tool description and 72 chars for params, these descriptions are short and lack context for LLM decision-making.
Get detailed information about a specific book
Get current user's basic info
Search items in catalog
Parameter descriptions are missing or trivial. 'Search query for books' is generic; should explain what queries are supported (title, author, ISBN?), format constraints, and example usage. LLMs cannot infer intent from bare parameter names.
Output schemas are completely undocumented. Tools return types.TextContent with formatted strings, but the LLM does not know what fields (username, title, rating, etc.) to expect in the response. This forces the LLM to parse unstructured output, increasing errors and wasting tokens.
Error handling does not guide recovery. When a request fails (e.g. 'Bad request' for search-books), the error message tells the LLM nothing. Should return: 'Invalid query format. Queries must be 1-500 characters and may include author, title, or ISBN. Try: search-books(query="The Great Gatsby")' to enable self-correction.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 54 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 42 | - | v1 |
search-books lacks pagination support. The code hardcodes page=1 and does not accept limit or offset parameters. If a search returns 100+ results, the entire response is dumped, wasting tokens and risking context window exhaustion. Should accept limit (default 20, max 100) and offset/next_cursor parameters.
Tool descriptions are under the baseline (194 chars) and lack key context. 'Get current user's basic info' does not explain when to call this tool instead of other user tools, what prerequisite (access_token) is required, or what fields are returned. Should be 50-150 chars, specific and actionable.
No tool annotations present. All three tools are read-only, but readOnlyHint is not declared. This prevents LLMs from optimizing request sequencing and caching. Should include 'readOnlyHint': true in tool metadata.
book_id parameter lacks description constraints. Is it a numeric ID, a UUID, or a slug? Should specify: 'The unique identifier of the book (e.g. "12345" or "isbn-978-0-13-110362-7"). Retrieve valid IDs via search-books.',
Response format is unstructured plain text. format_book() returns concatenated strings ('Title: ...\nAuthor: ...'), but the LLM expects structured JSON fields. Should return {'title': '...', 'author': '...', 'rating': ..., 'description': '...'} as a structured object so the LLM can reliably extract and reuse fields.