reserveoracle

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

With no annotations, the description must disclose behavior. 'Health status' suggests a read-only operation, but does not state whether it makes external requests, what data is returned, or if there are side effects. Minimal 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 extremely concise, but it's a fragment rather than a complete sentence. It's front-loaded and free of fluff, but under-specification limits the value of conciseness.

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 no output schema or annotations, so the description should explain return values and behavior. It only says 'health status' which is insufficient for an agent to know what response to expect or how to interpret the result.

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

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

Since the tool takes zero parameters, the schema already covers everything. The description doesn't need to elaborate on parameters. Baseline 4 is appropriate.

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 phrase 'ReserveOracle health status' indicates the tool provides health information about ReserveOracle, but it lacks a verb and specifics about what kind of status (e.g., uptime, API availability). It is distinguishable from sibling reserve_* tools but does not clearly state its 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 guidance provided on when to use this tool versus alternatives. The description doesn't mention contexts, prerequisites, or exclusions.

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

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

With no annotations, the description carries the full burden. The verb 'browse' implies a read-only operation, and 'with token counts' provides a useful behavior detail. However, it does not explicitly confirm side-effect-free behavior, data freshness, or any limitations, so it only partially discloses behavioral traits.

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 sentence that front-loads the purpose ('Browse all RWA asset types in the registry with token counts') and then provides an enumeration of covered types. Every word earns its place, and there is no filler or redundancy.

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

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

For a zero-parameter, no-output-schema browse tool, the description gives a clear sense of scope (asset type list) and key output (token counts). It doesn't specify the exact return structure or caveats around 'and more', but given the simplicity of the tool, this is nearly 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?

The tool has zero parameters and an empty input schema, so the description adds no parameter details (correctly, since there are none). The baseline for zero parameters is 4, and the description does not need to compensate for any parameter coverage 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 function: browsing all RWA asset types in the registry, and it lists the covered types (stablecoin, commodity_gold, etc.). This differentiates it from sibling tools that focus on specific assets like gold or silver, making the purpose highly specific and distinct.

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 this is the general overview tool for asset types, and the list of specific asset types suggests it's not for drilling into individual assets. However, it does not explicitly mention when to use alternatives or state any exclusions, so the guidance is only implied rather than 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, the description must bear the burden of disclosure. It reveals the payload includes a content_hash, verify URL, and custody providers, suggesting a signed/verified artifact. However, it does not clarify what 'signed' entails, whether the data is cached or real-time, or any failure modes, leaving significant behavioral ambiguity.

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 and mostly front-loaded with substantive details (price, 24h change, RWA context, MiCA, custody, content_hash, verify URL). The second sentence is slightly promotional ('turns raw price data into enterprise-grade evidence') but not excessive, so it earns a solid 4.

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 there is no output schema and no parameters, the description does a reasonable job of enumerating the key fields in the evidence payload. It covers the most relevant elements for a gold-price evidence tool, though it could elaborate on how the verify URL and content_hash work together or how the payload should be consumed.

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

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

The tool has zero parameters and the schema is complete (100% coverage), so the baseline is 4. The description correctly focuses on the output payload rather than input params, and no additional parameter semantics are needed.

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 resource ('gold spot price (XAU)') and the output form ('signed reserve evidence payload'). It distinguishes itself from siblings like reserve_silver and reserve_gold_tokens by emphasizing the live spot price and the evidence-payload format, though it lacks an explicit verb such as 'retrieves' or 'returns'.

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 implies a use case for 'enterprise-grade evidence' but does not explicitly state when to use this tool versus alternatives like reserve_silver or reserve_gold_tokens. No exclusions or alternative paths are provided, so the guidance is merely implicit.

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

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

No annotations are present, so the description must carry the burden. It discloses the output fields (live XAU spot price, custody info, MiCA relevance) and implies a read-only operation. However, it does not discuss potential delays, caching behavior, or how empty results are handled, which would be useful for 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, front-loaded sentence that states the core purpose first, then adds relevant details. No redundant words or filler, making it highly concise and well-structured.

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

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

For a zero-parameter list tool with no output schema, the description covers the essential content: token list, live price, custody info, and MiCA relevance. It could mention the return format or sorting, but overall it is sufficiently complete for its low complexity.

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

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

The tool has zero parameters, so the baseline is 4. The description reinforces that no input is needed by stating it returns 'All' tokens, and the schema is trivially complete. No further parameter explanation is necessary.

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 specifies the resource (gold-backed RWA tokens), the scope (all from the registry), and gives concrete examples (PAXG, XAUT, XAUM). This clearly distinguishes it from sibling tools like reserve_silver or reserve_metals, making the intent immediately obvious.

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

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

