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

With no annotations, the description carries the full burden. It discloses parsing behavior (accepted quantities, comment syntax), report contents (curve, inkable counts, legality, unresolved names), and notes the 'estimated' nature of lore-per-turn. This is thorough behavioral detail, though it does not explicitly address side effects or error handling.

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 yet information-dense. It front-loads the primary purpose, then provides necessary parsing and report details in a structured way without redundant or filler content. Every sentence adds value.

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 single parameter and existing output schema, the description is complete: it covers input syntax, edge cases, report items, legality rules, and unresolved-name reporting. No critical gaps remain for an agent to invoke this tool effectively.

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 schema provides only a bare string parameter with no description (0% coverage). The description fully compensates by explaining the expected format, examples, optional quantity, comment handling, and what the deck_list should contain. This is far beyond what the schema offers.

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's function: 'Analyze a raw deck list and return curve, composition, and legality stats.' This is a specific verb+resource pairing that distinguishes it from siblings like build_deck (construction) or lookup_card (single 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 provides clear context: it is for analyzing raw deck lists, with detailed input format and expected output. It does not explicitly name alternatives or give when-not-to-use guidance, but the scope is unambiguous enough to guide selection among sibling tools.

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

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

There are no annotations, so the description carries the full burden. It discloses what data is checked and that it excludes promo cards, but it does not describe the output format, whether it modifies the CSV, or any API-related behavior (e.g., rate limits, failure modes). The description adds value but leaves several behavioral aspects implicit.

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 and well-structured: a one-sentence summary, a brief detail paragraph, and a compact args section. Every sentence provides useful information without redundancy or fluff.

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?

The tool has a single simple parameter and an output schema (not shown), so the description does not need to detail return values. It covers the core purpose, when to use it, and parameter semantics. It could mention that the audit involves live API calls and potential latency, but overall it is sufficiently complete for the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema only defines 'csv_path' as a required string with no description. The tool description adds meaningful semantics by specifying it must be an 'Absolute path to an enriched Lorcana collection CSV,' clarifying the exact expected input 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 uses a specific verb ('Audit') and resource ('enriched Lorcana collection CSV against live API data'), clearly stating the tool's function. It also enumerates exactly which fields are checked (Ink color, cost, card type, etc.), distinguishing it from sibling tools like enrich_csv or search_cards.

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

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

The description explicitly states when the tool is useful ('after a new set releases or if enrichment data looks suspicious'), providing clear context for usage. It does not explicitly name alternative tools or exclusion scenarios, but the use cases are sufficiently specific.

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 no annotations, the description fully carries the burden. It discloses heuristic behavior (curve/keyword-value optimization), ownership capping, honest shortfall reporting, pricing via tcgcsv.com, rotation restrictions, and the disclaimer at the bottom of results. It also explains the no-op/ignored parameter behavior, providing a transparent view of internal logic.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and mode overview, then uses a bulleted list for modes and a labeled 'Args:' block. Every sentence adds distinctive information—no filler or redundant restatements. The length is justified by the tool's complexity (5 params, 3 modes, multiple formats).

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 complexity and the absence of annotations, the description covers all essential aspects: parameter semantics, mode behavior, constraints, edge-case handling (shortfall, no-op), and pricing integration. An output schema exists, so not describing return values is acceptable, and the description mentions the disclaimer for result interpretation.

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%, but the description compensates completely by explaining every parameter: ink_colors format and allowed counts per format, the three mode values, accepted format values, collection_csv path requirements and when it's required/optional/ignored, and rotation_safe's conditional behavior. This far exceeds what the schema's bare titles/defaults provide.

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

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

The description clearly states the tool's function: 'Automatically assemble a legal, curve-balanced ~60-card decklist for an ink pair and format'. It specifies the verb (assemble), resource (decklist), and scope (modes, format), and differentiates from sibling tools like filter_collection or analyze_deck by focusing on deck generation rather than collection management or analysis.

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 explicitly explains when to use each of the three modes ('collection', 'ideal', 'market') with conditions and outcomes, including details such as required collection_csv for 'collection', optional for 'ideal', and ignored for 'market'. It also notes the no-op behavior for rotation_safe in non-core formats and calls out the tool's limitations ('not multi-card combos or synergy packages'), which guides users to alternatives.

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

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

With no annotations provided, the description carries the full burden. It pays off by disclosing external API calls (LorcanaJSON, lorcana-api.com), output file creation, cache behavior, and price overwrite behavior. It stops short of mentioning rate limits, network requirements, or error handling, but the disclosed traits are substantial and accurate, a minor gap prevents a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded: a one-sentence summary, a compact list of output files, then an Args section. No redundant words; each sentence adds information about the tool's operation or parameters, maintaining conciseness without sacrificing 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?

