POKEKA — Pokémon Card Prices

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false. The description adds relevant behavioral context: it reads only POKEKA market data, discloses server-side logging, and confirms it does not modify user data, which goes beyond the structured 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?

The description is front-loaded with the tool's purpose and the data it returns, followed by concise behavioral constraints. The second sentence is slightly ancillary but not wasteful.

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 simple read-only, one-parameter tool with an output schema and safety annotations, the description covers purpose, data source, and behavioral constraints adequately. It could be improved with usage guidance, but it is complete enough to invoke 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 coverage is 100% and the single parameter card_id is already documented in the schema with a reference to search_card / slang_lookup. The description adds no further parameter meaning, so the baseline of 3 applies.

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 precisely states the resource and the exact graded population metrics returned (PSA by grade, CCIC by grade, gem rate, scarcity tier). It does not explicitly name a sibling or contrast with card_price/card_price_history, so it falls short of a 5.

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 when-to-use guidance, no alternatives, and no prerequisites. The sentence about reading POKEKA market data and logging is a constraint/behavior, not usage guidance.

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 read-only, non-destructive, closed-world profile, but the description adds substantial behavioral context beyond them: no interpolation from listings, no fallback from an unavailable grade to PSA 10, the meaning of price_status values, safe_to_quote=false caveat for reference_only, and disclosure of server-side logging. The FX conversion note (price_cny/price_jpy are conversions of one pooled price, not domestic-market observations) is exactly the kind of non-obvious trait that prevents misreading the output.

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 triggers are front-loaded in the first sentence and the semantic edge cases (no fallback, price_status meanings, FX conversion) follow in dense, non-redundant sentences. It is long, but nearly every clause carries decision-relevant information; the trailing privacy/logging sentence is the only part that could be trimmed without losing invocation guidance.

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 formatting need not be described, yet the description still explains the status codes an agent must interpret (grade_not_available, reference_only, card_not_found) and how the currency fields relate to the headline price. For a single-lookup pricing tool with annotations covering safety, nothing needed for correct interpretation 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; the description goes further by explaining how company and grade combine ('Pass company + grade to price a specific grade') and by stating the critical consequence that a missing grade yields grade_not_available rather than a fallback. It also clarifies that condition 'raw' is not yet supported, which the schema alone states only obliquely. It stops short of adding format or edge-case guidance for grade strings such as '9.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 names the specific verb and resource ('what a card is worth', headline price plus per-grade ladder) and scopes the resource precisely: one price per card and grade, pooled from verified sales across all marketplaces. It distinguishes itself from card_price_history and recent_sales by emphasizing a single pooled headline price and a per-grade ladder rather than a time series or sale-by-sale feeds.

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 concrete trigger phrasings ('what a card is worth', 'PSA 10 / PSA 9 / CCIC 10 price', 'what it last sold for') and tells the agent what to do on failure ('card_not_found = wrong id, search again', i.e. go back to search_card). It does not explicitly route to the nearest sibling, card_price_history, so the boundary with historical prices is left for the agent to infer.

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 readOnly/destructive/openWorld, but the description adds real behavioral context beyond them: the series is a representative grade, capped at 26 weeks, and change percentages appear only when statistically confident. It also discloses server-side request logging and that no user data is modified, which is useful transparency for a data-read tool.

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?

A single front-loaded sentence packs the resource, scope, and caveats without repetition, and the most important element (what the series is) comes first. The trailing privacy/logging clause is marginally less essential but still short.

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 need no explanation, and the description still covers the key behavioral caveats (representative grade, week cap, confidence gating). An agent can call it correctly; only explicit sibling routing 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 description coverage is 100%, so card_id and weeks are already documented, including the 26-week maximum. The description restates the 26-week cap and single-card scope but adds no format, id provenance, or default semantics beyond the schema; baseline 3 applies.

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+resource (weekly median price series for one card) with scope details (representative grade, up to 26 weeks) and the derived 30d/90d changes. It implicitly separates itself from card_price (single point) and card_pop (population), but never names those siblings explicitly.

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 content of the series implies when it is useful (trend analysis over weeks), but there is no explicit when-to-use or when-not-to-use guidance, and no routing to card_price, card_pop, or recent_sales despite several overlapping siblings. Usage must be inferred.

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?

The description reveals important behavior beyond annotations: OAuth is required, unauthenticated calls should trigger an account-linking challenge and retry, it returns access tier and a connection-management link but never credentials, it does not purchase or change a plan, and it may record usage statistics. This fully discloses side effects and constraints.

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?

Every sentence earns its place: purpose, usage trigger, auth behavior, return characteristics, exclusions, and side effects. The core action is front-loaded and the description remains compact despite covering multiple essential aspects.

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 zero-parameter tool with an output schema, the description covers all decision-relevant context: when to use, what to expect on auth failure, what is returned, what is never returned, what side effects occur, and what it does not do. Nothing needed for 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?

