A Rails-based MCP server for managing personal book libraries and wishlists, with support for photo processing and book search via Claude integration
BibliotecAI defines 7 tools with basic schemas and descriptions, but exhibits significant gaps in parameter documentation, output schema clarity, and error handling guidance. Tool names follow verb_noun convention (list_, search_, add_, remove_, process_) which is good. However, most parameter descriptions lack detail on constraints, formats, and valid ranges. Output schemas are not documented, LLMs cannot predict response structure. Error handling is minimal; tools return generic {ok: false, error: "..."} without recovery guidance. The fixture executor reveals tool behavior but does not constitute production-grade documentation.
Add a book to the user's wishlist with optional author information
List all libraries owned by the authenticated user
List all items in the user's book wishlist
Process a book cover photo with specified intent (e.g., 'wishlist')
Process a photo of a book shelf to extract and catalog books
Remove an item from the user's wishlist by item ID
Output schemas not documented. LLMs cannot predict response structure (e.g., search_books returns array of {book_id, title, author, published_year, library_id, library}; add_to_wishlist returns {ok, item_id, deduped, title, author}). Without documented output schemas, agents cannot plan downstream tool calls or extract required fields reliably.
Parameter descriptions lack constraint details. 'limit' in search_books says 'Maximum number of results to return (default 5, max 20)' but does not specify minimum (1?) or whether 0 is valid. 'intent' in process_book_cover_photo has no enum or valid values listed. LLMs will guess or pass invalid values.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 52 | 2026-07-28+ | v2 |
Search for books in the user's libraries by title or author
Error handling provides no recovery guidance. Errors return {ok: false, error: "..."} with no actionable next steps. E.g., 'not found' for remove_from_wishlist does not suggest checking list_my_wishlist first or clarifying the item_id. Agents cannot self-correct.
process_book_cover_photo and process_shelf_photo have vague descriptions and unclear input/output contracts. 'Process a book cover photo with specified intent' does not explain what 'intent' means, what formats are accepted, or what the response contains. These tools appear to accept file uploads but no file parameter is defined.
Destructive tool (remove_from_wishlist) lacks confirmation or dry-run support. Agents can delete wishlist items without a confirmation step, risking accidental data loss. No idempotent hint or retry guidance provided.