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

Annotations only cover readOnlyHint and openWorldHint; the description adds genuinely useful behavior the annotations don't: case-sensitive substring matching, inclusion of support cards via YGOProDeck tags or quoted text mentions, and card text returned only when the result is <= 60 cards unless include_text is set. That is real conditional-output disclosure. It stops short of 5 only because the returned structure is not characterized.

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 dense sentences with no filler; the core matching rule leads and the conditional output rule follows. Minor awkwardness in 'with status in `format`' slightly muddies an otherwise front-loaded, efficiently sized description.

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 three-parameter read-only query tool with no output schema and 0% schema coverage, the description supplies the matching rule, the support-card behavior, and the conditional text-inclusion rule, leaving little an agent needs unknown. Only the shape of the response is unspecified, which is a minor gap given no output schema exists.

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%, so the description must compensate, and it largely does: it explains `name` as a case-sensitive substring match, ties `format` to membership status, and explains that `include_text` overrides the small-result text-inclusion rule. Only the exact meaning of the `format` enum values is left 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?

The description states a specific resource and scope: an archetype's members matched by case-sensitive substring on `name`, filtered by `format`, plus YGOProDeck support cards tagged with or naming it. An agent can tell this is an archetype-wide retrieval rather than a single-card lookup. It doesn't explicitly name a sibling to contrast with, keeping it just 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?

Usage is only implied: querying a whole archetype plus its support instead of a single card. There is no explicit 'use this instead of search_cards when...' routing, no prerequisites, and no statement of when not to use it, despite the sibling list containing search_cards and card_lookup.

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?

With readOnlyHint and openWorldHint already covering the safety profile, the description adds substantial non-obvious behavior: the exact set of returned fields, the existence of unresolved_mentions for unmatched quoted names, and the deliberate no-guessing fallback to candidates on ambiguous input.

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 dense with value; nearly every clause adds a distinct fact. The middle sentence is a run-on list ('limit, Genesys points, legality and why not') that is slightly harder to parse than it needs to be.

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 must describe the return surface — and it does: full text, stats, per-format legality, alt passcodes, quoted names, rulings links, plus the unresolved_mentions edge case and the ambiguous-input behavior. Nothing an agent needs to invoke and interpret this tool 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 0% and the single parameter has no description, so the description carries the burden — and it does, explaining that query accepts either a card name or a passcode and how ambiguous values are handled. It stops short of syntax details (case sensitivity, quoting rules) but is well beyond the bare 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 ('One card by name or passcode') and enumerates the payload the caller gets back (text, stats, format status, rulings links). It implicitly separates itself from search_cards by scoping to a single card, but never names a sibling, so it falls short of full sibling 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?

Usage is implied: this is the single-card lookup, and the note that unknown/ambiguous names return candidates rather than a guess tells the agent the fallback path. There is no explicit 'use this when X, use search_cards when Y' guidance or stated 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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses caching, per-call request caps with a note when more remain, a note when no Q&A discusses both cards (interaction unverified), and the OCG-vs-TCG caveat with an instruction to quote rather than extend rulings. This is unusually rich behavioral context for a read-only 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?

Front-loaded with purpose, then labeled lines for with_card and query, then return-shape and caveats. Dense but every sentence adds something; the source parenthetical and return-field enumeration make it longer than strictly minimal.

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 supplies the return shape (title, question, answer, date, translation status, names_in_text) and the ordering rule that text-matching Q&As precede omnibus entries. Nothing essential 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?

Schema description coverage is 0%, so the description carries the load: it explains with_card (dual-card filtering) and query (all-words match) with examples, and the cap note implies limit's behavior. It does not directly define the `limit` or `card` parameters' formats, so it falls slightly short of full compensation.

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: 'Official FAQ and Q&A rulings for a card', naming the authoritative source (Konami OCG database via YGOResources). This is clearly distinct from sibling lookup/search tools like card_lookup or search_cards, which return card data rather than rulings.

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 usage guidance per mode, e.g. with_card is 'best for "does X work with Y" questions' and query filters by words like "cost banish". However, it never names an alternative tool or states when not to use this one, so routing versus siblings 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.

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