The input schema is empty, so parameter semantics are trivially satisfied. The description adds contextual requirements like OAuth but no parameters need explanation. A score of 4 is the baseline for a zero-parameter tool.

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 ('Connect', 'check') and resource ('POKEKA account'), and clearly differentiates from all sibling card/market tools by stating that public card and market queries do not require this tool. The purpose is immediately identifiable and unambiguous.

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 explicit use conditions: when the user asks to connect, sign in, or check account access. It also provides a clear exclusion: public card and market queries do not require this tool. This tells an agent both when to invoke it and when not to.

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 readOnly/openWorld annotations by disclosing that coverage is curated and growing, that missing flags are not a clearance, that it reads POKEKA market data only, and that requests are logged. Those caveats materially change how an agent should interpret an empty result.

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 is front-loaded in the first clause and the enumerated payload list is efficient. The tail clause about privacy-policy logging and 'does not modify user data' is partly boilerplate and partly redundant with the readOnly annotation, which keeps it from a 5.

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 return shape needn't be described; the description instead covers inputs, data scope, coverage limitations, and privacy posture. 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 100%, so the baseline is 3, and the description earns a bump by clarifying that 'query' must be an EXACT nickname and giving concrete examples ('凡高皮', '金拱门'). It also reinforces card_id as the primary identifier sourced from other tools.

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 resource and enumerates exactly what comes back (nicknames, counterfeit-risk flags, turnover tier, context note) plus the price, which clearly separates it from card_price and slang_lookup. The dual input mode (card_id or exact nickname) is also named up front.

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 only implied: 'Everything around one card beyond the price' hints that it complements card_price, and the schema notes where card_id comes from, but the description never says when to pick this tool over card_price, slang_lookup, or get_market_brief. No explicit exclusions or alternatives are given.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description still adds useful non-annotation context: the fixed-basket same-card methodology, that server-side request logging occurs, and that user data is not modified. It does not mention rate limits or freshness/caching of the weekly counts.

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 substance is front-loaded in one dense sentence, which is efficient for a one-parameter tool. The trailing legal/privacy lines ('Not investment advice', logging disclosure) add bulk that an agent does not strictly need for invocation, though they may be worth surfacing to users.

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 low-complexity, zero-required-parameter read with an output schema present and read-only annotations, the description covers output contents, data source, and side effects well. The only real gap is routing guidance relative to the many sibling market tools, plus the track-list mismatch.

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% and the single parameter is documented, so the baseline of 3 applies. The description does help by framing the parameter as a language track, but it lists only 'all / en / ja' while the enum also includes 'zh-cn', a discrepancy that could mislead an agent about available tracks.

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 resource (graded-Pokémon market cycle position) and enumerates the concrete outputs: phase read, fixed-basket index, peak/drawdown, weekly verified-sale counts, and a release calendar. That is far more specific than a sibling like market_movers or market_volume_leaders, though no sibling is named outright to make the boundary explicit.

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 implied by the outputs: this is the aggregate trend/cycle read rather than a per-card or ranking tool. However, the description never says when to prefer it over market_movers, recent_sales, or card_price_history, and gives no exclusions or prerequisites.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that: it states the data source is POKEKA market data only, that server-side request logging is disclosed in the privacy policy, and that it does not modify user data. Rate-guarding of whole-set sweeps is mentioned but primarily lives in the schema, so this falls just 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?

The core purpose and return contents are front-loaded, and the routing guidance follows logically. However, the bilingual duplication of the statistics list adds length without new information for a primarily-English reader, slightly diluting density.

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 spelled out, and annotations cover the safety profile. The description supplies usage triggers, alternatives, data-source scope, and privacy disclosure, making it essentially complete for correct invocation. Minor remaining gap is no explicit mention of what happens when a set_code matches nothing.

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 all three parameters already carry their own documented semantics (lang track, pagination limits, accepted set_code formats). The description's note about accepting internal set_code, official abbreviation, or set name largely restates the schema's set_code description, adding little new meaning. Baseline 3 applies.

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+resource (whole-set statistics for one Pokémon TCG set) and enumerates exactly what is returned: total cards, per-language-track counts, rarity breakdown, variant breakdown, top featured Pokémon, plus a paginated checklist. It explicitly distinguishes itself from siblings by naming set_top_priced_cards and card_price as the tools for price-related questions.

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 an explicit when-to-use trigger ("Use for questions like 'how many cards / SR cards are in 151c'") and exclusions: catalog data only, redirecting pricing questions to set_top_priced_cards and card_price. The alternative-routing 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?

