tcgdata.dev — European TCG Prices

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

Annotations already declare the read-only/open-world profile, but the description adds material behavior they cannot express: the account-request accounting model ('one admitted API call consumes one shared account request, including admitted errors'), the no-retry/no-split policy, and the separate handling of unavailable_ids. This is exactly the kind of operational context an agent needs before invoking.

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?

Front-loaded and mostly dense, but the no-retry policy is stated twice ('Never split or retry automatically' and 'No automatic retries'), which is redundant. Otherwise tight and earning its place.

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?

With an output schema present, return values needn't be explained, and the description covers limits, request accounting, and the unavailable_ids split. The one gap is that compact vs full behavior is unaddressed, but overall an agent has enough to call it correctly.

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 low (0% by context signal), so the description must compensate. It conveys the ID semantics ('mixed-game tcg_ IDs', deduplication) and the per-tier limits that map to card_ids/maxItems, but the 'view' enum (compact/full) is never explained in either the description or the schema, leaving one parameter undocumented.

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 (Read), resource (EUR prices), and scope (mixed-game tcg_ IDs in one request), which cleanly separates it from the single-item siblings get_prices and get_card_prices. An agent can identify it as the batch variant without opening the 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?

The description implies batch usage ('mixed-game tcg_ IDs in one request') and gives tier-based ID limits, which is useful context, but it never names when to prefer this over get_prices/get_card_prices or get_price_history, leaving the routing decision to inference.

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

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

Annotations already establish readOnly/openWorld/non-destructive, but the description adds substantive operational context: one admitted call (including errors) consumes one shared account request, and there are no automatic retries. It does not explain why the operation is non-idempotent, but its quota and retry disclosure clearly exceeds the annotations.

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 sentences, purpose front-loaded, and each sentence carries distinct information (stored vs fresh, sibling routing, quota cost, no retries). Reasonably tight, though the quota and retry sentences could be merged.

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?

An output schema exists, so return-value detail is not required, yet the description still notes game fields and image paths. Combined with the quota/retry disclosure and the sibling pointer, an agent has enough to call this correctly; only the view parameter remains unexplained.

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 only 50%: card_id is richly documented in the schema, but the view enum (compact/full) is undocumented in both the schema and the description. 'Includes game fields and image paths' gestures at returned content but never ties it to the compact/full choice, leaving the description unable to compensate for the gap.

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 (read) and resource (stored variant metadata + pricing availability), and distinguishes itself from get_card_image by naming that sibling. It does not, however, draw a clear line against get_card_prices or get_catalogue_card, which also concern card data.

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?

'without requiring a fresh quote' signals when to prefer this stored-data read over a live price fetch, and it explicitly routes artwork requests to get_card_image. No explicit exclusions or coverage of the other pricing siblings, so it falls short of a 5.

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

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

Annotations already mark this read-only and non-destructive, and the description goes well beyond them: one admitted API call consumes one shared account request (including admitted errors) and there are no automatic retries. These quota/retry semantics are exactly the behavioral context an agent needs and cannot get from structured fields.

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 the action and result, then constraints. Dense but every sentence carries distinct information; nothing is filler, though the packing is close to terse.

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?

With an output schema present, the description need not explain return values, and it still adds quota, retry, ID-sourcing, and face/catalogue semantics. For an image-fetch tool with catalogue variants and shared request accounting, nothing an agent needs to call 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 coverage is 75% and the schema already documents face and catalogue_card_id. The description adds real value by explaining that face selects a Magic face and that catv_ variants require their parent cat_ ID, tying parameters to the catalogue workflow rather than just restating them.

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: return verified WebP artwork as an MCP image block. It is clearly distinct from data-returning siblings like get_card or search_cards. It stops short of explicitly naming which sibling to prefer when the agent wants card data rather than artwork.

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 explains where valid IDs come from (the images.small/large query fields), the prerequisite for catv_ IDs (their parent catalogue_card_id), and an explicit prohibition (never pass an arbitrary image URL). No explicit when-to-use-vs-alternative routing against siblings, but the invocation conditions are concrete.

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

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

Annotations already declare read-only, open-world, non-idempotent and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: quota accounting ('one admitted API call consumes one shared account request, including admitted errors'), no automatic retries, and null-means-unknown semantics. It stops short of describing failure modes or pagination, but the quota/retry disclosure is material.

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 lead sentence front-loads the core purpose, and the following sentences are dense with no filler. The 'Product guides do not filter condition, language or edition' sentence is a useful scope guard, though its placement between price semantics and quota rules slightly interrupts the flow.

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?

An output schema exists, so return shape need not be explained, and the description still adds value with observed_at, quote scope, and null semantics. It covers quota and retry behavior, which matters for an API-consuming read. The one gap is that it never clarifies whether this alias is functionally identical to get_prices or differs.

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 50%: card_id is documented but the 'view' enum is not described anywhere. The description partly compensates by stressing 'one exact variant' and mentioning 'quote scope', which hints at the compact/full distinction, but it never explains what 'view' changes or what full returns. Baseline 3 is appropriate given the schema does half the work.

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 names a specific verb and resource ('Read measured EUR prices') and narrows scope to 'one exact variant', which is more precise than the title alone. It also identifies itself as a 'Compatibility alias of get_prices', which is informative but leaves ambiguous whether behavior differs from get_prices. Sibling differentiation against batch_prices, get_price_history and get_prices is only partially achieved.

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?

