Deckodex

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

Annotations give little signal (all false), so the description carries the load. It discloses side effects (a new list is created if listName doesn't exist), default printId behavior, and the 20-item per call limit. It does not cover possible failure modes or return behavior, but the main side effects are stated.

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 tight and front-loaded; the first sentence states purpose. The only questionable sentence is 'Deckodex Pro.' which adds little to invocation, but overall the text is short and free of 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?

For a mutating tool with no output schema, the description leaves a few gaps: it does not say what happens if both listId and listName are omitted (both are optional in the schema), and it does not describe the response shape. It covers the main selection logic but not the complete contract.

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 0%, and the description fully compensates: it explains listId (from a previous result), listName (reused/created), printId (from get_card with default), and the items limit. Only count is left to the schema, which already documents min/max.

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 a specific verb and resource: 'Add cards to one of the signed-in user's card lists (wishlists, trade binders…)' which makes the tool's purpose unambiguous. It does not explicitly name sibling tools to differentiate, but the 'card lists' concept distinguishes it from collection/deck tools.

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 provides concrete guidance on when to use by specifying the target context (signed-in user's card lists) and how to choose a list via listId or listName, including the reuse-or-create behavior. However, it never contrasts it with alternatives like update_collection or save_deck, so an agent must infer when this is the right 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 declare this a safe read-only, idempotent, closed-world operation, so the bar is lower. The description still adds real context: the result is personalized to the signed-in user, ranked by cost-effectiveness, and includes copies to buy, cost, and which decks are advanced. It does not mention auth requirements explicitly beyond 'signed-in user' or any rate limits.

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 second sentence is a legitimate clarification of return fields. The first sentence is dense and em-dash-heavy but contains no filler.

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 output schema, the description carries the return-value burden and does so by naming the fields returned (copies, cost, decks advanced) and defining fromPct/toPct. What is missing is input-side detail for limit/format/source, but the core read-only recommendation behavior is adequately framed.

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% (format and source documented; limit has only min/max/default). The description explains none of the three actual inputs and instead defines fromPct/toPct, which are not parameters — an agent could wrongly hunt for them in the input. With one genuinely undocumented parameter and no compensating input guidance, this is below the 3 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 (buy) and resource (single cards) plus a clear ranking criterion: cards that move the signed-in user closest to completing current tournament decks per money spent. The 'per money spent' framing implicitly separates it from market_movers and price_list, but no sibling is named, so it falls short of explicit differentiation.

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 scope ('current tournament decks', 'given what they already own') implies when this applies, but there is no explicit when-to-use, no when-not, and no named alternative among the 17 siblings. Usage must be inferred from the purpose sentence.

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, closed-world, so safety is covered. The description adds genuinely useful behavioral context beyond that: results are deduplicated to one per archetype, ordered closest-first, and include ownership totals, missing cards and finish cost.

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 dense sentence with the resource and result shape front-loaded and no wasted words. Every clause (archetype dedup, sort order, ownership/missing/cost) 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?

There is no output schema, so the description correctly carries the return-value burden by naming ownership count, missing cards and completion cost. It is only slightly short on how limit/format/source affect the result and whether collection coverage is required.

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 a moderate 67% and the description mentions no parameters at all. format and source are self-documented in the schema, but limit (the one parameter with no schema description) gets no clarification, and nothing indicates how limit interacts with the one-per-archetype result set.

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 scope: tournament/meta decks the signed-in user can nearly complete from their collection, deduplicated one per archetype and sorted closest-first. This clearly separates it from siblings like my_decks (user's own decks) and get_meta_deck (a single known deck) without needing to name them.

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 purpose implies when it applies (discovering near-complete meta decks), but there is no explicit when-to-use, when-not-to-use, or routing to alternatives such as get_meta_deck or get_meta. Usage is inferred 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?

Annotations already carry readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations by disclosing the composition of the returned data — meta share, results, most-played cards with average copies, and decklists — which warns the agent about the scope of the payload. Minor gaps: 'latest' and 'results' are not precisely bounded, but with rich annotations the bar is lower.

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 sentence of about 30 words carries the full purpose, scoping condition, output contents, and an alternative-tool pointer. The primary function is front-loaded ('One archetype in a format') and the sibling reference is placed at the end. Every clause earns its place with no filler.

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 output schema, the description carries the return-contract burden, and it discharges it well by enumerating the four data groups an agent can expect. Parameters are fully covered by the schema and safety by annotations. The only real gap is ambiguity about how many 'latest top tournament decklists' are returned and what 'results' encompasses, which is minor for a read-only informational 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%, with both 'format' and 'archetype' clearly documented in the input schema, including the format-code default behavior and the archetype reference back to get_meta. The description adds no parameter-level detail beyond what the schema already provides, 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 names a specific resource ('One archetype in a format') and enumerates exactly what is returned: meta share, results, most-played cards with average copies, and latest top tournament decklists. It also distinguishes itself from get_meta_deck by pointing out the scope difference, so an agent can tell it apart from siblings without inspecting 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?

The description gives explicit routing guidance for the closest sibling ('use get_meta_deck for a full list'), and the framing 'One archetype in a format' implies the selection condition: use this when you want a single archetype's detailed breakdown. It lacks a full when/when-not matrix across all siblings, but the key alternative is named with a condition, which is more than most tools provide.

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/openWorld=false, but the description adds genuinely new behavioral context: which price sources are returned, that d90Pct can be null for CardTrader until history exists, that Cardmarket d30Pct is null until ~late October 2026, and that spoiler:true cards are pre-release and may change. That freshness/caveat detail is real value beyond the 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?

Single sentence, front-loaded with the core purpose ('Full details for one card'), with the dense parentheticals carrying genuinely useful null/percentage semantics. Slightly overloaded but 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?

With no output schema, the description carries the full burden of describing the return payload — stats, effect text, keywords, rulings, every printing with multi-currency prices and change metrics, plus tournament usage — and it does so thoroughly, including null caveats.

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 with 100% schema coverage; the schema already documents the cardNumber format (GD01-001) and the description adds no extra format syntax. Baseline 3 is appropriate when 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 (get) and resource (full details for one card), and the 'one card' scope implicitly distinguishes it from the sibling search_cards list operation. An agent knows this is single-card detail retrieval, not 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?

Usage is only implied: fetch this when you already have a cardNumber and want everything about that card. It never names the alternative (search_cards) or states when-not to use it, and there is no prerequisite guidance. Adequate but leaves routing 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 declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond annotations: it is 'built from recent tournament results' and it 'Defaults to the latest format', which discloses the default-value behavior an agent needs to know. No contradiction with 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?

Two sentences with zero waste. The core purpose and output fields are front-loaded in the first sentence, and the default behavior is in the second. Every word 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?

Complete for a simple read-only list tool: one optional parameter, rich annotations covering safety/idempotency, and the description enumerates the return contents (archetype, tier, meta share, deck count, top-8 count) so no output schema is needed. 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?

With 100% schema description coverage, baseline is 3. The single 'format' parameter is well documented in the schema ('Format code like GD05; omit for the latest'). The description's 'Defaults to the latest format' largely echoes the schema, adding only marginal value. It does not add format-code syntax details 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?

The description states a specific verb+resource: 'The tournament meta for a format', enumerates exact output fields (tier, meta share, deck count, top-8 count) and the data source (recent tournament results). This clearly distinguishes it from siblings like get_archetype (a single archetype), get_meta_deck (a specific deck), and get_card (a card lookup).

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 usage context — it is the overall meta snapshot — but never explicitly names alternatives or says 'use this for the whole meta, not a single archetype/deck'. The sibling distinction is inferable from the sibling names (get_archetype, get_meta_deck) but no explicit when-to-use or when-not-to guidance is 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?

The annotations already establish this is a safe, idempotent, non-destructive read (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false). With that baseline covered, the description earns credit for disclosing the response content — placement, event, price to build, cards, and paste-ready decklist text — which is valuable given there is no output schema. It doesn't add auth, error, or missing-id behavior, so it stops 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?

A single front-loaded sentence: the primary action and the id, then the parenthetical payload list and id provenance. No filler, nothing repeated from the schema or annotations.

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 lookup with no output schema, the description adequately covers the return contents and the default behavior of the optional price source is carried by the schema. Error handling for an unknown id is the only notable omission, which is minor for this tool class.

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%: the `source` enum is documented in the schema, but `deckId` has no schema description. The description compensates by telling the agent where valid ids come from (get_archetype, buildable_meta_decks), which is semantic context the schema lacks. It still says nothing about id format or invalid-id behavior, so it is not fully compensating.

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+resource: it retrieves a full tournament decklist by id, and enumerates the payload contents (placement, event, price to build, cards, paste-ready text). It also names the sibling tools that produce valid ids (get_archetype, buildable_meta_decks), so the agent can distinguish it from get_card, get_archetype and save_deck without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The parenthetical routes the agent to get_archetype and buildable_meta_decks as the id sources, which is genuine usage guidance for the required parameter. There is no explicit when-not or alternative retrieval path, but the intended workflow 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, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds real value on currency behavior and the changePct sign/scale convention, but says nothing about ordering, ties, or what an empty market returns.

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 tight sentences, front-loaded with the core purpose and followed by the currency and changePct semantics. No filler; each sentence carries distinct information, though the changePct sentence could be merged into the parameter layering more cleanly.

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 list tool with no output schema, 4 optional params, and full annotation coverage, the description supplies the missing semantics (currency, changePct units, window/by behavior). It is nearly complete, with only return-shape/pagination left unaddressed, which is acceptable for a bounded 1-10 item result.

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%, and the description compensates meaningfully: it defines changePct as a percentage (12.5 = +12.5%), states the currency behavior when source is omitted, and pins the unit interpretation to get_card's convention. This clarifies 'by' (pct vs abs) and 'source' beyond the schema's own enum text.

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 scope: biggest gainers/losers across the Gundam market over a 7-day or monthly window, sorted by pct or absolute change. An agent can immediately tell what it returns. However, it never names the similar siblings (price_list, best_buys) it should be chosen over, so differentiation is only implied by scope.

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?

No explicit when-to-use, when-not-to-use, or alternative naming is present. The reader must infer from the name and scope that this is for market-trend queries rather than per-card pricing (price_list) or curated deals (best_buys). Cross-referencing get_card only explains a formatting convention, not selection.

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, and non-destructive behavior. The description adds useful context beyond annotations: the tool is scoped to the signed-in user, behavior differs with and without arguments, and cardNumbers aggregate across all printings. It does not describe output format or edge cases, but the annotation coverage lowers that burden.

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 two sentences, front-loaded with the core resource, and uses a clear conditional structure for the two invocation modes. Every phrase adds information; there is no repetition or filler.

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 tool with one optional parameter and no output schema, the description covers the main invocation modes and what the user can expect to get back. Minor gaps remain, such as the exact shape/format of the returned totals and completion data, and overlap with sibling tools is not addressed.

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, but the description compensates by explaining what cardNumbers does: it returns how many copies of each requested card the user owns, combining all printings. The schema already provides the format example and array constraints; the description adds the aggregation semantics and the no-argument mode.

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 clearly states what the tool does: it reads the signed-in user's collection and provides totals, per-set completion, or owned copies for given cardNumbers. It is specific about behavior based on arguments, but it does not explicitly distinguish itself from siblings like my_set_completion, which likely overlaps on the per-set completion aspect.

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 gives explicit usage context: call with no arguments for totals/completion, or with cardNumbers for per-card copy counts. It does not, however, mention when to prefer alternative tools such as my_set_completion or my_collection_value, so it lacks exclusion 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context by disclosing entitlement gating ('Deckodex Pro adds longer ranges (3M, 6M, 1Y, ALL)'), which tells an agent that certain range values depend on the user's plan.

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 what the tool returns, then the Pro extras. Two sentences with no filler, though the second sentence is a dense laundry list of Pro features that reads more like marketing than call-relevant detail.

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 output schema, the description does the work of telling the agent what comes back (current value, change over windows, Pro breakdowns like value by set and top holdings). It is close to complete for a zero-required-param read tool, missing only explicit guidance on fallback behavior when Pro 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 67% and all three params are enums. The description adds meaning for `range` by tying 3M/6M/1Y/ALL to Pro, and `mode`'s 'recorded' is already explained in the schema. Beyond that it does not add syntax or default guidance, so the 3 baseline fits.

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 ('what the signed-in user's Gundam collection is worth') plus the temporal dimension (7 days, month, longer ranges). It is clearly distinguishable from siblings like my_collection and my_set_completion, though it never names them or contrasts itself 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?

Usage is implied rather than stated: the mention of 'now and how it changed' plus Pro ranges signals valuation-over-time, but there is no explicit when-to-use-this-vs-my_collection guidance and no mention of prerequisites for the Pro-gated ranges.

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 and closed-world, so the safety profile is covered. The description adds real context beyond that: the deckId mode returns cards, rule checks, missing-card ownership gaps, and completion cost, plus it implies a signed-in user is required. Pagination or list-size limits are not mentioned.

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 tight sentences, front-loaded with the resource and then the mode branches. Every clause conveys distinct information with no filler.

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 output schema, the description must convey what comes back, and it does so for both modes (list vs. cards/rule checks/missing cards/cost). For a two-parameter read tool this is close to sufficient, though list-mode bounds and how to obtain a deckId are 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 50%: source is well documented in the schema (USD vs EUR per vendor), but deckId has no schema description. The description compensates by explaining that deckId switches the response to that deck's cards and analysis, which tells the agent what the parameter actually does. It does not state the ID format or where to obtain it.

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 resource (the signed-in user's saved decks) and splits behavior by input mode, so an agent knows exactly what it retrieves in each case. It does not explicitly contrast itself with close siblings like my_collection or validate_deck, so the distinction from those tools must still be inferred.

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 clear conditional usage: call with no arguments to get the list, call with deckId to get that deck's cards and analysis. That is effective mode-selection guidance, but it names no alternative tool (e.g., validate_deck for rule checks, my_collection for owned cards) and states no exclusions.

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, closed-world, non-destructive), so the bar is lower. The description adds real context: it reads from the user's saved Deckodex targets, and it discloses the behavioral difference between omitting set (per-set overview) and supplying set (rarity breakdown), which annotations cannot 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?

Two sentences, front-loaded with the core computation and cost before the optional-set behavior. The em-dash asides are slightly dense but each clause carries distinct meaning without redundant repetition of the 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?

With no output schema, the description does most of the work by describing return content (completeness percentage, cost to finish, per-set rarity breakdown) and default-resolution behavior. It is nearly complete, though it does not describe currency/price-source handling for the source parameter or output granularity beyond the set level.

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 baseline is 3; the description goes further by unpacking the mode enum (unique cards, playsets = 4 of each, master = every printing) and clarifying that default mode/source come from the user's saved Deckodex settings, plus what the optional set parameter adds.

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: computes how complete the user's collection is per set, with explicit mode variants (unique/playset/master) and a cost-to-finish output. It clearly differentiates from a simple collection listing by the set-level, completion-and-cost framing, though it does not name siblings like my_collection or my_collection_value.

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: the reader infers the tool is for per-set completion tracking, and 'With set: that set's rarity breakdown' hints that supplying a set changes behavior. There is no explicit when-to-use, when-not, or alternative routing versus my_collection or my_collection_value.

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). The description adds genuinely useful behavior: results are sorted most-expensive-first and each entry carries 30/90-day change and a Cardmarket price, which matters because there is no 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?

A single dense sentence that leads with the core purpose and then layers scope and returned fields. Efficient, though packing three ideas into one sentence makes it slightly hard to parse.

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 listing tool with annotations covering safety, the description is largely self-sufficient and even compensates for the missing output schema by naming the returned fields. Only the limit parameter and default behavior remain 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 50%: slug and source are documented, but limit and scope are not. The description partially compensates by explaining that slug accepts a set slug/code or rarity slug/code and by mapping the overall/set/rarity tiers to the scope concept, but it says nothing about limit or defaults.

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 (most valuable Gundam cards) and its scope axes (whole list, a set, or a rarity tier), with sort order made explicit. An agent understands what it returns, though it does not explicitly distinguish itself from siblings like market_movers or best_buys.

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 describing the three scope modes (overall/set/rarity), so an agent can infer how to query it. However there is no explicit when-to-use versus alternatives, no statement of when this beats market_movers, and no prerequisites noted.

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 indicate destructiveHint=false, meaning the tool is not destructive. The description adds that it 'never overwrites an existing deck', which provides explicit behavioral context beyond annotations. It also mentions the Pro feature, which is useful. However, it doesn't disclose potential side effects like how it interacts with the user's account or if it requires specific permissions, but the 'never overwrites' is a valuable addition.

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 concise, using three sentences with no filler. The key behavior ('as a NEW deck', 'never overwrites') is front-loaded, followed by a necessary format example that directly aids correct invocation. The 'Deckodex Pro' note is relevant and earns its place. It is well-structured and efficient.

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 tool's relative simplicity with only two parameters and no output schema, the description is fairly complete. It covers the purpose, the new-deck behavior, and the decklist format. However, it lacks details on possible errors (e.g., invalid card codes) or whether the tool creates a new entry in 'my_decks'. The absence of siblings' differentiation is a minor gap, but overall adequate for the complexity.

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 a schema description coverage of 0%, the description must compensate for undocumented parameters. It does provide a concrete format example for 'decklist' ('4 GD05-019') and specifies 'one card per line', which adds semantics. However, it doesn't explain the 'name' parameter beyond its schema (max 80 chars), and it doesn't clarify how the decklist string is parsed or if errors return. This is partial compensation but not complete.

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 clearly states the tool saves a decklist as a new deck in the user's Deckodex account, with a specific verb 'save' and resource 'deck'. It distinguishes from 'update_collection' and 'my_decks' by emphasizing 'new' and 'never overwrites', though it doesn't explicitly name a sibling alternative unlike the high-calibration example. The purpose is specific and actionable.

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 clearly states the action—saving a NEW deck and never overwriting—which implicitly sets the context for use (creating a new deck). However, it doesn't explicitly state when NOT to use this tool or how it differs from sibling tools like 'validate_deck' or 'add_to_list'. The line about 'Deckodex Pro' hints at a prerequisite but lacks explicit 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 declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds valuable behavioral context: filters combine with AND, returns up to 25 cards with deckodex.com links, and spoiler cards are pre-release and may change. This goes beyond annotations without contradicting them.

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 three sentences, front-loaded with the purpose, and each sentence adds unique value: purpose, filter behavior/limit, alternative routing, and spoiler caveat. There is no fluff or 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?

For a tool with 9 parameters, no output schema, and no required fields, the description gives enough to start (search, AND logic, link output, spoiler caution) but omits details like sorting, pagination beyond the limit, and the exact structure of returned cards. It also doesn't clarify the distinction between traits and keywords, which could be ambiguous. Adequate but not fully complete.

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 33%, so the description must compensate for the undocumented parameters. It adds the global AND-combining rule and the 25-card limit, but it does not explain the semantics of types, colors, traits, costMin/costMax, or limit beyond what the schema already provides. The low coverage and minimal compensation leave the agent guessing on several 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?

The description clearly states the verb 'Search' and the resource 'the Gundam Card Game catalog'. It distinguishes itself from the sibling get_card by explicitly saying 'Use get_card for full details, effect text and prices of one card', so an agent can easily tell them apart.

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 explicitly routes to get_card when full details of a single card are needed, providing a clear alternative. It implies the tool is for filtering/searching but doesn't state 'use this when...' explicitly, and it doesn't mention other alternatives like price_list or my_collection. However, for a search tool, the main alternative is covered.

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 destructiveHint=true and readOnlyHint=false. The description adds beyond that: clamping behavior, row limits, per-row error isolation, and the '0 removes' semantics. It also notes that printId defaults to the standard released printing, which is non-obvious. This provides actionable detail without contradicting 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?

The description is a single paragraph with multiple sentences, but each sentence adds a distinct piece of information: mode behavior, clamping, row limit, error isolation, and printId default. It is front-loaded with the main purpose and avoids fluff, though the density could be slightly streamlined. Still, it earns its length.

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 mutation tool with destructiveHint=true and no output schema, the description covers all critical calling constraints: how to specify changes, limits, error handling, and defaults. It also hints at the response format ('each row reports before/after'), giving the agent a clear picture of what to expect. Nothing essential is missing for a correct call.

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 0%—only cardNumber has a description. The description explains the meaning of 'mode' ('add' vs 'set'), the effect of count (including 0 removal and clamping), the role of printId, and the row limit. It fully compensates for the missing schema descriptions, making parameters self-explanatory.

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 clearly states the verb 'Change' and the resource 'owned counts in the signed-in user's collection', distinguishing it from read-only siblings like my_collection. It also specifies the two modes ('add' and 'set') and the effect of 'set' with 0, which uniquely identifies this as the update tool.

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 provides explicit behavioral context: mode semantics, count clamping (0–99), row limit (up to 20), partial failure (a bad row doesn't block others), and the default for printId. While it doesn't name alternative tools for when not to use it, the context is specific enough that an agent can infer when to call this tool for collection updates.

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 safety is covered. The description adds real behavioral context beyond that: precisely which rules are enforced and that pricing is included, which the agent could not infer from 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?

Two tight sentences, front-loaded with the validation scope, followed by the input format. No filler, though the parenthetical rule list is slightly dense.

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 output schema, the description should indicate what a validation result looks like (valid/invalid, error listing) or how pricing is returned. It covers inputs and rules well but leaves the response shape unspecified for a tool whose whole purpose is reporting a check result.

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% — the 'source' enum is documented in the schema, but 'decklist' has no schema description. The description compensates by specifying the exact line format and giving examples ('4 GD05-019', 'Side Deck' marker), adding substantial meaning for the undocumented 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?

States a specific verb (check/validate) plus the resource (decklist), and enumerates exactly what is validated (50-card main, max 4 copies, 2 colors, banlist, sideboard) in addition to pricing. This clearly separates it from siblings like price_list or save_deck.

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 effectively tells the agent when the tool applies via the input format and what it validates, but it never names alternatives or exclusions (e.g. use save_deck to persist, price_list for pricing only). Usage is implied rather than stated.

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