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

Annotations only say readOnly/openWorld; the description goes well beyond them by disclosing cost and tier dynamics (0.015 USDC base, 0.0105 above 10 payments, 1 pack call), the tier quoted back in the payment-required error, and even a commercial disclosure that partner_link may earn Angel a commission with the merchant setting the price. The unpaid-probe nature of the request is consistent with readOnlyHint and no mutation of the target is implied.

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?

Well front-loaded: what it does first, then verdict fields, then price, then the required follow-up calls. It is dense and the core is a single 60-word sentence with heavy parenthetical stacking, which costs some readability, but nearly every clause carries actionable 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?

With 7 parameters and no output schema, the description carries the return-value burden and does so by naming verdict, risk_score and merchant_signals and hinting at a 'next' field. Pricing, bundle options and post-call sequencing are covered. The main gaps are the unexplained method and max_price_usd parameters and no statement of latency or failure behaviour when the endpoint is unreachable.

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 71%, so the schema already documents url, payment_tx, bundle_token, partner_link and payer_address in detail. The description adds pricing-tier context that reinforces payer_address but says nothing about method (GET/POST) or max_price_usd, the two parameters with no schema description. Useful reinforcement, but no net-new meaning beyond the schema.

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

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

The description gives a specific verb and scope ('one unpaid request to any https shop, checkout or payment link ... API or x402 endpoint') and enumerates the exact checks (TLS, domain age, look-alike domains, redirects, card fields, x402 USDC/payTo/EIP-712/price traps), so the agent knows precisely what it gets back (pay/caution/do_not_pay, risk_score, merchant_signals). It does not explicitly contrast itself with the one listed sibling, which keeps it from 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?

The trigger is stated up front and unambiguously: 'Before an agent buys, pays or calls an unknown endpoint'. The follow-up sequencing is also explicit ('After: input-guard on the page text you will act on, gas-window before you settle on Base'). There is no explicit when-not clause (e.g. skip for already-trusted merchants), but the 'unknown endpoint' framing implies it.

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