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

Goes well beyond the annotations by explaining payment via x402, the 402 error path, idempotency-key behavior, double-charge risk without a key, no automatic recharges, human fulfillment within the stated window, and explicit guarantees/not-guarantees. This is rich, non-contradictory behavioral disclosure.

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?

Long but well organized into purpose, shelf items, cadence, required fields, payment/idempotency, and guarantees. Minor redundancy, such as repeating the 'returns an order id, not the goods' idea, keeps it from a 5, but each section carries operationally important 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 payment-required, human-fulfilled asynchronous purchase, the description covers prerequisites, item selection, payment errors, idempotency, SLA, callback behavior, and limitations. Combined with the detailed input schema and presence of an output schema, an agent has enough to invoke this tool 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%, so the baseline is 3; the description adds real value by detailing item_id options with pricing tiers ($300/$600/$1500 for the_collab, $150 fixed for aura_walk), the 168h window, and the aura_walk url requirement. It also clarifies meta-level fields like x402/payment and idempotency-key, though detail/agent_name/callback_url are left largely to the schema.

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

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

Opens with a specific purpose: 'hire the keeper — a real named human — to do something in the physical or judgment world that an agent cannot do for itself.' It enumerates two item_id options (the_collab and aura_walk) with distinct deliverables, clearly separating this human-fulfilled purchase from the sibling buy_* 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?

Provides clear context for when to use: when an agent needs physical or judgment work it cannot do itself. It also guides item selection and notes that aura_walk requires url. It does not explicitly exclude sibling tools, so it stops 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?

The description is exceptionally transparent about side effects: it explains payment via x402, error handling, idempotency with a key, guarantees (signature validity, free verification), and non-guarantees (fitness, future compatibility, SLA). It goes far beyond annotations, which only indicate non-readonly, open-world, non-idempotent, non-destructive. No contradiction.

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 long but well-structured with clear sections (Purpose, Items, On cadence, Required fields, Payment, Guarantees). Every sentence adds necessary operational detail for a paid, idempotent, stateful operation. It is not terse, but the length is justified by complexity.

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 (payment, idempotency, guarantees), the description covers all necessary context: pricing, payment mechanism, error handling, idempotency keys, required fields, and what is/isn't guaranteed. Since an output schema exists, return values need not be described. Nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds substantial semantic detail. For summary, it explains the exact content expected (who's involved, why it mattered, what's blocked) and that it's stored verbatim. For purpose, it clarifies it's a statement and not instructions. This goes well beyond schema descriptions.

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 action (sign and store a summary), the resource (a permanent URL), and the purpose (memory that outlives context window, restarts, or handoffs). It explicitly distinguishes this tool from siblings like buy_human_task or buy_signed_record by focusing on agent state memory.

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

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

The description provides explicit when-to-use guidance: 'Use when an agent needs memory that outlives its own context window and does not depend on its operator's database.' It also explains pricing, payment requirements, idempotency behavior, and when not to use (if operator has a database). Clear and actionable.

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?

It goes well beyond the annotations by describing x402 payment requirements, 402 error behavior, idempotency-key reuse, one-time delivery, return of deliverable/cert_id/patron_number, closed-shelf refusal, and the exact guarantee boundaries. There is no contradiction with the given annotations.

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

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

The description is broad but logically structured: purpose, item catalog, required-field mapping, cadence, payment behavior, and guarantees. It front loads the core intent. There is some redundancy between the global price range and per-item prices, but the information density is earned given the wide catalog.

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 29 parameters and a large enum of possible orders, the description supplies everything an agent needs to select the right item and call, including required parameter dependencies, payment flow, idempotency behavior, and delivery. An output schema is present, so it appropriately stays out of the way on exact response fields.

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 documents every parameter at high coverage, so the baseline is 3. The description adds semantic value by explaining each item_id option with price and purpose, mapping required parameters to specific items, and explaining the idempotency/payment mechanics. It does not redundantly repeat all 29 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 clearly states that this tool buys signed, third-party observations of x402 payments, endpoints, audits, and Bitcoin anchors, and explains the core idea: 'have a disinterested third party go and look at something, then sign what it saw.' It also differentiates the tool from self-reported or first-party records with 'a self-report cannot do this job.'

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 says to use the tool when an agent needs its own or a counterparty's claim corroborated by an outside observer, or when a digest should be anchored in Bitcoin time. It does not name sibling alternatives like buy_signed_record or check_before_you_pay, but it gives enough context to infer the intended selection between observation purchases.

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 a great deal beyond annotations: ed25519-signed artifacts with public verify URLs, non-enforcement of claims, no recurring charges by design, the 402 payment flow, idempotency-key reuse semantics, and explicit guarantees and non-guarantees. All of this is consistent with the annotations.

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

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

