BinderDex

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the description only needs to add context. It does: set_id switches the tool from a list to a detail response that embeds the top 10 highest-value cards, which is a meaningful behavioral disclosure not in the annotations. It stops short of noting the list cap of 25 or default 15 in prose, but the schema covers that.

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 primary list mode before the set_id override and the sibling pointer. Slightly dense with parenthetical asides, but every sentence carries routing or scope 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-value explanation is unnecessary, and the description already flags the notable embedded '10 highest-value cards' payload. Both operating modes, the filter options, and the sibling alternative are covered — nothing an agent needs in order 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 description coverage is 100%, so parameters are already fully documented, including the game enum values and the set_id mode switch. The description largely restates those facts ('filterable by series/query and by game') rather than adding new semantics such as matching rules or id formats. 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 specific verbs and resources: lists Pokemon and One Piece sets, and with set_id returns a single set's detail plus its 10 highest-value cards. The dual mode is stated up front and the tool is clearly differentiated from binderdex_search_cards and binderdex_get_card.

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 question archetypes ('what sets exist', 'most valuable card in [set]') that map to each mode, and explicitly names binderdex_search_cards as the alternative for individual cards. An agent can route without opening any schema.

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, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds real substance beyond them: the response includes every tracked variant and condition with USD market price, a price_updated_at timestamp, and 7d/30d changes, so the agent knows what data freshness and granularity to expect.

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, front-loaded with the core action and payload, then the lookup prerequisite. No filler and nothing repeated from the schema.

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, full parameter descriptions, and rich annotations, the description only needs to convey purpose and routing, which it does. The one gap is that it never distinguishes this tool from the price_history/price_stats siblings, which matters for an agent choosing among price-related reads.

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 both parameters, including the concise/detailed enum. The description confirms that id may be a slug as well as an id, but says nothing about response_format or when the detailed mode is worth the extra size, so it adds little 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 and resource ('Get full detail for one BinderDex card') and names the accepted identifiers (id or slug), plus what the payload contains (variants, conditions, prices, deltas). This cleanly separates it from the sibling search tool, which returns lists rather than one card's detail.

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: 'Call binderdex_search_cards first to find the id if you only have a card name.' That is a clear precondition and names the alternative tool. It does not cover when an agent should prefer binderdex_get_price_history or binderdex_get_price_stats instead, so sibling routing is only partially addressed.

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, idempotent, closed-world semantics, so the description's job is to add context beyond them, which it does by explaining the noise rationale for the min-price default and the ranking/aggregation nature of the results. It stops short of noting that results are capped at 10 rows or that non-7-day periods silently fall back to 7 days, gaps that matter for a ranked-list 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?

Three short sentences, front-loaded with the capability and its filters, followed by usage triggers and the sibling redirect. No filler or repetition of schema details.

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 and 100% parameter description coverage, the description only needs to convey scope, ranking semantics, and tool routing, all of which it does. Nothing an agent needs to select or call this correctly is absent.

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 adds genuine meaning by framing the whole result set as fixed to a 7-day window and by explaining why min_price_cents exists (to suppress noisy low-value percent moves). It does not mention the 1-10 row cap or response_format, leaving those 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 (biggest price gainers/decliners) with the exact window (last 7 days) and available restrictions, so an agent knows precisely what this returns. It is clearly distinguishable from sibling tools like binderdex_get_price_history or binderdex_get_price_stats, which are per-card rather than ranked across the market.

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 explicit positive triggers ('what's spiking' / 'what's crashing' questions) and names a specific alternative for the adjacent case (binderdex_search_cards for name/set lookups). The when-not condition is stated rather than left 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context the annotations cannot: a 90-day window and downsampling to at most 60 points. It does not mention error behavior for invalid ids or rate limits, which keeps it from 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?

