Tarot MCP has 9 tools with present schemas and basic descriptions, but significant gaps in description depth, parameter documentation, and error handling guidance. All tools are read-only (low risk), but descriptions are generic and under the 50-200 char LLM-optimized range. Parameter descriptions exist but lack format guidance, constraints, or actionable context. No output schemas documented. Error responses are minimal, tools return null on failure without recovery guidance.
Tools (9)
daily_cardread onlysource verified57/100
Draw a single card for daily guidance
draw_cardsread onlysource verified67/100
Draw a specified number of tarot cards
get_card_meaningread onlysource verified67/100
Get detailed information about a specific tarot card
Missing output schemas for all tools. No documented return types visible in tool registration or code. LLMs cannot predict what fields to expect from responses, forcing unstructured output parsing and breaking tool chaining.
Descriptions are too generic and under 50 characters (baseline 50-200 for LLM optimization). Examples: 'List all available tarot spreads' (35 chars), 'Draw a single card for daily guidance' (38 chars). Missing context on WHEN to call, WHY the LLM should select this tool, and WHAT to expect.
Parameter descriptions lack actionable constraints. 'search_cards' query parameter has no guidance on format, min/max length, or expected keywords. 'draw_cards' count parameter states range (1-78) but no explanation of why that limit or common use cases.
Recommendations
Add explicit output schemas to all tool definitions in index.ts. For draw_cards, document: returns array of DrawCard objects with fields {card: TarotCard, position: string, isReversed: boolean}. For list_spreads, document: returns array of TarotSpread with {id, name, description, positions: array}.
Expand descriptions to 60-150 characters with LLM-friendly format: WHAT + WHEN + CONTEXT. Example: 'draw_cards: Draw N random tarot cards (1-78). Use for quick divination, or to seed a full reading. Returned cards include upright/reversed orientation.'
Add constraints and format hints to parameter descriptions. For search_cards query: 'Free-text search across card names, keywords, and descriptions. Examples: "love", "success", "conflict". Returns up to 20 matching cards.' For draw_cards count: 'Number of cards (1-78, default 1). Typical readings: 1 (daily card), 3 (past-present-future), 10 (Celtic Cross).'
Document interpret_reading's 'reading' parameter structure. Add: 'reading object returned from perform_reading with fields: id, timestamp, spread, question, cards (array of DrawCard). Do NOT construct manually; always use output from perform_reading.'
Add error handling to all tools. When cardName not found, return: '{error: true, message: "Card not found: ' + cardName + '. Try search_cards() for partial matches.", suggestions: [list of similar cards]}' instead of null. This lets LLM auto-correct.
Implement result limits. Cap list_all_cards to 20 results default with 'arcana' filter mandatory for full list. Cap search_cards to top 10 matches. Add 'total_available' count to enable agent pagination awareness.
interpret_reading accepts a complex 'reading' object parameter but no schema definition or guidance on structure. LLM must guess the required fields (card, position, isReversed, etc.) based on code inspection alone.
No error recovery guidance. Tools return null on failure (e.g., 'getCardMeaning' line 'return card || null') with no actionable error message. LLM receives null and has no hint to retry, use search_cards, or adjust input.
list_all_cards has optional 'arcana' enum parameter but description does not explain what each enum value means or when to use filtering. LLM may not realize major vs minor arcana distinction.
No result limits or pagination support. list_all_cards returns all 78 tarot cards without limit, list_spreads returns all spreads, search_cards returns all matches. Large uncapped lists waste context tokens and break agent reasoning when results are numerous.
list_all_cardslist_spreadssearch_cards
Clarify arcana enum meanings in description. For list_all_cards: 'arcana filter: major (22 symbolic cards, e.g. The Fool, Death), minor (56 cards, 4 suits), all (default, all 78). Use major/minor to focus readings on spiritual vs practical themes.'
Add relationship hints to multi-step patterns. For perform_reading description: 'After calling perform_reading, pass the returned reading object to interpret_reading to generate human-friendly analysis. These tools form a chain: perform_reading → interpret_reading.'
Document daily_card's purpose more explicitly: 'Draw a single card for daily guidance or quick reflection. Equivalent to draw_cards(1) but with semantic clarity. Returns DrawCard with orientation (upright/reversed) and basic meaning hints.'
Add output field naming consistency note. All tools that return card data should use card.name, card.id, card.arcana, card.suit consistently. Document this in descriptions so LLM can chain tools reliably.