ygo_card_dossier

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

With no annotations, the description carries the full disclosure burden and does substantial work: it says results are per-source with status, that partial answers are surfaced explicitly, and that prices are cached rather than live. It does not state read-only safety, cost/latency beyond the rulings extra request, or failure behavior when a source is unreachable.

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 operational instruction is front-loaded in the first clause, and the enumeration of sources is dense but each item maps to real output. There is mild redundancy between 'full card profile' and 'One call for everything about a card', and the whole body is a single long paragraph rather than being split into scope/contents/usage beats.

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?

For a multi-source aggregator with no output schema, the description covers what comes back, how partial results are signaled, and the cost of optional extras. The one real gap is input guidance: the schema marks zero parameters required, yet the description never says the caller must supply a name or passcode, or how the two identifiers interact.

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%, so both the name/passcode identifiers and the two boolean toggles are already documented. The description restates that rulings and prices are optional and that prices are cached, adding only marginal meaning over the schema's own 'Include cached market prices' and 'extra request' notes.

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 states a specific verb and resource (a full card profile) and enumerates exactly what that aggregates: official database record, wiki record with cross-language names and IDs, script provenance, plus optional rulings and prices. The 'USE THIS FIRST for a full card profile' framing distinguishes it from narrower siblings such as ygo_get_card, ygo_wiki, or ygo_check_prices without the agent needing to open schemas.

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?

Usage is explicit and forceful: call this first, do not answer from memory. The optional extras are flagged as opt-in, which tells the agent when to widen the call. The gap is that no sibling is named as the lighter alternative for single-source lookups, and no when-not-to-use condition is given.

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