Tarot spreads and card draws from a shuffled 78-card Rider-Waite-Smith deck, 23 languages, no key.
Scored across 2 tools
draw_cards and list_spreads have completely distinct purposes—one draws/returns cards, the other enumerates available spreads. Their coupling (draw_cards consumes spread_id from list_spreads) is explicit and complementary rather than overlapping.
Both tools follow a clean snake_case verb_noun pattern (draw_cards, list_spreads). The convention is fully consistent with no deviation.
With only two tools the surface is on the thin side for a tarot server, and draw_cards carries a lot of overloaded behavior (widget vs text mode, spreads vs free-form, localization). It works but feels minimal rather than well-scoped.
Drawing and spread enumeration are covered, but there is no tool to look up card meanings, interpretations, or reversed/positional significance—a notable gap for a tarot domain, since an agent can draw cards but not interpret them.
Shuffle a full 78-card Rider-Waite-Smith deck with server-side randomness and show it face-down in an interactive widget, where the user picks their cards by hand. Where the widget renders, the tool result does not contain the drawn cards: the widget sends the cards the user picked to the conversation once the last one is revealed. In a text-only host the cards are drawn server-side and returned in the result. Takes a spread_id from list_spreads to draw into that spread's positions, or a card_count (1-10) for a free-form draw such as a single card of the day. Card names, position names and the widget text follow locale.
| Name | Required | Description | Default |
|---|---|---|---|
| locale | No | Language for spread names, position names, card names and widget text: the language the user is writing in, as a BCP-47 code (zh-CN = Simplified Chinese, zh-TW = Traditional Chinese). Defaults to en. | |
| spread_id | No | Spread id from list_spreads. Takes precedence over card_count. | |
| card_count | No | Number of cards for a free-form draw without a spread. Defaults to 3. |
| Name | Required | Description |
|---|---|---|
| cards | No | |
| spread | No | |
| status | Yes | |
| card_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations, which only declare a safe read operation. It discloses that shuffling is server-side, that the widget path deliberately omits the drawn cards from the tool result and delivers them later via the conversation, and that text-only hosts return cards directly — behavior an agent must know to interpret the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action, then the host-dependent behavior, then parameter usage; every sentence carries information. It is dense and slightly long, but no sentence is filler given the non-obvious widget/text-only split.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, yet the description supplies the one thing the schema cannot: that the result may intentionally contain no cards in widget hosts. Combined with locale and spread routing, an agent has everything needed to call and interpret it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents locale format, spread_id precedence, and the 1-10 card_count bound with its default, so the baseline is 3. The description restates spread_id's source and the card_count range without adding syntax or validation detail the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (shuffle/draw a 78-card Rider-Waite-Smith tarot deck) and immediately distinguishes itself from the only sibling by naming list_spreads as the source of spread_id. An agent can tell what this does and that it is not the listing tool without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear selection rule between the two draw modes: spread_id for drawing into a spread's positions, card_count for free-form draws like a card of the day, with an example. It routes to list_spreads for obtaining a spread_id, but never states when this tool should not be used or what happens if both params are omitted beyond the schema default.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the tarot spreads available for a reading, with each spread's id, name, tagline, number of cards, and position names, in the requested language. The ids are the values draw_cards accepts as spread_id and are the same in every language.
| Name | Required | Description | Default |
|---|---|---|---|
| locale | No | Language for spread names, position names, card names and widget text: the language the user is writing in, as a BCP-47 code (zh-CN = Simplified Chinese, zh-TW = Traditional Chinese). Defaults to en. |
| Name | Required | Description |
|---|---|---|
| spreads | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/non-destructive/non-open-world, so the safety profile is covered. The description adds genuinely useful behavior the annotations cannot convey: the returned fields, that results are localized, and that spread ids are language-invariant, which prevents needless re-listing per locale.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, with the payload content stated first and the draw_cards linkage as the closing, high-value note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Return values are documented by the output schema, safety by annotations, and the one parameter fully by the schema; the description supplies exactly the missing cross-tool context. Nothing needed to invoke it correctly is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the locale enum already documents every value and the zh-CN/zh-TW distinction, so the baseline is 3. The description's 'in the requested language' and 'ids are the same in every language' hint at locale behavior but add no format detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource (list the tarot spreads) plus the exact fields returned, and it explicitly ties itself to the sibling by stating the ids are the values draw_cards accepts as spread_id. An agent can distinguish it from draw_cards purely from the text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Strong implicit routing: the note that ids are draw_cards' spread_id tells the agent this is the discovery step before drawing. However, it never states an explicit when-to-use/when-not condition, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
draw_cardslist_spreadsRider-Waite-Smith, Marseille and Lenormand: spreads, draws, card pictures and spread readings.
Real random tarot draws, card meanings, I Ching casting, BaZi charts and Chinese zodiac (EN/JA).
Free tarot for Claude & your AI — many decks, real card art, a true shuffle, drawn & discussed.
Tarot card meanings, spreads and seeded reproducible readings for AI agents, one API key.
Add one secure layer between your agents and this server.
