Search Pokémon cards

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond that: the regional data asymmetry (JP sets are not translations, CN has 60 sets), the coverage statistics for card game text (attacks on 33%, etc.), the null-means-not-held semantics, and the explicit statement that legalities are empty and cannot be answered. This is exactly the kind of behavioral disclosure that prevents an agent from making wrong inferences.

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 information-dense, and every sentence earns its place: search dimensions, return shape, regional asymmetry, language behavior, coverage statistics, null semantics, and explicit exclusions. It is front-loaded with the core purpose and return shape, then layers caveats. It could be slightly tightened (the coverage statistics sentence is long), but the density is justified given the tool's complexity and the number of traps an agent could fall into.

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 12-parameter search tool with no output schema, the description is remarkably complete. It covers what the tool returns, how to use the parameters, what the data quality caveats are, and what the tool cannot answer. The only thing not explicitly described is pagination mechanics, but the cursor parameter's schema description ('Opaque cursor from a previous call. Never construct one.') already covers that. The description fully compensates for the absence of an output schema.

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 the baseline is 3. The description adds meaning beyond the schema by explaining the lang parameter's fallback behavior ('falls back to English when a translation is missing'), clarifying that set names are not translated, and giving the q parameter its escape-hatch role. It also explains the region enum values with counts (WEST 176, JP 379, CN 60). The description doesn't add per-parameter syntax details for every field, but the schema already covers those, and the description's additions are genuinely useful.

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 a specific verb and resource ('Search the Pokémon TCG card catalogue') and enumerates the searchable dimensions (name, set, print region, rarity, artist, release window), which clearly distinguishes it from siblings like ptcg_get_cards or ptcg_get_card_prices. It also states the return shape (one row per printing with set, rarity, illustrator, euro price index), so an agent knows exactly what this tool produces.

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 gives explicit guidance on when to use this tool versus alternatives: it names ptcg_list_sets for finding set codes, ptcg_get_reference for valid rarity values, and ptcg_list_artists implicitly through the artist parameter. It also tells the agent when NOT to use it: deck legality is explicitly out of scope ('say so rather than inferring it'). The escape-hatch q parameter is scoped to cases where named arguments cannot express the question.

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