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

Goes well beyond the annotations by disclosing payer re-screening with payer_blocked semantics, the 10-year retention of refusals, the pending-until-mined behavior with 409, the 5-pending/30-unconfirmed throttling with 429, and single-use txHash rules with tx_already_used. This is exactly the error/limit/auth context annotations cannot carry.

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-loads the core action and keeps every sentence substantive with no filler. However, it is a dense single paragraph where distinct concerns (screening, pending, limits, hash reuse) run together rather than being cleanly separated, slightly reducing scannability.

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 write-oriented reporting tool with no output schema, the description covers return-relevant states and error codes, idempotency behavior, rate limits, and proof semantics. An agent can invoke and handle responses correctly with this alone.

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 four parameters (id, payer, method, txHash) are already documented in the schema. The description reinforces that the payer must be the signer and the txHash is the proof, but adds no format or constraint detail beyond what the schema already provides, so the baseline 3 applies.

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 action (report a payment transaction to the server) and resource (invoice payment), and explains that the server verifies on-chain what reached the receiver. It is clearly distinguishable from invoice_pay (which sends the payment) by the 'right after sending it' framing, though it never explicitly names the sibling it complements.

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?

Gives concrete usage context: call right after sending the transaction, call again once mined when you get payment_pending (409) or too_many_pending (429). It stops short of explicitly contrasting with invoice_report_analysis_payment or payout_report_payment, leaving that routing to inference.

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