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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses the payment model ($0.002 USDC per call via x402 inside the call), the alternative Skyfire/kya-pay token path through a header or the kyapay-token argument, that failed calls are not charged, and that pre-availability calls are refused before payment. It also reveals the filter-relaxation order and the seller de-duplication pooling behavior, which the annotations cannot convey.

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 availability caveat is correctly front-loaded, since an agent must know a call can be refused before it spends anything. But the prose is dense and partly redundant with the schema, restating the kyapay-token argument/header and the ETag/304 mechanic that the parameter descriptions already carry. The pivot from availability to the actual output is buried mid-paragraph.

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

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

With no output schema, the description does the work of describing the return: one signed number with a 95% range and a seller count, plus which filters held. Payment, caching and refusal paths are all covered for a six-parameter, metered tool. Only the meaning of 'signed' and the failure shape when no filter combination yields enough sellers are left implicit.

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 meaning the schema does not: price is treated as a price band and the answer is segmented by category, price band and method, and resource is 'your listing's resource URL' as an alternative targeting route. It also explains the practical effect of if_none_match (free 304) and of kyapay-token (charge that token).

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 precise computation: the share of new Bazaar listings in a given category, price band and method still listed four weeks after they first appeared, pooled over recent weeks with each seller counted once, plus a 95% range and seller count. That is specific enough that an agent knows exactly what it gets back. It never differentiates itself from a sibling tool such as pick_odds, which keeps it short of a 5.

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

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

It frames the question the tool answers ('Do x402 listings like mine survive?') and lays out practical conditions: the answer only exists from the 2026-W49 snapshot, calls are refused before any payment until then, and unchanged answers asked with their ETag are a free 304. It also explains the fallback when too few sellers match. There is no explicit statement of when to prefer a sibling over this tool.

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