Two sentences, both dense and front-loaded: the return shape first, the prerequisite routing second. No filler and no repetition of the tool name.

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, yet the description still summarizes the computed fields so the agent knows what the call yields; combined with full schema coverage and annotations, nothing needed to invoke 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; the schema already documents id, days, variant, and response_format. The description restates the 90-day cap and adds the downsampling behavior, but says nothing extra about variant semantics or what changes between concise and detailed beyond what the enum already conveys.

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 (daily USD price series for one card) and enumerates the deliverables (start, end, change, high, low, trend). It is clearly distinguishable from browse/search siblings, though it never contrasts itself with the close cousin binderdex_get_price_stats.

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 an explicit prerequisite: 'Call binderdex_search_cards first if you only have a card name,' which tells the agent how to obtain the required id. It stops short of stating when to prefer this over binderdex_get_price_stats or binderdex_get_market_movers.

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 a safe, idempotent, closed-world read, so the bar is lower; the description still adds real value by disclosing the plan gating and the exact shape of the free-plan error ('readable error naming the upgrade needed'). It also states the per-variant grouping guarantee, though it doesn't discuss empty-result behavior or whether short windows return partial aggregates.

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 verb, resource, and scope, then enumerates outputs compactly in a single dense sentence. The paid-plan sentence is short and earns its place; nothing is padded, though the output-field enumeration runs long given an output schema exists.

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 a full input schema, an output schema covering return values, and read-only annotations, the description fills the remaining gaps an agent needs: the plan gate, error behavior, and the guarantee that variants are never blended. Nothing required 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 description coverage is 100%, so all four parameters are already documented, and the enum values for window and response_format are visible there. The description only reinforces the window choices and the per-variant semantics of 'variant'; it says nothing extra about response_format or the id format from binderdex_search_cards, so 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 and resource (aggregate price statistics for one card) and precisely enumerates the returned metrics: min, max, average, first/last price with dates, and percent change. The 'per variant so printings are never blended together' clause distinguishes it from the raw history sibling at binderdex_get_price_history.

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 context for use: one card, a 7/30/90-day window, and a paid-plan prerequisite with a described failure mode for free keys. It does not, however, explicitly route the agent between this tool and binderdex_get_price_history or binderdex_value_cards, so the alternative-selection guidance is only implicit.

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/idempotent/non-destructive, so the safety bar is met; the description adds that the result set is small and enumerable (two games) with stable slugs. It doesn't say whether the catalog can grow or change, but nothing essential is missing for a read-only lookup.

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: the first defines the resource and its fields, the second gives the use case. Purpose is front-loaded.

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-arg, read-only listing with an output schema, the description supplies everything needed: what comes back, which games exist today, and why to call it. Only minor gap is not stating how often the game/set catalog changes.

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 baseline is 4 and no parameter explanation is needed. The description correctly spends no space on inputs.

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 ("List the games BinderDex serves") and immediately scopes it (Pokemon and One Piece today), which no sibling covers. The mentioned return fields (slug, display name, set/card counts) further distinguish it from browse_sets and search_cards.

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 to confirm a valid game slug before filtering other tools by game" gives an explicit precondition that ties this tool to the sibling tools. The agent knows both when to call it and what to do with the result.

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 read-only, idempotent, non-destructive behavior, and the description adds the economically important context: 'one request credit total' for the whole batch. It also discloses the response structure (per-line value, running USD total, ambiguous/not_found lists capped at 3 candidates), which is behavior an agent needs to reason about partial failures.

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 core action and batch limit, then the per-line input rule, then the return/ambiguity behavior, then batching for oversized lists. No sentence is redundant and none restates the tool name.

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, yet the description still summarizes the shape of the response in one clause, which is helpful rather than duplicative. Combined with credit cost, batch ceiling, and ambiguity handling, an agent has everything needed to call this correctly and interpret partial 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%, so the baseline is 3, but the description adds genuine resolution logic not encoded in the schema: id takes precedence and name is the fallback, with set/number/game narrowing the match. The cross-game disambiguation rationale for 'game' is useful context beyond the enum's own description.

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?

Opens with a specific verb and resource ('Price a list of up to 25 cards in one call') and scopes the batch size immediately. The batch-oriented framing clearly separates it from binderdex_get_card and binderdex_search_cards, which handle single-card lookups and discovery.

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 operational guidance: use id when known, otherwise name plus set/number/game, and split lists longer than 25 into repeated batches. It also prescribes a workflow ('ask the user which card they meant before quoting a total') when results are ambiguous. It stops short of explicitly naming sibling tools as alternatives for single-card pricing, which keeps it off a 5.

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