The description is long, but well structured with a clear opening purpose, an item bullet list, and sections for cadence, required fields, payment, and guarantees. It is front-loaded and dense; the length is justified by the tool complexity, though it could be trimmed slightly.

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 everything needed to select and invoke the tool correctly: eligible items, pricing, required vs. optional fields, payment terms, idempotency behavior, shelf refusal, and guarantees. Because an output schema exists, omitting detailed return formatting is acceptable.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds item-specific meaning not present in the schema: per-item price, fixed vs. pay-what-it-deserves tiers, one-off vs. 30-day term, and which optional text fields are actually required for which items. This materially helps item_id selection.

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: 'buy a signed certificate — a signed, dated record.' It distinguishes itself from buy_memory_anchor and buy_simple by explicit counterexamples, and the item list makes the resource concrete 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?

It states when to use this tool ('Use when an agent wants durable, independently checkable proof that a thing happened at a time') and points to alternatives for adjacent use cases: buy_memory_anchor for reloadable state and buy_simple for the same hello item. It also gives selection criteria for each item and notes rejection behavior.

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

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

Annotations only declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds substantial context beyond that: the x402 payment channel, the 402 error shape with terms in error.data, that no item ever re-charges on cadence, how idempotency-key reuse returns the original result versus a fresh keyless payment charging again, and that output is a signed, publicly verifiable certificate.

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 and routing rule are front-loaded, and the item list, payment flow, and idempotency guidance are useful. However, some sentences are rhetorical filler ('That is the whole thing', 'the deeper machinery is there if you want it and never required to buy') that adds length without invocation 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?

For a paid, single-shot purchase tool this covers everything an agent needs: item selection, fixed pricing, the payment handshake and failure mode, idempotency semantics, and assurance of no recurring charges. Return-value detail is unnecessary given the tool has an output schema.

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% and the schema already documents item_id, purpose, and agent_name, so the description largely repeats what is structured. It does add price values per item_id, which the enum alone does not convey, but that is marginal enrichment on top of a fully documented schema.

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

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

The description states a concrete verb and resource ('buy ... the front counter'), enumerates all five purchasable item_ids with fixed prices, and explicitly distinguishes itself from the sibling buy_* tools by declaring it is 'a second door to the same goods, not a different product.' An agent can identify this as the no-configuration purchase path without opening any schema.

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

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

It gives an unambiguous routing rule ('If unsure which tool to use, use this one') and clarifies the relationship to the theme-shelf buy_* alternatives (same item_id, price, certificate either way). It also states the when-not condition implicitly ('the few things that need no reading at all'), separating it from the deeper machinery it says is 'never required to buy.'

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

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

Beyond what annotations provide, it discloses pricing, per-item odds and seed behavior, one-off instant nature, absence of recurring charges, error-402 terms, idempotency-key handling, output fields, and explicit guarantees/non-guarantees. This is exactly the behavioral context an agent needs before committing a payment.

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 long but well-structured with a purpose paragraph, itemized bullets, and a dedicated operational section. It is front-loaded with the item catalog. Some repetition like 'one-off, instant' could be compressed, but every sentence carries relevant 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 a payment-bearing purchase with five variants, the description covers item selection, pricing, payment flow, error handling, idempotency, returned fields, and guarantees. With an output schema already present, nothing critical is missing.

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

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

