ygo_check_prices

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

With no annotations supplied, the description carries the full burden and does well: it discloses the Japanese-name resolution step, states that a failed Yuyu-tei match yields a search link with price 0 rather than a guessed number, and says the result is one aggregate per card. It omits any mention of caching, rate limits, or freshness of the quotes, which keeps it short of a 5.

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?

Three sentences, front-loaded with the market scope, then the fallback rule, then the sibling routing. Every sentence earns its place; a slight density cost comes from the parenthetical market/region labels, but nothing is redundant.

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?

There is no output schema, yet the description still characterizes the return shape ('one aggregate per card') and the degenerate case (search link with price 0), which is exactly what a two-parameter lookup tool needs. Nothing essential to correct invocation 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 coverage is 100%, so the baseline is 3, but the description adds real meaning by explaining that the English card name is resolved to a Japanese name for the Yuyu-tei lookup — behavior a caller could not infer from the schema. The passcode parameter is left unexplained beyond its schema text, which prevents a 5.

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 ('Multi-market price lookup'), enumerates the exact markets covered (TCGPlayer/US, Yuyu-tei/JP, TCGCorner/AE), and names the sibling tool it is not to be confused with. An agent can distinguish it from ygo_card_printing_prices and the meta/trend price tools without opening any schema.

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?

It gives an explicit routing rule: for per-rarity or per-language printings use ygo_card_printing_prices instead. It does not, however, distinguish itself from other price-adjacent siblings such as ygo_market_query, ygo_deck_cost, or ygo_get_card_price_trends, so the when-not guidance is partial.

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