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

Annotations already cover the safety profile (readOnly, openWorld, destructive=false), so the bar is lower, and the description still adds quota context that the schema cannot express: one admitted call consumes one shared account request, admitted errors count, and there are no automatic retries. That is genuinely useful operational behavior for a rate-limited account, though it omits pagination/return-shape behavior (partly excused by the output schema).

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?

Four tight sentences, front-loaded with what the tool searches before moving to identifier and quota caveats; nothing is padded. Density is high, and the rate-limit sentence earns its place, though the identifier-bridge sentence is the only one that could be trimmed slightly.

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 read-only search with an output schema (so return values need no explanation), the description covers scope, identifier prefixes, pricing hand-off, and quota consumption. The main remaining gap is that none of the six input parameters gain meaning from the description, but the annotations plus output schema carry much of the rest.

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 only 50%, so the description should compensate; instead of explaining set, view, after, limit, or release_status, it spends its parameter-adjacent words on identifier semantics (cat_/catv_/tcg_) that are relevant to interpreting results rather than to filling the inputs. Baseline 3 for the covered half, with a clear gap on the undocumented parameters.

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 and resource (search the Japanese Pokémon source catalogue) and adds a scope qualifier that separates it from pricing siblings: 'price-independent ... including cards with no price-variant match.' It also disambiguates the cat_ vs catv_ vs tcg_ identifier families, so an agent can tell it apart from get_card_prices/get_prices without opening other 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?

Explicitly routes the agent away from this tool for pricing ('Use pricing.price_variants[].id (tcg_) for prices, never guess a bridge'), which is real when/when-not guidance. It does not, however, name the obvious sibling (search_cards) or state whether this should be preferred over get_catalogue_card for single lookups, leaving that routing to inference.

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