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

Annotations say readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the write/open-world nature is already declared. The description adds genuinely new behavioral context beyond that: without payment_authorization it only returns a challenge, with it, it can pay and send real mail, and no document or addresses are resubmitted. It notably reveals a real-world mailing side effect not captured by destructiveHint=false, though it does not spell out idempotency or permissions in depth.

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?

Six sentences, front-loaded with purpose then usage then behavior. Most sentences carry distinct value, but it is somewhat dense and a sentence like 'Review the preview or campaign_url, recipient count and total' mixes in output detail that could be trimmed.

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?

An output schema exists, so return values need not be enumerated, and the description still points to the returned payment status. Combined with clear inputs, prerequisites, retry behavior, and the challenge-vs-pay distinction, an agent has everything needed to invoke it correctly.

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 only 50%: payment_authorization is documented in the schema, but order_id has no schema description. The description compensates by explaining where order_id comes from (draft tools with payment_protocol=mpp, or create_machine_order) and that it should be reused verbatim on retries. That adds real meaning beyond the UUID format constraints.

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 (pay) and resource (existing MPP order across PDF, letter, form, or bulk campaign), plus the prerequisite (buyer approval) and the challenge-only mode. It also names the sibling create_machine_order, so an agent can distinguish it from the draft-creation tools without opening a schema.

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?

Explicitly says to use the order_id returned by any draft tool with payment_protocol=mpp or by create_machine_order, and gives the exact procedure when switching from create_machine_order (omit the credential first to obtain this endpoint's challenge). Retry guidance is also given. Nothing about when/when-not is left to inference.

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