'Compatibility alias of get_prices' implies this exists for backward compatibility and that get_prices is the forward path, but it never states when to prefer one over the other. There are no explicit exclusions relative to batch_prices or get_price_history. Usage is inferable but not spelled out, so this sits at the minimum-viable level.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), yet the description adds genuinely non-structured behavior: a shared-account request budget consumed per admitted call including errors, and an explicit no-retry policy. That quota/no-retry context is exactly the kind of beyond-annotation disclosure that matters. It stops short of describing error surfacing or what compact vs full omits.

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 short, front-loaded sentences with no filler; the capability statement leads and operational constraints follow. Dense jargon ('admitted', 'tcg_ price-variant ID') costs a little readability but each sentence carries distinct information.

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?

An output schema exists, so return shape need not be explained, and the description covers the consumption model and downstream ID contract. The remaining gap is the undocumented 'view' parameter, which an agent must guess at to control payload size.

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 50%: catalogue_card_id is well documented in the schema (including which tool produces it), but the 'view' enum has no description anywhere. The description's phrase 'variants, provenance and explicit pricing references' hints at the richer view but never explains compact vs full, so it only partially compensates.

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 ('Read one Japanese source card') and enumerates the payload scope (variants, provenance, pricing references), which separates it from generic card tools. It does not explicitly name the sibling it complements (search_catalogue_cards is only referenced in the schema), so sibling differentiation is partial.

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?

Gives one concrete downstream rule — 'Only use returned tcg_ price-variant IDs for price tools' — which tells the agent how to chain into price tools, but never states when to call this instead of get_card or search_catalogue_cards, nor any prerequisite for obtaining the cat_ ID beyond what the schema says.

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

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

Goes well past the annotations (readOnly/openWorld/non-idempotent/non-destructive) by disclosing quota semantics ('one admitted API call consumes one shared account request, including admitted errors') and the absence of automatic retries, which directly explains why idempotentHint is false. It also constrains interpretation of the data ('preserve missing_dates; never interpolate') and pins the window to UTC.

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?

Front-loaded with the core purpose and kept to six short sentences with no filler. Some sentences are telegraphic fragments ('UTC window ends on to or today', 'No automatic retries') that read more like notes than prose, which slightly hurts scannability at the tail.

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?

An output schema exists, so return format need not be explained, and the description still covers the important non-schema context: UTC windowing, quota cost per call, no retries, and missing-date handling. It is thin on what 'approved stored variant' means and gives no hint about response size or limit behavior for larger windows.

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 67%: card_id and to are documented in the schema, while days has no description and no enum. The description adds meaning only for to, clarifying that the UTC window ends on that date or today, but says nothing about days or its 1-90 bound. Baseline 3 is appropriate given the schema carries most of the load.

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: read daily EUR observations for an approved stored variant, and adds the disambiguating scope note 'independently of its current price', which separates it conceptually from sibling price tools like get_card_prices and get_prices. It does not name any sibling explicitly, so an agent still has to infer the boundary from sibling names alone.

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?

'Use earlier to dates for older windows' gives one piece of operational guidance about a parameter, but there is no explicit statement of when to prefer this tool over get_prices, get_card_prices, or batch_prices. Usage is implied by the scope sentence rather than stated.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses real operational behavior: null means unknown rather than zero, one admitted call consumes one shared account request even on error, and there are no automatic retries. That quota and retry disclosure is exactly the kind of trait annotations cannot express.

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 short, front-loaded sentences with no padding. The one weak spot is 'Product guides do not filter condition, language or edition', which is cryptic in context and its relevance to a single-variant price read is not self-evident.

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?

With an output schema present, the description need not detail returns, yet it still clarifies return semantics (null-vs-zero) and call-cost behavior. The main gap is the undocumented 'view' parameter, which the agent has no guidance on.

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 50%: card_id is fully documented in the schema, but the 'view' enum (compact/full) is undocumented in both places and the description never explains the difference. The phrase 'one exact variant' reinforces card_id semantics but adds nothing for the unexplained view parameter, so this sits at the baseline.

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 ('Read measured EUR prices') plus a scope qualifier ('for one exact variant'), which is enough to separate it from aggregate siblings like batch_prices. However it never names the closely related get_card_prices or get_price_history, so the agent must infer the distinction between 'current price' and 'price history' itself.

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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative, despite four adjacent price tools in the sibling list. 'One exact variant' only weakly implies 'do not use this for multiple cards', leaving the routing decision to inference.

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

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

Goes well beyond the annotations: it discloses that the call counts itself against the shared quota, cannot bypass exhausted limits, consumes one request per admitted call including admitted errors, and performs no automatic retries. It also explains what happens around plan upgrades (activate after Stripe confirms payment) and custom access (separate agreement, manual activation), which the readOnly/openWorld/idempotent hints do not convey.

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?