Usage is implied by the resource type: this tool is for retrieving gold-backed token data. It does not explicitly state when to use this vs alternatives, nor does it mention any exclusions. This meets the 'implied usage' level but lacks direct 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?

No annotations are provided, so the description carries the full burden. It does not state whether the tool is read-only, what happens for unsupported symbols, or any side effects. The examples show it returns static data, but this is inferred rather than disclosed. For a lookup tool, explicit read-only status would be valuable.

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, each earning its place: the first defines the purpose and output fields, the second and third provide concrete examples. It is front-loaded with the core purpose and avoids any 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?

There is no output schema, so the description must explain return values, which it does comprehensively (legal name, LEI, jurisdiction, regulator, etc.). For a single-parameter, low-complexity tool, this is largely complete. It does not cover error behavior for unsupported symbols, but that is a minor gap.

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 fully describes the 'symbol' parameter with an enum and a description, so the baseline is 3. The description adds examples of values (PAXG, BUIDL, EURCV) and what they map to in terms of issuer, but this is just illustrative output, not additional parameter meaning. The schema already covers the 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 identifies the tool as an issuer deep-profile lookup for reserve tokens, listing specific fields returned (legal name, LEI, jurisdiction, etc.). It provides concrete examples for PAXG, BUIDL, and EURCV, which make the purpose tangible. However, it does not explicitly contrast with sibling tools like reserve_token_lookup or reserve_token_context, so it loses a point on differentiation.

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

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

The description does not provide any guidance on when to use this tool versus alternatives. It implies it should be used when issuer details are needed, but it never mentions sibling tools, says 'use when...', or excludes cases. This is a significant gap given the existence of closely related tools such as reserve_token_context and reserve_token_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?

The description discloses that the payloads are signed and include content_hash and MiCA Art.36 context, which is useful behavioral information beyond a simple price response. However, with no annotations provided, it does not mention whether the operation is read-only, potential rate limits, or any error handling, leaving some burden unmet.

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. The first states the core function, and the second adds relevant output details (signed evidence, content_hash, MiCA context). Every word earns its place, and the information is front-loaded.

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

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

For a zero-parameter tool, the description covers the main purpose and key output characteristics: two metal prices, the ratio, and signed evidence with content_hash and MiCA context. While no output schema exists, the description provides enough about return values to be useful, though it could specify the exact response shape.

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 are zero parameters, so the schema fully covers any input needs. The description correctly omits parameter details, and the baseline for 0 params is 4. No additional parameter semantics are needed.

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 explicitly states the tool returns live gold (XAU) and silver (XAG) prices in a single call, and mentions the gold/silver ratio. This clearly distinguishes it from sibling tools like reserve_gold and reserve_silver, which likely return individual metals.

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 phrase 'in one call' implies using this tool when both gold and silver prices are needed together, but it does not explicitly compare to alternatives or state when not to use it. No exclusions or alternative tool names are given, leaving usage guidance implicit.

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

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

With no annotations, the description takes on the burden of explaining behavior. It states the data source (RWA registry, 80+ protocols), the optional filter, and the return fields. This is transparent for a read-only query tool, though it doesn't address pagination or performance characteristics, which would be additional context but not strictly required.

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 concise sentences that immediately convey the tool's scope, filtering capability, and return fields. No extraneous content, and the most important information is front-loaded.

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

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

For a simple one-parameter list tool with no output schema, the description provides sufficient context: data source, filter options, and output fields. It could mention whether the filter is required or how results are ordered, but those are minor gaps. Overall, it is a complete description for the tool's complexity.

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

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

The schema covers 100% of the parameter ('asset_type') with a list of valid values. The description repeats these values and adds 'etc.', but it does not add meaningful semantics beyond the schema. It clarifies the filter is optional, which is already inferable from the schema's lack of required parameters. Thus, the description adds marginal value.

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 returns all MiCA-relevant reserve assets from the RWA registry, with an optional filter by asset_type. It specifies the expected output fields (issuer, LEI, jurisdiction, custody), making the tool's purpose distinct from sibling tools that focus on specific asset types like gold or silver.

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

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

The description implies usage context: use this tool to get a broad list of MiCA-relevant assets, optionally filtered by asset_type. It does not explicitly mention exclusions or alternatives, but the broad scope and filter options provide clear situational 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?