Given the tool's complexity (3 parameters, external API calls, file outputs) and the existence of an output schema (which likely covers return values), the description is complete. It covers inputs, behavior, output file naming, and parameter semantics, providing an agent with enough context to select and invoke it correctly without ambiguity.

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 compensates fully. Each parameter gets a clear, purpose-driven explanation: input_path (absolute path to raw export), cache_path (speeds re-runs by skipping API calls), refresh_prices (overwrites with live tcgcsv lookup). This goes far beyond the schema's bare names and types, meeting the high need.

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: 'Enrich a raw TCGPlayer Lorcana CSV export with full card data.' It clearly distinguishes this from sibling tools like lookup_card or filter_collection by focusing on file transformation with API enrichment, and lists added fields and output files, making the purpose unmistakable.

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 implies the primary use case (processing a raw TCGPlayer export) and explains optional parameters for re-runs (cache_path) and price refreshing (refresh_prices). However, it does not explicitly state when not to use the tool or compare with alternatives like audit_csv, so it lacks explicit exclusions, though context is strong.

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

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

The description discloses the data provenance (duels.ink) and explains that Poorcana legality is derived from the Rarity column without external lookups. However, it does not mention side effects (e.g., whether it writes a new file or overwrites) or any other behavioral traits. With no annotations, this is a partial gap.

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 and well-structured: a one-sentence purpose, a brief note on data source, and a clear Args section. No wasted words; each sentence 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?

Given the moderate complexity (2 params, output schema present), the description covers the core context: what it filters, input requirements, and format definitions. It could be more explicit about what the output is (e.g., a new CSV, a printed table), but the output schema likely covers return structure. Overall, reasonably 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 coverage is 0%, so the description carries the full burden. It explains csv_path as 'absolute path to an enriched Lorcana collection CSV' and enumerates all format values with their string literals, adding meaning 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?

The description clearly states the tool filters an enriched collection CSV to cards legal in a specific play format, using a specific verb+resource+scope. This distinguishes it from sibling tools like search_cards, build_deck, or enrich_csv, which have different purposes.

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

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

The description implies the tool requires an 'enriched collection CSV' (a precondition) and lists the supported formats, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. Usage guidance is present but not fully explicit.

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 no annotations provided, the description fully discloses behavioral traits: it explains the Singer keyword rule, how the matching works, the grouping order (Singer-keyword characters first, then cost-outright characters), and the effect of passing a collection_csv (flagging owned copies). It also transparently notes that song_name is fuzzy-matched the same way as resolve_card, adding cross-tool context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by a clear explanation of the matching logic and a structured Args list. It is somewhat dense due to the detailed Singer explanation, but every sentence contributes necessary context. The structure is logical and easy 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?

For a tool with 5 parameters, no annotations, and a moderately complex algorithm, the description is remarkably complete. It covers the singer matching rule, output grouping, each parameter's semantics, the optional CSV integration, and even references the fuzzy resolution behavior of a sibling tool. No significant missing context remains for correct invocation.

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 does so thoroughly. The Args section explains each of the 5 parameters (song_name, cost, colors, collection_csv, limit) with concrete examples and the mutual-exclusion constraint between song_name and cost. This goes far beyond the bare schema fields.

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: 'Find every Character that can sing a given song', clearly stating the tool's core function. It distinguishes itself from sibling tools like search_cards or lookup_card by focusing on song-character synergy and the Singer keyword mechanic. The detailed matching rule further clarifies the exact purpose.

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 clear context for when to use the tool: to identify free-song Singer combos and discover which characters can sing a song. It also gives an explicit input constraint ('Provide either song_name ... or a raw cost threshold — not both') that acts as usage guidance. It does not explicitly name alternative sibling tools, but the specialized use case is evident.

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 no annotations provided, the description carries the transparency burden. It discloses matching behavior (exact then partial), data sources (LorcanaJSON and duels.ink), set selection logic (most recent unless set_name is specified), and return contents (stats, abilities, legality, image URL). It does not mention error handling or rate limits, but for a read-only lookup this is fairly transparent.

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 and well-structured: a clear opener stating purpose and return value, two sentences covering matching and data sources, and a compact Args section. Every sentence adds useful 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?

Given that an output schema exists, the description does not need to enumerate return fields in detail. It covers purpose, parameters, data sources, matching behavior, and edge cases like multiple printings. This is complete for a lookup tool with a small parameter set.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema only lists parameter names and a default, with 0% schema description coverage. The description fully compensates through an Args section: it explains that 'name' accepts exact or partial matches, provides examples, and clarifies that 'set_name' is optional and narrows the search. This adds essential meaning 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 clearly states the tool's function: 'Look up a Lorcana card by name and return its full stats, abilities, and legality.' It specifies the resource (Lorcana cards), the action (look up by name), and key details like exact/partial matching and data sources, distinguishing it from broader search or filtering 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?

