An MCP server that provides tarot card drawing and deck management capabilities, with support for drawing random cards, retrieving the full deck, and fetching base64-encoded card images
The Tarot MCP Server defines 3 tools with clear, actionable names (draw_cards, get_full_deck, fetch_images). All tools have descriptions and explicit JSON Schema input definitions visible in TarotServerHandler.swift. However, several definition quality gaps prevent a higher score: (1) Parameter descriptions are minimal or absent, 'count' has a brief description but lacks guidance on when to use which count; (2) Output schemas are undocumented, responses are returned as JSON text via CallTool.Result but the structure (CardResponse with 'name' and 'imageURI' fields) is not declared in tool metadata; (3) Error messages lack recovery guidance, TarotCardError.invalidCardCount and file-not-found errors are raised but do not guide the LLM on what to do next; (4) Tool composition is sound (each tool has one responsibility) and naming follows verb_noun convention, which is a strength.
Draw one or more tarot cards
Fetch base64-encoded images for the given tarot card URIs
Get all 78 tarot cards in the deck
Output schemas are not documented. Tools return JSON (CardResponse, image base64) but the structure is not declared in tool metadata. LLMs cannot plan downstream operations or validate the shape of responses.
Parameter descriptions are incomplete or too terse. 'count' in draw_cards only states the range (1-78) but does not explain when to use small vs large counts, or what the trade-offs are (token cost, interpretation complexity). 'uris' in fetch_images describes the array but lacks guidance on how many URIs are safe to fetch in one call.
Error handling lacks recovery guidance. TarotCardError.invalidCardCount and file-not-found errors are raised, but responses do not guide the LLM on corrective actions (e.g., 'Try a smaller count' or 'Verify the URI matches the pattern').
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 56 | <=2025-11-25 | v2 |
Tool descriptions lack context on when to call each tool. 'Draw one or more tarot cards' and 'Get all 78 tarot cards' are clear, but descriptions do not explain the trade-off: when should an agent call draw_cards vs get_full_deck? (e.g., 'Use draw_cards for sampling insights; use get_full_deck for exhaustive analysis.').
fetch_images has a regex pattern constraint on URIs but does not document allowed values or provide examples in the description. LLMs may struggle to construct valid URIs without examples or an enum.