attest_x402_payment

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

With no annotations at all, the description carries the full burden, and it does disclose one genuinely valuable behavior: idempotency keyed on txHash, meaning repeat calls with the same hash are safe. It does not say whether verification is re-checked server-side, what happens when verification fails, whether the record is permanent, or what the response contains. For an unannotated mutation tool that is a meaningful but partial 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?

A single front-loaded sentence with zero filler; the precondition and the idempotency guarantee are both packed into it. Nothing needs trimming and the key constraint appears first.

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 five-parameter write operation with no annotations and no output schema, the definition covers purpose, timing, and idempotency but leaves the effect of the call and most parameters unexplained. It is minimally viable rather than 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?

Schema description coverage is only 40% (txHash and wallet), so the description must compensate for amount, network, and resource, and it does not mention them at all. The one contribution is clarifying that txHash functions as the idempotency key, which adds meaning beyond the schema's format note. Three undocumented parameters outweigh that single gain.

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 and resource: 'Record an x402 payment attestation', scoped by a precondition ('after settlement verification'). That is clearly distinguishable from the sibling trust-check tools and even from pay_if_trusted, since this records an attestation rather than moving funds. It stops short of explicitly naming a sibling to route against, so 4 rather than 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?

'after settlement verification' gives a real timing precondition, which tells the agent this is a post-payment bookkeeping step, not the payment itself. However, no alternatives are named and no exclusions are stated, such as what to do if the payment was not verified or whether pay_if_trusted already performs this attestation. Usage is implied rather than spelled out.

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