The description gives clear usage context: provide a card name, optionally a set name to disambiguate. It explains fallback behavior and most-recent-printing behavior without explicitly naming alternatives. This is clear context with no exclusions, though it could have referenced sibling tools for stronger differentiation.

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 no annotations, the description carries the full burden of behavioral disclosure. It reveals the tool's tolerance for typos, missing dashes, missing subtitles, and word order, and details the three possible return shapes (single match, top-3 list, no match). This gives the agent a complete understanding of what to expect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and efficient: a one-sentence summary, a brief behavior paragraph, a list of return shapes, and an Args block. Every sentence earns its place, and the format is easy for an agent 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?

Given the output schema exists, the description covers all necessary context: the tool's purpose, its behavior, when to use it (vs. lookup_card), and the possible outcomes including the no-match scenario. It is comprehensive for a fuzzy-matching lookup 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 schema provides no parameter descriptions (0% coverage), but the description compensates fully. The Args section explains that `name` accepts informal, partial, or misspelled names, and `set_name` is an optional narrow with an example ('Wilds Unknown'). This adds significant meaning 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 clearly states the tool's purpose with a specific verb ('Resolve') and resource ('informal, misspelled, or subtitle-less card name to specific card(s)'). It explicitly distinguishes this tool from lookup_card by contrasting its tokenization and scoring approach with substring matching.

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 direct usage guidance: 'Use this when lookup_card fails or when you're not sure of a card's exact printed name.' This explicitly states when to use this tool and names the alternative (lookup_card), making the selection criteria clear.

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?

Even though no annotations are provided, the description discloses non-obvious behavior: all filters are ANDed except colors (which are ORed), colors and ability_text are case-insensitive, cost bounds are inclusive, and limit is capped at 200. This goes beyond the raw schema by explaining query semantics, though it omits error handling and auth/permission notes.

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 and front-loaded: a one-sentence purpose, a brief note on filter combination, then a clean Args list. Each parameter gets a single informative line with no redundancy. The structure is easy to scan and appropriately sized for 11 parameters.

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 11 parameters, zero schema descriptions, and an output schema present, the description covers all necessary context: full parameter semantics, filter logic, examples, and pagination details. It does not need to describe return values since the output schema exists, but it could benefit from a note on alternative tools, which is a separate dimension.

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%, but the description fully compensates by documenting every one of the 11 parameters: types, defaults, valid enum values for card_type and rarity, examples, and specific behavior like 'Pass -1 for no minimum/maximum'. This is exemplary parameter-level guidance.

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

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

The description opens with a specific verb+resource: 'Search the full Lorcana card pool by any combination of filters.' This clearly distinguishes it from siblings like filter_collection (which presumably filters a collection) and lookup_card (which likely fetches a single card). The scope is explicit and unambiguous.

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

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

No explicit guidance is given on when to use this tool versus alternatives. It does not mention 'use this when you need broad search' or contrast with lookup_card/resolve_card. The filter combination explanation implies usage but does not guide selection among 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?

No annotations are provided, so the description carries the full burden. It thoroughly discloses behavioral traits: first checks CSV's own TCG Market Price for owned cards (no network), falls back to live TCGPlayer lookup only for zero-copy cards (cheapest printing), caches fallback data for 24 hours, and only fetches if actually needed. This goes beyond a simple 'read-only' hint and covers conditional behavior, data source, and caching.

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 longer than minimal, but every sentence adds value. It is front-loaded with a one-sentence summary, then details mechanics and args. It might be slightly dense, but no filler or redundancy. The structure with separate paragraphs and an Args section aids readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, return values need not be described. The description covers input formats, pricing logic, fallback behavior, and caching, which is thorough for a tool with two parameters. However, it does not mention error conditions (e.g., invalid CSV, missing cards in TCGPlayer lookup) or network dependencies beyond tcgcsv.com, leaving a small gap for full completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, but the description compensates fully. It explains deck_list is 'raw deck list text, one card per line (e.g. "4x Goofy - Musketeer")' and collection_csv is 'absolute path to an enriched Lorcana collection CSV.' It also mentions the expected format is identical to analyze_deck, giving clear semantic meaning beyond simple field names.

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 clear action: 'Compare a deck list against your collection: what you own, what's missing, and the estimated cost to complete it.' This states the specific verb (compare/cross-reference), resources (deck list and collection CSV), and output (owned/missing/cost). It also distinguishes from sibling tools like analyze_deck by explicitly focusing on collection comparison, not just deck analysis.

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 context for when to use the tool: when you have a deck list and want to see collection completeness/cost. It references 'same format as analyze_deck,' implying analyze_deck is the alternative for deck-only analysis. However, it does not explicitly state 'use this instead of X when...' or list exclusions, so it's clear but not fully explicit.

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