Beyond the readOnly/non-destructive annotations, the description discloses the liquidity gate, the capped ±40% change, the row fields returned, the 20-card limit, privacy logging, and that user data is not modified. This is unusually rich behavioral context for a read-only market query.

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 front-loaded with the trigger use case and remains dense without filler. It is a single long paragraph rather than clearly segmented, but nearly every sentence contributes relevant selection or trust 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?

Given the output schema and annotations, the description provides enough context to call the tool correctly: trigger scenarios, parameter defaults, row-level fields, result limits, and data quality constraints. Nothing essential is missing for an agent to select and invoke it.

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% and all three parameters are enums with descriptions, so the schema already documents the allowed values and defaults. The description mostly restates those defaults, though 'market tracks never mix' adds a small amount of meaning about the lang parameter.

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 an explicit use case: cards that are rising or falling, what is hot, or biggest moves this week/month. That gives an agent a clear verb-like operation (find market movers) and resource (Pokémon card price movement), and the direction/window framing implicitly separates it from volume or history siblings.

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 clearly states the user questions that should trigger this tool and explains parameter defaults for direction and window. It does not name alternatives such as market_volume_leaders or card_price_history, nor does it give explicit when-not-to-use guidance.

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?

Going well beyond the readOnly/destructive/openWorld annotations, it discloses the data source (POKEKA market data only), that server-side request logging occurs, that user data is not modified, and the crucial behavioral trait that windows anchor to the latest sale date rather than wall-clock now. That anchor semantics is exactly the kind of context 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?

Front-loaded with the core purpose and window semantics, and the median_usd vs card_price distinction is a compact, useful aside. The privacy/logging clause is somewhat tangential but short enough not to bloat the paragraph.

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 doesn't need to enumerate return fields, yet it still explains two output-interpretation pitfalls (anchor_date presentation, median_usd being mixed-grade). Combined with the read-only/scope disclosures, an agent has everything required to call and interpret this tool.

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 schema already documents lang, limit, window, and grade_company, including the PSA10 sub-filter and the non-wall-clock anchor. The description largely restates those same filters (all/en/ja/zh-cn, all/PSA/CCIC/PSA10) without adding syntax or defaults beyond what the schema provides, so the baseline 3 applies.

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 resource and ranking criterion — 'most-traded graded Pokémon cards by verified sales count' — across explicit 24h/7d/30d windows, plus the filter axes (language track, grading company). An agent can distinguish this from price-movement tools like market_movers or set_top_priced_cards 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?

Gives clear context for use (volume ranking by verified sales, filterable by language and grader) and explicitly routes the agent to a sibling for the adjacent need: 'median_usd is a mixed-grade reference; use card_price for a precise per-grade quote.' It doesn't state when this tool should NOT be used, so it falls short of a full 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 cover read-only, non-destructive and closed-world, so the description is not carrying the safety burden — but it adds genuine context beyond them: a hard cap of 10 results, cross-marketplace coverage (US, Japan-domestic, Chinese), USD normalization, and the fact that records are verified completed sales rather than listings. The privacy-logging note adds mild extra disclosure. Return format is left to 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?

Front-loaded with the core purpose and returned fields, then supporting scope in the following sentences; three compact sentences with little waste. The trailing 'does not modify user data' clause largely restates readOnlyHint/destructiveHint=false, a small redundancy.

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 further explanation, and the fixed cap of 10 removes any pagination question. Coverage of marketplaces and currency conversion is a useful plus. The only gap is the missing routing guidance relative to the pricing-history siblings, which is a usage issue rather than a completeness one.

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?

Only one parameter and schema description coverage is 100%, with the schema already stating that card_id comes from search_card / slang_lookup. The description reinforces the single-card scope but adds no new syntax, format, or constraint information about the parameter. Baseline 3 applies since the schema does 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?

States a specific verb and resource ('most recent verified sales for one card') and enumerates returned fields (date, grading company + grade, USD price, marketplace), so the agent knows exactly what it gets. It also clarifies these are completed transactions, not listings. It does not name the obvious sibling alternative card_price_history, so the differentiation is implicit through 'most recent' and 'up to 10'.

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 its use case ('most recent verified sales for one card') and points to where card_id comes from via the schema ('search_card / slang_lookup'). However, it never says when to prefer this over card_price, card_price_history, or market_movers, and gives no exclusions or alternatives. Usage must be inferred.

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 readOnly/openWorld=false/destructive=false, so the safety profile is covered, and the description still adds real behavioral facts: results are capped at 10, language tracks are never mixed, and it reads POKEKA market data only. The 'does not modify user data' clause largely restates destructiveHint=false, which is why this is not 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?

