Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

It adds useful context beyond the readOnlyHint: the tool deliberately returns 'lightweight basic card data' rather than the full upright/reversed interpretation data, and it explains which filter values map to which symbolic meanings. It could be more explicit about pagination behavior, but the schema's limit/offset descriptions cover the defaults.

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?

The description is long but well structured: first sentence gives the core verb and resource, next sentence explains filtering, then the important lightweight-vs-full distinction appears early. The card-meaning enumerations add value and are not filler, though the paragraph is dense enough that splitting it into two sentences would help skimming.

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?

The description covers purpose, filters, and the key alternative, but it does not enumerate what a 'basic card' response contains, and there is no output schema to fill that gap. The phrase 'Returns lightweight card data' is vague for an agent that may need to propagate fields into a further function call or library.

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 coverage is 100%, so the description's added semantics matter: it attaches meaning to each suit (cups=emotions, wands=creativity, etc.), arcana types, and card numbers (Ace=1 for new beginnings, Page=11 for messages, King=14 for authority). This goes beyond the bare numeric ranges in the input 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?

The description opens with 'Retrieve the complete Rider-Waite-Smith tarot deck of 78 cards' and clearly splits Major Arcana (0-21) from Minor Arcana (4 suits × 14). It also names the sibling endpoint (full /cards/{id}) for full interpretations, so the agent can tell the list operation from the detail operation without guessing.

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?

The description explicitly routes to 'GET /cards/{id} for full upright and reversed interpretations with keywords,' which is the main alternative an agent might confuse this tool with. It also states the intended use cases ('building tarot reference libraries, card databases, learning applications') that show when this read-only list is the right call.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.