With no annotations, the description carries the transparency burden. It discloses that the output is signed, includes a content_hash and verify URL, and contains price, 24h change, and MiCA context, giving a good sense of output behavior. It does not cover potential side effects, but this is a read-only, zero-param tool and the disclosure is adequate.

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 concise sentences front-load the main purpose and then enumerate the key output fields. Every word earns its place with no redundancy or filler.

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

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

For a zero-input tool without an output schema, the description is reasonably complete. It lists the included data fields and signing/verification elements, which is enough to understand the tool's scope. It could clarify the exact response structure but is not critically incomplete.

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 zero parameters, so schema coverage is effectively 100%. The description's parameter burden is minimal, and the baseline 4 applies because no additional parameter semantics are needed.

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?

Description clearly identifies the tool as providing live silver spot price (XAG) as a signed reserve evidence payload. It names the specific resource (silver) and distinguishes it from sibling tools like reserve_gold by explicitly stating XAG.

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: use this tool when you need the live silver spot price with reserve evidence details. No explicit when-not-to-use or comparison to alternatives such as reserve_gold or reserve_metals is provided, but the resource specificity is sufficient for basic selection.

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

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

With no annotations provided, the description carries the full burden. It discloses the output format (ES256K-referenced, content_hash, signed_at, verify_url) and data sources (live price data, RWA registry), offering meaningful behavioral context beyond a generic snapshot statement.

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 primary purpose, and each sentence adds value—first stating what it does, second detailing the output format and use cases. No unnecessary verbosity.

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 explains key return fields (content_hash, signed_at, verify_url) and notes it is a single payload, giving agents a clear picture of the result. It doesn't cover errors or prerequisites, but for the tool's simplicity, this is adequate.

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 fully covers the symbol parameter with an enum and description, so the tool description adds no additional parameter semantics. The phrase 'any asset' is slightly misleading given the restricted enum, but this is a minor issue.

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 creates a 'Full signed reserve evidence snapshot for any asset', combining live price data and RWA registry data into a signed payload. This distinguishes it from sibling tools like reserve_gold or reserve_silver, which are asset-specific.

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 this tool: 'for compliance, due diligence, and agent workflows'. It doesn't explicitly exclude alternatives, but the enterprise-grade framing implies it's the comprehensive option among the reserve_* 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 indicates a read-only 'returns' behavior but does not disclose side effects, auth requirements, or edge cases. The description is adequate but not rich, earning a baseline 3.

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 concise sentences, front-loaded with the core purpose and data returned, followed by a sibling distinction. Every sentence earns its place; no redundancy.

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

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

For a simple single-parameter lookup tool, the description adequately covers what it does and returns, including a clear distinction from a sibling. It does not describe output format or error behavior, but given the low complexity and lack of output schema, it is sufficiently complete for an agent to use.

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% for the sole parameter 'symbol', with an enum and default value. The tool description adds no parameter-specific meaning, so the baseline of 3 applies. Notably, the enum list in the schema conflicts slightly with the parameter description mentioning 'EURe, OUSG, USDY etc.' that are not in the enum, but this is a schema issue not addressed by the tool description.

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

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

The description clearly states the tool's purpose: 'Token-level reserve context for any RWA token — the issuer-near view' and enumerates specific data returned (token structure, custody, issuer LEI, etc.). It explicitly differentiates from sibling 'reserve_snapshot' by noting it 'Complements reserve_snapshot (asset-level) with token-specific details.'

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 by positioning the tool as complementary to reserve_snapshot, implying use when token-specific details are needed over asset-level data. However, it does not explicitly state when not to use it or mention alternatives like reserve_token_lookup, 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 provided, the description carries full burden for behavioral disclosure. It lists output fields but does not mention side effects, error handling, whether it is read-only, data freshness, or any access constraints.

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

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

The description is two sentences, front-loaded with the core purpose, and every word adds value. It efficiently communicates scope and return data 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?

For a simple one-parameter lookup with no output schema, the description conveys the main purpose and return fields. However, it omits behavioral details like read-only status, token availability limits, or potential errors, making it adequate but not fully complete.

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

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

Schema description coverage is 100% for the single symbol parameter, so the description adds little beyond the schema. The listed symbols in the description extend beyond the enum, but the schema already documents the same via 'etc.' 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 the tool provides a 'Full RWA profile' for reserve asset tokens, listing specific examples and return fields. It distinguishes the broad token coverage from sibling tools like reserve_gold or reserve_issuer, though it doesn't explicitly name alternatives.

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 implies use when you need comprehensive reserve asset data for a token, but does not state when to avoid it or mention sibling alternatives. The context is clear but exclusions are absent.

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