Front-loaded with the core capability and example queries, then routing and return-size facts. The Chinese sentence largely duplicates the preceding English content, adding bulk without new information, which costs it the top score.

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 wisely avoids re-explaining return fields and instead covers what the schema cannot: the 10-result cap, the set-code fallback path, language-track isolation, and how to chain card_id into sibling tools. 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 100% with a documented enum, so the baseline is 3, but the description adds genuine meaning: query accepts zh/en/ja interchangeably, covers nickname slang and 'set code + number' compound syntax with examples, and clarifies that lang pins a single language track that is never mixed with others.

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+resource ('Search graded Pokémon cards') and enumerates the three query forms (name, community nickname, set code + number) with concrete examples. It also names sibling tools it hands off to (get_set_overview, set_species_summary) and the other card_id-consuming tools, so an agent can place it precisely in the toolset.

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 covers the when: use for name/nickname/set-code+number lookups, then pass card_id to the pricing/population/history tools. It also covers an important edge case — a bare set code or set name returns a set-level summary with guidance rather than a truncated list — and tells the agent to follow that guidance to the right alternative tools.

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 readOnlyHint/openWorldHint annotations, it adds that it reads POKEKA market data only, that server-side logging is disclosed in the privacy policy, and that it does not modify user data – useful operational context. It stops short of describing result format or pagination, but with output schema present that gap is minor.

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-loads the core purpose and then layers the example query, the probability caveat, and the data-source disclosure efficiently. The bilingual duplicate paragraph adds length but serves a documented user segment, so the density is justified rather than wasteful.

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 covering return values and annotations covering the safety profile, the description supplies the remaining essentials: what is counted, what it is not (probabilities), and the data source. It is complete enough to invoke correctly, missing only explicit sibling routing.

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% and both parameters (set_code, lang) are already documented in the schema, so the baseline of 3 applies. The description's variant vocabulary (base/Master Ball/Poké Ball) concerns output values, not parameter meaning, so it adds no parameter-level guidance.

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 resource and metric: a per-Pokémon breakdown for one set, counting card faces per species and their variant split (base / Master Ball / Poké Ball). It also draws a conceptual contrast with pull-rate tools, though it never names a specific sibling like get_set_overview or card_pop, so the differentiation is implied rather than explicit.

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 a concrete use case ('which Pokémon has the most versions in this set') and clarifies the data is catalog counts, not probabilities, steering the agent away from pull-rate tools. However, it offers no explicit 'when not to use' statement or named alternative, so the routing is contextual rather than directive.

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 readOnly/destructive annotations: explains that cards with no usable price are excluded, that the response reports how many cards in the set have a price, that only the top of the ranking is returned with no paging, the price_basis values (verified_sales or reference), and discloses server-side request logging.

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-loads the core action and scope, then adds behavioral caveats. The bilingual example block is useful for matching user phrasing, though it adds length; overall every clause carries 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?

With annotations covering safety and an output schema present, the description fills the remaining gaps: exclusion of unpriced cards, coverage count, ranking-only/no-paging behavior, and the price_basis semantics an agent needs to interpret results.

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% and the lang parameter already documents the enum and the 'cards language, not user language' rule. The description reinforces the single-language-track constraint and the max-20 cap but adds little syntax or format detail beyond 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+resource: 'Rank the highest-priced cards inside one Pokémon TCG set' with scope (top N, max 20, single language track). This clearly separates it from card_price (single card) and set-level siblings like get_set_overview.

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 concrete trigger phrases ('most expensive / top 5 priciest cards in m2a' and the Chinese variants) and notes it is not a sorted checklist and has no paging. It implicitly routes per-card pricing to card_price ('不用逐张查价'), but never names siblings like market_movers or get_set_overview as alternatives.

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=true, destructive=false, openWorld=false), and 'does not modify user data' merely restates that. But the description adds genuinely new context: a hard 'Up to 10 cards' result cap, that it reads POKEKA market data only, and a server-side request-logging disclosure. These go beyond 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?

The purpose is front-loaded and the whole thing is a tight block with no wasted preamble. The Chinese sentence largely mirrors the English one, and the trailing 'does not modify user data' duplicates annotation content, but the bilingual rendering is defensible for the target audience.

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?

A single fully documented parameter and an existing output schema mean the description needn't explain return values, and it still adds result-cap and data-source scope. It is complete enough for an agent to call correctly, with only the missing sibling routing as a minor gap.

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 100% schema coverage, the baseline is 3, and the description earns above that by clarifying the term's value domain — it accepts Chinese/Japanese/English community nicknames — plus concrete examples ('鬼皮', '老喷', 'Zard') that the schema's terse 'nickname / slang term' text does not provide.

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 precise verb+resource ('Resolve a ... community nickname ... to the actual card(s)') and enumerates the output fields (official names, set, number, card_id). This is clearly distinct from sibling search_card, which takes official names, and an agent can tell them apart without opening either 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 the usage context (you have a slang/nickname and need the real card) and notes the supported languages, which guides invocation. However, it never explicitly states when to prefer this over search_card or excludes cases, so the when-to-use is left to inference.

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