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

With no annotations, the description carries the burden and does well: it discloses that the tool returns multiple technical fields plus a `human_summary`, and explicitly warns against citing technical values in human-facing text. This goes beyond the schema and adds crucial behavioral context, though it doesn't describe the content of human_summary or any effects.

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

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

The purpose is front-loaded in the first sentence, and the warning is clearly separated. The second sentence is somewhat verbose with repeated emphasis ('IMPORTANTE', 'NUNCA'), but it's still compact and every part 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 tool's low complexity (one param, no output schema), the description provides sufficient context: what the tool does, what output fields exist, and how to handle them. It doesn't fully describe the content of `human_summary` or edge cases, but it's complete enough for an agent to use it correctly.

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

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

Schema coverage is 100% (the only parameter image_url is described as 'URL da imagem do produto'). The description adds only that the URL is for a product image, which is already implied by the schema and tool name, so it provides no meaningful additional parameter semantics.

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 a specific verb ('analisa') and resource ('imagem de um produto (por URL)'), and enumerates the analyzed aspects: resolução, proporção, fundo, nitidez, prontidão. This distinguishes it from siblings like analyze_url or ocr_image, which target other concerns.

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 a strong when-not instruction: use `human_summary` for the store owner and never expose internal diagnostic fields to humans. It doesn't mention alternatives or explicitly state when to use this tool versus siblings, but the context makes it clear it's for product image quality assessment.

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 of behavioral disclosure. It describes the action (scraping and diagnosing), the extracted fields, and the return value ('diagnóstico de prontidão por seção'). It does not mention side effects or error handling, but it clearly implies a read-only audit operation, which is sufficient for a simple scraping 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?

The description is three sentences: the first states the core action, the second lists what is extracted and returned, and the third gives the ideal usage context. Each sentence earns its place with no unnecessary words or repetition.

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?

