DYOE Payment Pre-Flight ($0.10)

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

Annotations only declare readOnlyHint/openWorldHint; the description adds material context beyond that: the response vocabulary (proceed/caution/stop, reasons, signed attestation), the fact that it is a zero-mutation pre-flight despite the 'transaction' name, and the paid-call mechanics ($0.10 USDC on Base per call via x402) which an agent must know before invoking. It also clarifies this is a consolidation of three checks rather than a fourth check.

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 the purpose and the go/no-go value proposition, then the return values, then inputs and price — a sensible priority order with no filler. The query-string example is slightly redundant against the JSON schema but still earns its place as a usage illustration.

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 correctly carries the return-value burden (proceed/caution/stop, reasons, attestation), and pricing is disclosed. The gap is that the schema marks all 3 parameters optional (required: 0) and the description never says what happens with partial input — e.g. domain-only vetting — which an agent would need to know.

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 semantic meaning by mapping each input to the check it drives: domain → counterparty legitimacy, wallet → payee sanctions/disposable detection, amount → policy threshold. The inline '?domain=merchant.com&wallet=0x...&amount=500' example reinforces the shape of a real call.

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?

Specific verb ('Vet') plus specific resource and scope ('an entire payment before an agent sends money'), and it immediately enumerates the three dimensions checked: domain legitimacy, wallet sanction/disposable status, and amount policy. That scope ('entire payment') is what distinguishes it from the per-check siblings like dyoe_verify / dyoe_wallet / dyoe_merchant, even though those names aren't cited 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?

'Vet an entire payment before an agent sends money' gives a clear trigger condition, and 'one go/no-go instead of three calls' establishes that this is the aggregate alternative to multiple single-check calls. It lacks an explicit negative case (e.g. 'use dyoe_wallet if you only need a wallet check'), so the routing guidance is clear but not fully enumerated.

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