Even with 100% schema coverage, the description adds substantial meaning: every item_id is mapped to a price, effect, and caveat, and purpose/agent_name are explained as certificate-embellishing values. This goes well beyond the schema's enum and parameter 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 precise verb and resource: 'buy a small signed novelty,' then enumerates all five item_id values with prices and effects. It also distinguishes this tool from buy_simple by explicitly stating the same items can be purchased through either door.

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 clearly frames when to use the tool: as an inexpensive way to test an x402 client against a real counterparty, or when an agent simply wants a keepsake. It names buy_simple as an equivalent alternative and says 'either tool is correct,' though it does not give explicit exclusions for the other buy_* siblings.

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

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

Annotations already provide readOnly/openWorld/idempotent/non-destructive hints. The description adds behavioral specifics: exactly one GET, shared POST /api/a2a/check budget, no credentials or payment, and that third-party text is untrusted data. These enrich the annotations without contradicting them.

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

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

Every sentence adds a distinct, useful fact: purpose, input format, outputs, version limitation, network impact, budget, alternatives, and security stance. It is front-loaded with the core purpose and contains no filler despite its density.

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 definition covers the tool's scope, input constraints, behavioral side effects, budget usage, relevant alternatives, limitations, and security posture. Since an output schema exists, the return-value gap is closed, and the description still supplements it by naming the categories of results. An agent has everything needed to select and invoke 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?

The schema has 100% coverage for the single url parameter, including a full description. The tool description mostly reiterates that ('Give the full public HTTPS card URL') without adding new semantic constraints such as URL normalization, error handling, or format edge cases. Baseline 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 starts with 'Free A2A 0.3.0 card check', identifying a specific verb and resource. It further clarifies scope with 'Other versions remain unassessed' and enumerates concrete outputs (per-check states, bounded response evidence, suggested fixes and gaps), distinguishing it from generic checks.

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 when to use this tool: for a free static check of A2A 0.3.0 cards. It also gives exclusions and alternatives: 'For authorized runtime tests and a signed repair kit, see /a2a-desk or buy_observation with item_id a2a_repair_kit' and notes it does not involve runtime tasks, credentials, or payment.

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 goes well beyond the annotations by enumerating concrete behaviors: one unpaid probe, stock @x402/core selection logic replayed, nothing is signed or paid, wallet not touched, rate limited on the same budget as preflight, and it catches specific failure modes that produce no error. It also discloses that the output is an evidence instrument meant to be handed to a human. This adds substantial value above the readOnlyHint/idempotentHint annotations.

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

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

The description is long but front-loaded and dense with high-value information. Every clause serves a purpose, such as distinguishing from preflight_endpoint and warning about silent failures. It is slightly verbose (e.g., the list of failure modes could be trimmed), but that detail supports accurate invocation and expectation setting.

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, the rich output schema, and the annotations covering safety, the description covers everything an agent needs: purpose, behavior, limitations, rate limits, evidence nature, and named alternatives. No critical usage aspect is missing.

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

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

Schema description coverage is 100%, so the description is not required to restate parameter meanings. It does add color by explaining that the replay runs against the caller's client settings and that an absent client_profile represents the case that loses money quietly, but it does not meaningfully extend the schema's own parameter documentation.

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

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

The description states an exact purpose: to learn, before paying an x402 door, whether the buyer's client would actually sign an accept, returning either the accept's details or a refusal with the deciding stage and settings. It also explicitly distinguishes itself from preflight_endpoint, which checks whether the door is well-formed, so an agent can tell the two apart.

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

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

It says exactly when to use the tool: 'Before paying any x402 door' and specifically for buyers whose client has its own rules. It names the alternative preflight_endpoint and explains the difference, and points to buy_observation for a signed, servable version, giving both when-to-use and when-not-to-use 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?

