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

Annotations only supply readOnlyHint=false and openWorldHint=true; the description carries the rest, disclosing that the call settles $0.01 on-chain, that an unpaid call returns PaymentRequired (paid via _meta x402/payment), and what the vetting pipeline actually does (17 queries → 117 listings → 73 sybil collapsed). No contradiction 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?

Front-loaded with an identity label followed by clean Use when / Not for / Returns / Example sections, so the agent can scan to the routing clause immediately. The embedded full example response JSON is long and partly redundant with the Returns line, and the escaped newlines make the text noisy, but with no output schema the example does real work.

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 compensates by enumerating the return shape (recommendation with ready_to_pay, survivors[] with typed evidence[], catalog counters, vetting summary) and pricing/auth mechanics for a paid x402 call. Nothing an agent needs to invoke 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?

Schema description coverage is 100%, so need, chain, and budget_usd are already documented at the field level, and the description's per-parameter contribution is largely restatement ('budget $Y'). It adds the useful framing that a single query only sees a slice of the marketplace, but no syntax, format, or edge-case detail beyond the schema.

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

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

States a specific verb chain and resource: sweeps the whole x402 marketplace, collapses sybil clusters, ranks survivors by unique-payer usage, and returns one vetted recommendation with a ready-to-pay challenge. It explicitly distinguishes itself from sibling tools ('a single search shows only a slice') and from the AgentPay tools an agent might call directly.

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 'Use when' (about to pay an unknown x402 tool and want the real, used, non-sybil one under budget) and 'Not for' clauses that name two concrete alternatives: calling the known AgentPay tool directly, and verified_route_preview on the remote server for a free ranking preview. The routing decision is fully specified.

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