Annotations declare a safe, idempotent, non-destructive write, and the description goes beyond them by disclosing exactly what gets written (data/decks/<name>.<format>.ydk plus a .json with ydke:// URL, decklist, points/ban breakdown, as-of date), the failure mode (nothing written, problems returned), and the overwrite/history behavior. This is rich behavioral context that matches the declared safety profile rather than contradicting it.

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 critical precondition before the output details. The parenthetical aside is slightly dense but each sentence earns its place; 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?

For a no-output-schema tool the description usefully describes the returned artifacts and the ydk path handed to follow-ups. However, with 7 parameters at 0% coverage, an agent still lacks any guidance on how to supply decklist, ydk_text/ydk_path, notes, or point_cap, leaving a real gap for a complex mutation 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 0% across 7 parameters, so the description carries the full documentation burden, yet it names no parameters. The path template "<name>.<format>" only faintly implies the name and format arguments, and nothing explains notes, decklist, ydk_path, ydk_text, or point_cap.

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 ("Save a finished deck") and immediately differentiates itself from the sibling validate_deck by framing saving as conditional on validation. An agent can tell this is the terminal persistence step versus validation or lookup siblings 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?

It gives an explicit precondition (only save if validate_deck says it is legal) and names the alternative flow (follow-up questions pass the returned ydk path to validate_deck or find_links). It lacks an explicit "do not use this when..." against a competing save tool, but the gating condition covers most of the routing decision.

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 only say non-read-only, non-destructive, non-idempotent; the description goes well beyond by disclosing the async job_id pattern with per-depth timings, the deck-stacking mechanics, the scoring methodology (interruptions left live plus hand traps), the 'search result, not a solver' caveat, and the environment prerequisite failure mode.

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 action, then timing, then parameter guidance, then caveats – every clause carries information. It is a dense single block rather than a structured list, which costs a little scannability but no sentence is wasted.

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 still states the return contract (a job_id, retrieved via line_result) and the caveats an agent needs (search-not-solver framing, prerequisite environment, recommended starting depth). 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 coverage is 0%, so the description carries the full burden and does: hand = 5 card names or passcodes, deck = exactly one of saved_deck/ydk_path/ydk_text/decklist, executor = 'module:Class' with a concrete example, and depth = quick/normal/deep with latency expectations.

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 gives a specific verb and resource ('find the turn-1 lines a starting hand makes, going first') and immediately names the mechanism (searching the real EDOPro engine with a stacked deck). It is clearly distinguishable from siblings like line_result (fetch results) and card_rulings (verify rulings).

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?

Explicit trigger: 'Run it when the user asks for a specific hand's line, starting with depth "quick".' It routes the agent to line_result for fetching and card_rulings for rules verification, and states the prerequisite (YGOSIM_HOME checkout, otherwise an error).

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 cover the safety profile (readOnlyHint, openWorldHint), and the description adds meaningful caveats beyond that: 'Links are parsed from card text, not verified rulings', the instruction to read evidence/ruling_flags and validate_deck, the Genesys point-limitation rule, and more_not_shown for truncated items. These are real behavioral disclosures an agent cannot get from 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?

It is front-loaded with purpose and the 'fetch' definition, but the body is a dense, indentation-heavy enumeration of output sections with idiosyncratic spacing that reads like copied field docs rather than a curated description. Much of it is necessary given no output schema, but the structure is hard to scan.

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 usefully enumerates and explains each result section, which is genuinely helpful. But for a 9-parameter tool at 0% schema coverage it omits how the input options (cards vs decklist vs ydk_path/ydk_text, archetypes, limit) relate, so an agent still can't call it correctly from the description alone.

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% across 9 parameters, so the description must carry the burden. It explains format, point_cap/point_cap-vs-max_points interaction, but leaves cards, decklist, ydk_path, ydk_text, archetypes and limit entirely unexplained, including the mutually-exclusive deck-input options — a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line states the resource produced: bridges and support (cards that 'fetch' your cards) for a deck or a few cards, constrained by format and budget. The definition of 'fetch' makes the domain precise. However it never distinguishes itself from the similarly named sibling find_lines, leaving an agent to guess which retrieval tool to pick.

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 partial routing guidance ('check these first' for your_archetypes_unplayed, 'validate_deck any final list', and the Genesys point-cap rule), but no explicit statement of when to use find_links versus find_lines, search_cards, or archetype. Usage is implied by the output-section list rather than declared.

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 cover the safety profile (readOnlyHint, openWorldHint), so the description adds value by disclosing the status state machine (running/done/failed), the shape of the done payload (hand, lines ordered best-first, steps, end board, remaining hand, surviving interruptions), and the edge case that unplayable cards are reported. That is meaningful behavioral context beyond 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?

Single front-loaded sentence that leads with the tool's identity and then enumerates the payload, with no filler. The colon-separated clauses stay dense and readable. Slightly list-like but appropriately sized.

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?

No output schema exists, so the description must describe return values, and it does so thoroughly for the 'done' case. Gaps remain: the 'running' and 'failed' payloads and the source of job_id are not addressed, and there is no polling guidance. Still largely complete for a result-retrieval 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?

There is one parameter, job_id, with 0% schema description coverage, so the description must carry the burden of explaining it. It never mentions job_id, where it comes from, or its format, even though the whole tool is keyed on it. The meaning is only loosely inferred from 'Result of a find_lines search.'

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 and scope: it returns the result of a find_lines search, including the status lifecycle and the result contents. It differentiates from the sibling find_lines by framing itself as the result-retrieval counterpart. The core verb (retrieve/poll a job's result) is only implied by the noun phrase rather than stated outright.

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?

Naming find_lines implies this is where you fetch that search's output, but the description never explicitly says 'call this with the job_id returned by find_lines,' nor does it explain polling/retry behavior while status is 'running'. Usage is inferable from the sibling reference rather than spelled out.

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 and openWorldHint, so the safety profile is covered. The description adds one genuine behavioral note (near-miss deck type names are suggested), but says nothing about data freshness, time-window behavior, truncation, or result shape.

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 dense sentences with the primary output description front-loaded and the parameter rule trailing. Nothing is padded, though the parenthetical stack makes the first sentence 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?

With five parameters, 0% schema coverage, and no output schema, the description covers the two main arguments and the exclusivity rule but omits the required-adjacent knobs (days, limit) and the format enum values. An agent can make a reasonable call but may misuse the undocumented controls.

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%, so the description must carry all parameter meaning. It explains card and deck_type (including the mutually exclusive rule) but never mentions format, days, or limit, leaving three of five parameters undocumented anywhere.

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 resource (card inclusion stats in recent tops) and spells out the two distinct output modes: per-card play rate and a deck type's inclusion table. It's specific about what data comes back but never distinguishes itself from siblings like meta_snapshot or archetype.

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

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

It gives an explicit operating rule: 'Pass exactly one of card, deck_type,' and hints that near-miss deck type names are resolved. That is clear selection guidance, though it doesn't say when to prefer this over meta_snapshot or other siblings.

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 and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context about what the payload contains (legality under today's list, average points for Genesys, common blockers), but says nothing about data freshness/lag, rate limits, or error behavior.

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 resource and its scope, with the format clarification placed last. The long field enumeration is dense but each item maps to real payload content, so little is wasted.

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 right work by enumerating the returned aggregates, which is enough for an agent to know what it gets back. Gaps remain around the meaning of 'top'/'days' and any freshness or pagination 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?

Schema description coverage is 0%, so the description must carry the load. It fully disambiguates the required 'format' enum (Genesys = Genesys events; Advanced = TCG lists outside Genesys and OCG), but 'top' (default 15) and 'days' (default 60) are never explained — only implicitly hinted at by 'Recent tournament tops'.

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 concrete resource and enumerates its scope precisely: recent tournament tops, deck-type shares, top-8s/wins, legality counts, most_common_blockers, and most-played cards. An agent can tell this is a meta-aggregate snapshot rather than a card- or deck-level tool. However, it never explicitly contrasts itself with the closest sibling (meta_inclusion), so it stops 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 statement of when to reach for this tool versus meta_inclusion, archetype, or search_cards — usage is only inferable from the returned-field list. The only routing-style help given is defining the format enum values, which is parameter semantics rather than 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 declare readOnlyHint and openWorldHint, and the description adds genuine value on top: result ordering (newest first) and the exact field set returned. It does not cover pagination, result limits, or whether the format parameter narrows the list, so it stops short of 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 compact sentence, front-loaded with the resource and provenance, followed by the return fields. Nothing is padded and 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 no output schema, the description usefully enumerates returned fields, and annotations cover the safety profile. However, it omits the semantics of the format filter, pagination/limit behavior, and whether an empty result is possible, leaving gaps for a listing 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?

The single 'format' parameter has 0% schema description coverage and enum values (tcg_advanced, genesys) that are never explained. The description's mention of 'format' refers to an output field, not the input filter, so it does not compensate for the schema gap and could even mislead about what the parameter does.

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?

Identifies the exact resource ('decks saved with finalize_deck') and its ordering ('newest first'), letting an agent distinguish it from siblings like finalize_deck or search_cards. The verb (list/retrieve) is only implied rather than stated, which keeps it just 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?

Usage is only implied through the reference to finalize_deck as the producer of these records, so an agent can infer 'call this to see what you saved'. There is no explicit when-to-use/when-not statement or named alternative, and the role of the format parameter as a filter is not clarified.

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 only declare readOnlyHint and openWorldHint; the description adds genuinely useful behavior beyond that, notably the default legality filter and the disclosure that card text is truncated to 400 characters unless full_text is set. It does not cover result ordering or the effect of limit, but the truncation and filtering notes are exactly the kind of context annotations cannot carry.

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?

Opens with the core purpose in one sentence, then a compact parameter glossary with a worked example per non-obvious field. Every line earns its place and nothing is padded.

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 17-parameter tool with no output schema and no schema descriptions, the semantic coverage is strong and the search-syntax nuances are explicit. The main gap is silent handling of limit (default 20) and count/ordering behavior, which the agent must infer.

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 0% schema description coverage across 17 parameters, the description carries the full burden and largely succeeds: it explains text as FTS5 syntax, pattern as Python regex, name as substring, archetype as case-sensitive name containment, mentions as quoted-name references, kind/attribute/race vocabularies, and level/rank/link semantics for level_min/max. Only limit, atk_max, and def_max are left undocumented, and the depth it provides on the ambiguous filters far exceeds what a schema could convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search the card pool') and immediately scopes the default result set to cards legal in the given format. This distinguishes it from siblings like card_lookup (single card retrieval) and archetype without needing to inspect 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 conveys an important default behavior (illegal cards excluded unless include_illegal) but never states when an agent should choose this tool over card_lookup, find_lines, or archetype, nor does it describe any prerequisites. Usage is implied rather than guided.

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 and openWorldHint, and the description is consistent with them ('Check', no mutation). Beyond the annotations it adds real behavioral detail: legal tri-states to null on unknown passcodes/ambiguous names, nothing is dropped or guessed, and resolved_names flags normalized matches. It does not describe rate limits or output volume for large decks.

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 and the mutual-exclusion rule are front-loaded, and the indented parameter/format breakdown is scannable. It is somewhat long and the format/genesys block is dense, but nearly every sentence carries unique information rather than restating 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?

There is no output schema, and the description compensates by explaining the return contract (legal, resolved_names, parse_errors) and the null/failure semantics. Combined with the documented input modes, an agent has enough to call the tool and interpret the result without guessing.

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%, so the description must carry the parameter burden and it does: ydk_path (with WSL path syntax), ydk_text (including ydke:// URLs), decklist shape with entry-format examples, the format enum values with their rules, as_of date semantics, and point_cap inside the genesys rules. All six parameters are given meaning not present in 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?

Opens with a specific verb+resource+outcome: 'Check a deck against a format and list every card with its ban status or Genesys points.' That scope is clearly distinct from siblings like search_cards, card_lookup, or finalize_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?

Explicitly states 'Give exactly one deck input' and enumerates the three mutually exclusive input modes (ydk_path / ydk_text / decklist), plus what to do when legal is null ('fix parse_errors and call again'). It gives strong context but never names an alternative sibling tool or the conditions under which another tool would be preferable.

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