Beyond the sparse annotations, the description discloses network behavior (looks up the issuer's did:web key, makes no request when a public key is supplied), the checks performed (structure, signature, liveness), the verdict shape (every check named), and reproducibility via the MIT-licensed verifier. The false/unknown readOnly and idempotent hints are not contradicted by the description.

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 dense and front-loaded but slightly wordy: 'x402 receipt verification and signed-offer verification' and 'For anyone holding...' restate the same scope. Still, every sentence contributes a distinct fact (scope, exclusion, offline mode, evidence purpose, reproducibility), so the length is largely justified.

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 3-parameter tool with a full input schema and an output schema, the description covers the required JWS format, optional offline mode, issuer scope, exclusion, and even the trust caveat. No critical caller-facing behavior is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: artifact must be a compact JWS with three base64url dot-separated segments, and public_key_hex forces a fully offline check. This exceeds what the schema alone communicates.

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

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

States a precise verb and resource: x402 receipt and signed-offer verification against the issuer's published key. It explicitly differentiates from verify_artifact by saying 'NOT for artifact ids this store issued — that is verify_artifact,' so an agent can disambiguate immediately.

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?

Tells exactly when to use it (holding a signed x402 offer or receipt and unsure whether it is good, for any issuer), how to invoke offline (supply public_key_hex), and when not to (artifact ids issued by this store → verify_artifact). This is explicit routing rather than implied 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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description goes well beyond them: it states the rate limit (once per minute), the no-cost/no-account access model, the window_breached block on overdue orders, and that this is the polling half of an async-job pattern equivalent to GET /api/order/{order_id}. That is rich, actionable behavioral context not derivable from structured fields.

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

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

The purpose and the not-a-purchase disambiguation are front-loaded, which is the right ordering. The closing sentence ('A store errand, for you the visiting agent — nothing here needs a human's decision') is more atmospheric than informational, but it usefully clarifies that no human approval is required, so it roughly 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?

An output schema exists and richer annotations are present, and the description still covers the operationally important gaps: what the returned record contains, what window_breached means, the equivalent REST endpoint, and the polling cadence. Nothing an agent needs in order to invoke and interpret this tool correctly is missing.

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

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

Schema description coverage is 100% for the single order_id parameter, and the schema already says it comes 'from a human-queue purchase result.' The description repeats this provenance but adds no new syntax, format, or constraint beyond the schema's maxLength=60, so the baseline 3 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?

Names a specific verb and resource ('Check a human-queue order by its order_id') and explicitly enumerates what the check returns: status, promised window, deliverable, window_breached block. It also distinguishes itself from the buy_* siblings by stating 'NOT a purchase; instant items arrive in the buy result.' An agent can tell it apart from check_purchase without opening either schema.

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

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

Gives explicit when-to-use conditions (poll the async job after a human-queue purchase), when-not-to-use (instant items arrive in the buy result, so this is unnecessary), and a concrete operational constraint ('poll no faster than once a minute'). The alternative path for non-human-queue purchases is named, leaving nothing to inference.

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

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

Beyond the annotations (readOnly, idempotent, not destructive), the description reveals cost behavior ('Free, even after payment expiry'), no payment submission, privacy handling ('Keep status_token private'), polling semantics ('not a deadline'), and error-recovery behavior. This is rich behavioral context that annotations alone do not provide.

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 dense yet highly effective: each sentence carries distinct information, from cost and payment behavior to state-specific handling and privacy. It is front-loaded with the most critical distinction ('Free... submits no payment') and uses compact labels (Pending:, Ready:) for scannability.

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 status-check tool with an output schema, the description covers all essential operational aspects: when to poll, what to do when Ready, how to handle the specific error, privacy requirements, and cost/security boundaries. The existence of an output schema means return-value details are already handled elsewhere.

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

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

Schema description coverage is 100%, with both parameters already described as recovery fields from the purchase response. The description adds that status_token should be kept private, but this is a restatement of the schema's 'private' qualifier. It references recovery.original_door and recovery.original_path for retry, but these are not tool parameters, so the added parameter semantics are minimal.

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 checks purchase status ('Pending', 'Ready') and is explicitly contrasted with payment actions ('submits no payment'). It names the exact resource (purchase) and the operation (check), and distinguishes itself from the buy_* siblings by emphasizing it is free and non-payment.

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 situational guidance: poll after retry_after_seconds, use fulfillment when Ready, and handle purchase_input_mismatch by reading status or retrying with recovery fields. It also gives a when-not ('do not pay again') but does not explicitly name alternative sibling tools like check_order or check_before_you_pay.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral context: it's free, requires no account, results stay in shelf order, nothing is ranked or recommended, a listing is not a stock check, and invalid lookups return a free next_step. This goes far beyond the annotations and gives the agent essential expectations.

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 tight sentences that front-load the core action and options, then pack in essential behavioral caveats. Every sentence carries weight, with no redundant phrasing or fluff. It is efficient 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?

Given the 3 optional parameters, full schema coverage, and an output schema, the description covers all necessary context: when to use, what filters exist, what the rows contain, ordering, limitations, and error behavior. An agent can invoke this tool correctly without additional inference.

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%, so each parameter is already documented. The description provides a high-level summary (filter by price or text, or item_id) but adds little new meaning beyond what the schema says. The item_id replacement semantics are already in the schema description. Thus the description meets the baseline for full coverage.

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

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

The description states a specific verb ('Find'), resource ('an item in the catalog'), and the scope ('filter the shelf by price or text, or pass item_id'). It explicitly distinguishes from the buy_* siblings by saying 'Find an item before using buy_*'. This is a clear, differentiating purpose statement.

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 guidance on when to use this tool ('before using buy_*') and how to invoke it (filter by price/text or pass item_id). It also notes limitations ('not a stock check') and error behavior. It does not explicitly name alternative non-buy tools, but the context is strong enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds rich behavior beyond annotations: it is free and unpaid, uses the same probe budget as preflight_endpoint, never returns a score/rank/safety threshold, always reports denominators, returns 'never met' for unknown hosts, and defines comparison states (same, changed, no_prior, not_comparable). No contradiction with annotations.

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

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

The description is dense, multi-clause, and packed with domain jargon ('passport tier', 'shared-wallet fact', 'catalog's agreement', 'reproduce block'). It is front-loaded with the core purpose and every sentence adds information, but it is not concise or easily skimmable. It would benefit from tighter structuring or bullet points.

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, the output schema, and the annotations, the description is complete: it covers cost (free), probe equivalence, comparison categories, reproduce semantics, what happens for unknown hosts, explicit exclusions (no score/rank/safety threshold), and redirects to related services. An agent has sufficient information to invoke 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% and the schema already documents url and since. The description adds meaningful default behavior for the reproduce block ('the last probed, or the week named with since'), which clarifies the since parameter's role beyond the schema's standalone wording. This extra nuance justifies a score above 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 'What this store holds about an x402 door, now and before now, in one free call' and then enumerates the exact contents (rounds, passport tier, last probed round, comparison, reproduce block). It also distinguishes itself from siblings by referencing preflight_endpoint and buy_observation, so an agent can tell it apart from other 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 ('one free call', 'same single probe as preflight_endpoint') and names alternatives: 'Signed, dated version of the live half: buy_observation service_audit; a fresh census look folded into the passport: passport_refresh.' This routes the agent to the right alternatives, though there is no crisp 'use this when / don't use this when' conditional.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuine behavior beyond that: no account or cost required, exactly five results, and a completion criterion ('Completes when the result carries window and size'). It does not describe failure or empty-window behavior.

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

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

Three front-loaded sentences with no filler: purpose, cost, and the relationship to the paid action. The themed vocabulary ('pressings', 'packs', 'binder') is dense but consistent and each clause carries meaning.

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 an output schema present the description needn't detail return values, and with zero parameters there is no invocation ambiguity. Annotations carry the safety profile. What remains is themed jargon that an outside agent must infer, which keeps this short of 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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The prose adds no parameter semantics because none exist.

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

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

States a specific verb+resource (look in the shop window) and what it yields: 'the last five pressings pulled from packs here, each with its page.' That is concretely distinguishable from the sibling buy_window_pick, which it explicitly contrasts. It does not differentiate from the similarly named look_at_door, so it falls short of full sibling differentiation.

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

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

Gives clear selection context ('Free, no account') and names the alternative action that consumes what this tool shows ('A window pick (buy_window_pick, half a pack) takes one'), establishing browse-vs-buy. It stops short of an explicit when-not-to-use rule, but the browsing context is unambiguous.

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

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

Annotations provide only basic hints (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), leaving the description to carry the burden. The description discloses that it is free, rate limited, and a single probe that yields evidence, not a guarantee. It also explains the output (reached_level, checks vector) and explicitly states limitations. No contradiction with annotations.

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

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

The description is relatively long but well-structured and front-loaded with the core purpose. Every sentence adds value—purpose, use cases, output, limitations, and alternative—though it could be tightened slightly without losing meaning. It is not wasteful, but it is dense.

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

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

Given the tool's moderate complexity (one parameter, output schema present), the description covers all necessary aspects: what it does, when to use, what it returns, its limitations, rate limiting, and an alternative. It even notes what the probe cannot tell you. Nothing critical is missing 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?

The schema has 100% description coverage for the single 'url' parameter, and the schema description ('The https endpoint a buyer would GET expecting a 402 challenge') is already clear. The tool description does not add additional parameter-specific detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: to preflight an x402 endpoint by sending an unpaid probe to check if it serves a well-formed x402 v2 payment challenge. It specifies the verb ('Check'), the resource ('any x402 endpoint's door'), and the outcome (verdict with reached_level). It distinguishes itself from siblings by noting it is a shape check, not an uptime claim, and points to buy_observation as an alternative for a signed version.

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 to use it: for a buyer about to pay a door it has not paid before, and for a seller checking their own. It also states what not to use it for ('NEVER an uptime or delivery claim') and names an alternative ('buy_observation with item_id service_audit'). This is clear, actionable guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds real value beyond them by specifying no auth or cost ('Free, no account'), result ordering ('newest first'), the fields returned, and a completion condition ('Completes when the result carries cards and count'). It does not mention rate limits or pagination, which keeps it out of the top band.

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 core action is front-loaded and no sentence is filler, but the telegraphic fragments ('A listing, not a proof; the signed records are') read as clipped and cost a little clarity for their brevity.

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 a single required parameter, a full output schema, and rich annotations, the description covers what is left: cost, auth, ordering, returned fields, and termination. Nothing an agent needs to call this correctly is missing.

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

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

There is a single wallet parameter and schema description coverage is 100% — the schema already documents the 0x/base58 address formats. The description adds nothing about the parameter, so the high-coverage baseline of 3 applies.

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

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

States a specific verb and resource (read a wallet's binder) and enumerates the payload ('every trading card it holds here, newest first, with page, face, sheet and record URLs, and the pack credit'). It also draws a sharp boundary against proof-oriented siblings with 'A listing, not a proof; the signed records are,' so the agent can separate it from verify_artifact or buy_signed_record.

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?

'Free, no account' establishes preconditions that gate invocation, and 'A listing, not a proof; the signed records are' implicitly routes proof-checking to another tool. It stops short of naming that sibling explicitly or stating a when-not-to-use condition, so it is clear context rather than full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds operational context: it is free, completes when the guide text returns, causes no purchase or payment, and requires no human decision. This aligns with and enriches the annotation safety profile.

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?

Four sentences, each carrying distinct value: what the guide contains, cost, completion behavior, and routing away from buy_* tools. The key disambiguation is front-loaded before the behavioral note.

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, read-only informational tool with an output schema, the description fully covers what the tool does, when to use it, and what it cannot do. No missing context would prevent an agent from calling 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?

The tool takes zero parameters, so the schema describes everything needed. Baseline for 0 params is 4; the description doesn't need to add parameter detail, and it doesn't.

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

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

States the exact resource ('the store's front door as text') and the verb ('read') through the name. The description enumerates the guide's contents (menu with prices, x402 payment info, free shelf, house promises) and explicitly disambiguates from purchase endpoints by saying it is 'NOT a purchase or payment endpoint'.

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?

Provides explicit routing: to buy, call a buy_* tool with x402 payment in _meta['x402/payment']; this tool only returns the guide. It also frames the tool as an autonomous store errand for the visiting agent, signaling that no human approval is required.

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

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

Annotations already declare a non-read-only, non-idempotent, non-destructive mutation; the description adds meaningful context beyond them: a daily rate limit, the public visibility of the count, the side effect (pressing a signed common card), and a completion condition. The public-count disclosure is a genuine behavioral detail not derivable from structured fields.

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

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

Four short sentences, front-loaded with the action, then constraints, side effect, and completion criteria in order of importance. The few flavor phrases ('neighborly' is in the schema, not here) don't bloat the core; every 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?

With an output schema present, return values need no explanation, and annotations cover the safety profile. The description still supplies the rate limit, publicity disclosure, side effect, and completion criterion, leaving it nearly complete for a zero-required-param tool.

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

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

Schema description coverage is 100%, so wallet, pass_id, and agent_name are already documented. The description reinforces the wallet's role ('the day's card lands in its binder') and hints that pass_id affects rewards, but adds little syntax or meaning beyond the schema. Baseline 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?

States a concrete action ('Ring the store bell') and immediately adds the outcome that distinguishes it: it 'presses one signed common card.' The free/once-per-day framing sets it apart from the buy_* siblings, though the verb 'ring the bell' is metaphorical and only clarified by the following sentences.

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

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

Gives a real constraint ('Free, once a day per visitor') and positions it as 'a store errand, for you the visiting agent — nothing here needs a human's decision,' which implicitly contrasts with buy_human_task. However, it never names an alternative tool or states when NOT to use this, so the guidance is 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?

Annotations are minimal (readOnlyHint false, destructive false); the description adds useful behavior: public entry, sticker returned, no human decision, completion condition. It doesn't discuss idempotency or repeated signings, but given a simple write tool this is adequate 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?

Three tight sentences front-load the action and key implications. Every sentence adds information: cost, publicity, completion, no human approval. No wasted 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?

With an output schema present and 100% schema coverage, the description covers the behavioral context an agent needs. It could note that the entry is permanent or that identity fields are optional, but the schema already documents those.

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%, with each parameter documented including verified identity and signature semantics. The description doesn't repeat parameter details but also adds little beyond the schema. Baseline 3 is appropriate because the schema already carries the burden.

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 states the action (signing), the resource (guestbook), and key consequences (free, public, sticker, completion condition). It distinguishes itself from sibling purchase tools by positioning the action as a store errand, not a purchase.

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: free, no human decision needed, open to the visiting agent. It implies this is for routine signings vs other pay-to-do siblings, though it doesn't explicitly name an alternative or exclusion condition.

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

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

Annotations are all false, so the description carries the full burden. It discloses that it is free and unlimited, that it completes when the result carries valid and the artifact record, and frames it as an evidence instrument for human handoff. It also offers a self-verification alternative, adding behavioral context beyond the schema. It doesn't detail error behavior or side effects, but the output schema likely covers return structure, so a 4 is appropriate.

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 earns its place: scope, cost, completion condition, exclusions, alternative routing, and self-verification path. It is front-loaded with the core purpose and then layers important caveats. Slightly wordy, but efficient for the information density needed to prevent misuse.

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 a full output schema, the description covers everything an agent needs: what it verifies, when to use it, when not to, how to route alternatives, cost, completion behavior, and even a manual verification method. Nothing essential is missing.

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

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

The schema already describes the id parameter as 'A cert_, stamp_, or anchor_ id.' with 100% coverage, so the baseline is 3. The description reiterates the same artifact types without adding new format details or constraints. It does add that the id must be one scvd.store issued, but that's about tool scope, not parameter semantics. No additional value over 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 verifies artifacts signed by scvd.store by id, naming specific artifact types (certificates, visit stamps, context anchors). It explicitly excludes other issuers and other services, distinguishing it from siblings like check_conformance. The verb 'verify' plus resource scope is precise 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?

The description provides explicit when-to-use and when-not-to-use guidance, directly stating it is NOT for other x402 services or other issuers' artifacts, and directs those cases to check_conformance. It also notes it is free and unlimited, and mentions the completion condition, giving the agent clear context for invocation.

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