Front-loaded with the core purpose and quota-consumption behavior, which is the highest-value information. It is somewhat long: the upgrade/Stripe and custom-access sentences are billing-context rather than invocation guidance, and 'counts itself' partially overlaps 'one admitted API call consumes one shared account request, including admitted errors.'

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?

With no input parameters and an output schema present, the description needs only to explain what the call does and how it affects the account; it covers both thoroughly, including self-counting, no-retry behavior, and the upgrade/access paths.

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?

The tool takes zero parameters, so the schema has nothing to document and there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly implies the call is unscoped (whole-account usage).

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 concrete verb and resource ('Read account request usage and limits') and immediately scopes it ('shared across keys and games'), so the agent knows this is an account-level quota read rather than a per-key or per-game resource. No sibling tool (all card/price lookups) overlaps, so ambiguity is nil.

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?

Gives a clear pre-condition ('Check request metadata on existing results first') that steers the agent away from a wasteful call, and implies the use case of monitoring quota. It stops short of naming an alternative tool or an explicit when-not-to-call rule, but no sibling covers this territory.

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

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

Adds substantial behavior beyond annotations: one admitted API call consumes one shared account request even on admitted errors, and there are no automatic retries. It also warns that a set record is a catalogue membership rather than proof of a physical printing, a semantic caveat an agent could not infer from readOnlyHint/openWorldHint alone.

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, led by the core purpose before pagination, return-type and quota caveats. Every sentence carries information, though the density of clauses makes it slightly terse.

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, paginated lookup tool with an output schema, the description covers purpose, downstream usage, pagination, quota cost and record semantics. The remaining gap is the meaning of the limit and release_status filters, which neither schema nor description fully explains.

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 50%: 'after' and 'query' are documented in the schema, while 'limit' and 'release_status' are not. The description reinforces cursor usage but adds nothing about the limit cap or the release_status enum values, so the partially covered parameters stay under-explained.

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 Japanese Pokémon source sets') and clarifies the output type ('catalogue set IDs'). It also routes the agent downstream by naming search_catalogue_cards, though it does not contrast itself against the other listing siblings like list_games.

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?

Gives a clear workflow: use the returned next_cursor for pagination and feed the resulting IDs into search_catalogue_cards. No explicit when-not-to-use or exclusion conditions are stated, but the intended context is unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: the call is static and consumes no API request or account usage, which matters for budget-aware planning. It stops short of noting caching or stability guarantees.

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?

Two sentences, no filler, with the resource and scope front-loaded and the operational caveat second. Every clause earns its place.

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?

An output schema exists, so return values need no narration, and there are no parameters to document. For a static zero-arg list tool this is as complete as an agent needs.

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?

Zero parameters, so the baseline of 4 applies. There is nothing for the description to clarify about inputs, and it correctly describes the returned content instead.

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?

Specific verb plus resource ('List the six supported game identifiers and catalogue languages') that tells the agent exactly what comes back, including the cardinality. It is clearly distinguishable from siblings like list_catalogue_sets or get_usage, which return different resources.

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?

'Static API capabilities, no API request or account usage' tells the agent this is a free, non-quota-consuming call, implicitly contrasted with the account-consuming sibling tools. It does not explicitly name an alternative or state exclusions, so it falls short of a 5.

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

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

Goes well beyond the annotations (readOnly/openWorld/non-idempotent/non-destructive) by disclosing the cost model: 'One admitted API call consumes one shared account request, including admitted errors' and 'No automatic retries.' The quota/consumption detail and the no-retry warning are exactly the operational facts an agent needs before calling, and nothing contradicts the declared hints.

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?

Purpose, return shape, parameter guidance, workflow ordering and quota caveat are all packed into five dense, front-loaded sentences with no filler. Each sentence carries decision-relevant information for the agent.

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?

An output schema exists so return values need not be spelled out, yet the description still summarizes them (stable tcg_ IDs, identifying fields, pricing availability, next_cursor). Combined with annotations and the quota note this is nearly complete; the only minor gap is that none of the non-required filter params (game/set/query/limit) are elaborated.

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?

With only 50% schema coverage, the description compensates by explaining view=full ('compare printed_number and finish_details') and the cursor lifecycle ('returns ... next_cursor', 'Stop when next_cursor is null' via the schema). It adds real meaning for view and pagination, though game/set/query/limit are left entirely to the schema.

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 (Find) and resource (variant candidates/card variants) and scopes it to six games, immediately signalling it is a lookup/browse tool rather than a pricing tool. It differentiates from pricing siblings implicitly ('even without a current price', 'before requesting prices') but never names a sibling like search_catalogue_cards directly, so an agent must infer the boundary.

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?

Provides clear workflow context: use view=full to compare printed_number and finish_details, preserve separate printings, and choose an exact candidate before requesting prices. This tells the agent where this tool fits relative to the price tools, but it does not name an explicit alternative or state when-not to use this tool.

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

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.