Without an output schema, the description provides a clear summary of the tool's purpose, inputs, and output. It names specific extracted fields and the diagnostic nature of the result. Given the tool's simplicity (one parameter), this is nearly complete, though it could have elaborated on the 'sections' of the diagnosis or potential prerequisites.

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% because the only parameter 'url' is already described as 'URL do produto na loja (http/https)'. The description reinforces this by mentioning 'link do produto' but adds no new semantic details beyond the schema, so the baseline score 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 clearly states the verb 'Raspa e diagnostica' (scrapes and diagnoses) and the resource 'página de um produto na loja própria do cliente' (product page on the client's own store). It also lists specific extractions and the diagnostic output, distinguishing it from sibling tools like analyze_image or lookup_ean.

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 an explicit use case: 'Ideal para: o lojista cola o link do produto e o agente audita' (ideal for when the store owner pastes the product link and the agent audits). This gives clear context, though it does not mention when not to use it or alternatives, so it falls short of a 5.

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

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

With no annotations to rely on, the description discloses several behavioral aspects: it processes products one by one, returns a consolidated report with enriched items/failures/warnings, and produces storefront-ready output. This implies a non-destructive, orchestration-style operation and indicates graceful error handling. However, it does not mention authentication, rate limits, or external service calls, which would be needed for full transparency.

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, well-structured sentence that front-loads the core concept ('Orquestrador de lote') and follows with the specific action and outcome. It contains no filler or redundant information, achieving maximum efficiency.

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 description covers the high-level purpose and output but lacks essential context: it does not explain what the options do, how failures/warnings are structured, potential constraints, or the relationship to sibling tools like enrich_product. Given the nested schema and absence of an output schema, the description leaves clear gaps for a complex batch 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 description provides no meaning for the 'products' array structure (ean, brand, title, etc.) or the 'options' object (locale, with_ai, with_images). With schema description coverage at 0%, the description was expected to compensate, but it only refers to 'raw products' generically. The agent must rely entirely on the schema for parameter understanding.

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 identifies the tool as a batch orchestrator that applies the enrichment pipeline to a list of raw products and returns a consolidated report with enriched products, failures, and warnings. The verb 'aplica' and resource 'pipeline de enriquecimento' specify the action and object, and the mention of 'lote' distinguishes it from single-enrichment tools like enrich_product.

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 conveys the intended usage: processing a batch of raw products for storefront import, with output ready for import. However, it does not explicitly mention alternatives or when-not-to-use scenarios, such as using enrich_product for single products. This makes the context clear but not fully explicit, meriting a 4 rather than 5.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does this well by highlighting the critical with_images behavior: the default produces lightweight JSON, while with_images=true embeds base64 and can balloon to 100k+ tokens. It also lists the full transformation pipeline, giving the agent a clear picture of what happens to the product. It doesn't mention side effects like API costs or rate limits, but the most important caveat is covered.

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 that conveys a lot of information without unnecessary filler. The 'IMPORTANTE' warning draws attention to the token implication. It is moderately dense but well-organized; breaking it into bullets would improve scannability, but it is still effective.

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 lack of an output schema, the description provides a solid high-level view of the output (storefront-ready product) and the enrichment steps. It also includes a crucial warning about output token size, which helps an agent manage context. The main gap is the absence of a detailed output structure, but the enrichment steps imply what to expect.

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. It does a good job explaining the with_images parameter and its impact on output size. However, it does not explain with_ai or locale, leaving those to the schema defaults. It gives a high-level description of the product input ('raw ERP product') but does not detail its structure, which the schema already provides. Overall, partial 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?

The description clearly defines the tool as an enrichment pipeline with a specific list of actions (title sanitization, bullets, HTML description, SEO, JSON-LD, image lookup, attribute normalization). It frames the input as a raw ERP product and the output as a storefront-ready product, distinguishing it from sibling 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 explicitly states the input (raw ERP product) and output (storefront-ready product), giving clear context for when to use this tool. It also provides parameter-specific guidance for with_images, explaining the default behavior and the token trade-off. However, it does not explicitly compare against alternatives like enrich_batch, so it falls short of a 5.

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

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

With no annotations, the description carries the burden of disclosing behavior. It does mention scraping and downloading, and that it returns local paths, implying disk writes. However, it does not clarify side effects like whether files are persistent, overwritten, or if any rate limits or permissions apply, which is a gap for a tool that downloads resources.

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, well-structured sentence that front-loads the main action and audience, then lists input options and return values. Every clause adds meaningful information without 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?

With no output schema, the description appropriately explains the return format (data-URLs + local paths) and both input modes. It covers the core usage for a simple 3-parameter tool, though it could benefit from noting that product_url and image_urls should not both be provided, but the 'ou' (or) already implies exclusivity.

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 already provides descriptions for all parameters (100% coverage), giving a baseline of 3. The description adds the crucial relationship that the tool accepts either a product_url OR image_urls (mutually exclusive), which is not evident from the schema alone. It also clarifies the limit parameter's role in the context of fetching.

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 downloads product images for display in chat, using a specific verb ('Baixa') and resource ('imagens de um produto'). It distinguishes from siblings by explicitly mentioning two input modes (page URL scraping or direct URL list) and the return type (data-URLs + local paths), which sets it apart from search/analyze/OCR 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 context for when to use the tool ('para EXIBIÇÃO no chat') and explains the two alternative input modes ('URL da página' vs 'lista direta de URLs'). It lacks explicit exclusions or comparisons to sibling tools, but the intended use case is well implied and distinct.

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 full disclosure burden and does so thoroughly. It reveals multi-step fallback behavior, prioritization of the bare EAN, optional role of product_hint, return format (candidates with title/URL), and a crucial guardrail: the agent must never claim a candidate is the product without merchant confirmation. This is rich, safety-relevant behavioral 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 compact, front-loaded with purpose, and every clause adds value: sources, fallback reason, parameter constraint, and agent guardrail. Despite its length, it is dense and free of fluff, making it both concise and structured for quick parsing.

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?

Since there is no output schema, the description compensates by explaining the return shape (candidates with title/URL) and the need for merchant validation. It covers tool scope, data sources, fallback logic, and a critical safety instruction, making it complete for an agent to invoke correctly within the given sibling context.

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 already provides 100% coverage for both parameters, describing the EAN length and product_hint's role. The description adds context about sources but largely repeats the product_hint constraint already present in the schema. Therefore, no significant new parameter-level meaning is added beyond the schema 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?

The description opens with a clear verb-resource pair: 'Busca dados de referência de um produto pelo código EAN/GTIN' (Looks up reference data for a product by EAN/GTIN code). It further distinguishes itself by detailing two sources (Open Food Facts and web search) and sets it apart from sibling tools like search_images or analyze_url, which target different actions.

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 explains a fallback sequence: use Open Food Facts first, then fall back to web search when the EAN is not in databases, with context about why (common for fashion/private label BR). It gives clear guidance on product_hint usage and explicitly warns not to override the EAN with it. No explicit alternative tool comparison, but the context is sufficient for deciding when to invoke this 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?

With no annotations provided, the description carries the full burden of disclosure. It reveals that the tool uses tesseract OCR, is optimized for pt-BR text, and extracts title, price, and brand from the image. However, it omits limitations such as image quality requirements or handling of non-product images, but the core behavior is well specified.

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 exceptionally concise, consisting of two focused sentences. It front-loads the core purpose ('Extrai texto de um PRINT/foto') and immediately adds practical usage guidance, with no wasted or redundant words.

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 single-parameter tool with no output schema, the description covers the essential aspects: what it does, when to use it, and what information it extracts from the image. It does not describe the exact return format or error handling, but the description is sufficient for an agent to decide when to invoke it and what to expect.

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 already fully documents the image_url parameter with a clear description. The tool description adds contextual meaning by specifying the expected image type ('print/foto da página de produto') and the intended downstream extraction (título, preço, marca), going beyond the schema's basic 'URL da imagem'.

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 specific function: 'Extrai texto de um PRINT/foto da página de produto' (extracts text from a print/photo of the product page), specifying the resource and action. It distinguishes itself from siblings like analyze_image or search_images by focusing on OCR for product page screenshots, mentioning tesseract OCR and pt-BR.

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 indicates when to use this tool: 'Ideal quando o lojista manda um print da loja própria ou do concorrente em vez de link' (ideal when the store owner sends a print of their own store or competitor instead of a link). This implies an alternative (using a link-based tool) without naming it, providing clear context for usage.

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 transparency burden. It discloses that the tool returns a GraphQL query and JSON payload, lists included fields, and emphasizes it is for automatic publication without copy/paste. It does not mention side effects or permissions, but for a pure data transformation this is sufficient.

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 dense sentence that front-loads the action, followed by a concise list of return contents. It contains no fluff, though it is somewhat long due to enumerating fields.

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?

Despite lacking an output schema, the description specifies exactly what is returned (query and payload with key fields) and the expected input from enrich_product. It does not discuss error cases or formatting details, but for a transform tool with moderate complexity, this is 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 50%, with the 'product' parameter well-defined by the schema and 'handle' briefly described. The description adds meaning by listing output fields (title, descriptionHtml, handle, vendor, tags, metafields, image), but does not fully explain the mapping from product fields to those outputs. It partially compensates for the schema gaps.

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-converts an enriched product into a Shopify Admin GraphQL payload-and clearly identifies the resource and outcome. It distinguishes itself from sibling tools like enrich_product by focusing on the final payload preparation, not enrichment 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?

It explicitly states the input is the output of enrich_product, which gives clear context for when to use it (after enrichment). It does not provide explicit exclusions or alternatives, but the pipeline context makes usage direction 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?

With no annotations, the description carries the full burden of disclosing behavior. It transparently notes the use of Open Food Facts without an API key and ERP-provided URLs, and it explains the output structure: up to N URLs with source and score. However, it leaves unclear the meaning of 'score', result ordering, and behaviors for not-found or error cases, so the disclosure is only partially complete.

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 long and front-loads the primary purpose and output format. Every word contributes meaning, and there is no redundant or filler content.

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 image search tool with three well-specified parameters, the description adequately covers the input (EAN), source (Open Food Facts, ERP), limit (N), and output (URLs with source and score). It does not describe the meaning of score or fallback behavior, but given the tool's simplicity and lack of output schema, it is sufficiently complete for basic usage.

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 already provides 100% parameter description coverage, so the baseline is set at 3. The description adds minimal extra meaning by confirming that images are searched by EAN/GTIN and that 'N' relates to the limit parameter, but it does not significantly enhance understanding 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 searches candidate product images by EAN/GTIN and returns up to N URLs with source and score. It is specific about the verb and resource, but it does not distinguish itself from the sibling tool 'fetch_product_images', which presumably performs a very similar function.

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 provided on when to use this tool versus alternatives like 'fetch_product_images' or 'analyze_image'. The description implies usage context through mention of Open Food Facts and ERP URLs, but it does not state exclusions or name alternative tools, leaving the agent without clear selection criteria.

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 discloses what the tool returns (score 0-100, issue list with error/warning, ready-to-publish flag with threshold >=70) and the scope of validation. Although it does not explicitly state side-effect behavior, the nature of validation implies a read-only operation, and the return details provide meaningful behavioral transparency.

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 main purpose, followed by a concise summary of the output. It avoids redundancy and every sentence carries meaningful information.

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

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

Given the tool's complexity (nested objects, multiple validation dimensions) and the absence of output schema and annotations, the description provides a solid overview. It details the output structure and scoring threshold, but omits details about the rules parameter and the exact issue object format, leaving some gaps.

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%, with only the listing parameter described. The description adds context by listing validation criteria (image, schema.org, etc.) which map to the rules booleans, but it does not explain the rules parameter or its sub-fields. The rules object's purpose and configurability are not mentioned, so the description only partially compensates for the schema 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 description clearly states the tool's specific verb (Valida) and resource (produto/listing) with the purpose of storefront publication. It enumerates the validation dimensions (title, description, image, required attributes, schema.org JSON-LD, on-page SEO), which distinguishes it from sibling tools focused on enrichment, image search, or payload preparation.

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: use this tool to validate completeness before publishing to a storefront. It does not explicitly mention alternatives or when-not-to-use, but the publication context makes the appropriate usage evident and distinct from sibling tools like enrich_product or prepare_shopify_payload.

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