pay

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

Goes well beyond the annotations: it warns the action spends real money irreversibly, explains idempotency caching (re-calling a paid key returns the cached receipt without paying), and discloses the 9-minute resend carve-out for delegated settlements the seller failed to deliver. It also explains where the spending cap comes from in each mode, and that mandates are enforced server-side before signing.

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?

The money risk is front-loaded in the first clause, followed by the flow, then mode selection, then the routing advice and exclusion. Dense but nearly every sentence carries operational weight; the parenthetical asset/network list is the only mildly expendable detail.

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?

No output schema exists, and the description does cover the return ('response plus a structured machine-readable receipt'), the auth/prerequisite (private key or stored agent), and idempotency behavior. It stops short of describing what the receipt contains or what happens on policy rejection or payment failure, which for a destructive money-moving tool would be worth one more clause.

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 50%: idempotencyKey and agent are richly documented in the schema, but body, method, and headers have no descriptions anywhere. The description adds the delegated-mode meaning of `agent` and reinforces idempotency semantics, but says nothing about how body/method/headers are forwarded to the target endpoint, so it only partially compensates.

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 and resource ('makes the HTTP request... if the server answers 402... pays, retries'), and names the exact mechanism (x402 payment flow) rather than restating the tool name. It is immediately distinguishable from siblings like inspect and balance, which do not move funds.

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 an explicit prerequisite workflow ('Use inspect first to see the price') and an explicit exclusion ('Do not use for ordinary unpaid HTTP requests'). It also documents the mode-selection rule (PAYAGENT_PRIVATE_KEY set vs. stored ArisPay agent) that determines which code path runs.

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