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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context beyond that: it is a standalone endpoint, returns the complete deck rather than a subset, and is meant to feed 'enriched display layers' in downstream tarot draw/spread tools. It also links to a full output and error contract, so the agent has a clear behavioral picture.

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 well structured with clear headings and the core purpose is front-loaded in the first sentence. The WORKFLOW, INPUT CONTRACT, and DO NOT CONFUSE WITH sections each serve a distinct purpose, though the 'BEFORE: None' line is slightly filler and the total length is a bit longer than strictly necessary.

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 tool is simple: one optional enum parameter, an output schema, and no required inputs. The description covers what it returns, the metadata fields, workflow context, sibling disambiguation, and a link to the full contract. Nothing an agent needs to select and invoke it correctly is missing.

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%: the only parameter, response_format, is fully documented with enum values, a default, and an explanatory description. The description's INPUT CONTRACT merely summarizes the schema and confirms there are no other parameters, adding no new semantic detail beyond what the schema already provides.

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 begins with a specific verb and resource: 'Returns the complete 78-card Rider-Waite-Smith deck with full metadata,' and enumerates the fields included. It also explicitly contrasts itself with three sibling tools in the 'DO NOT CONFUSE WITH' section, making it easy to distinguish from major_arcana, suit, and draw.

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 WORKFLOW section states there are no prerequisites and recommends using this tool before asterwise_draw_tarot_cards or asterwise_get_tarot_three_card_spread to build enriched display layers. The 'DO NOT CONFUSE WITH' section gives explicit conditions for when to use alternatives: major_arcana for 22 cards, suit for 14 cards, draw for random selection.

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