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

Annotations only cover readOnly/destructive/idempotent/openWorld, so the description carries real weight and delivers: funds are held then charged only on printer acceptance, release with no charge if the printer refuses, no charge plus re-approval if total/document/address changed, and idempotency_key reuse guarantees a single charge. It also enumerates every transaction_state value and states the correct user-facing claim threshold (VENDOR_ACCEPTED or later), which annotations could never convey.

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?

Dense and front-loaded — the core action and its gating conditions come first, with payment/state details after. It is on the long side and the payment-mechanics sentences could be tightened, but nearly every clause carries actionable information for a tool that moves money.

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 money-moving, open-world purchase tool this is complete: approval preconditions, token requirement, hold/settle semantics, idempotency contract, change-detection behavior, fallback payment path, and state-machine interpretation are all present. An output schema exists, and the description still adds the state semantics an agent needs to phrase results 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 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema cannot: expected_total_cents is what the person approved and a mismatch aborts the charge, and one idempotency_key must be reused across retries so the same key never charges twice. The remaining parameters are simply echoed from their schema descriptions.

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 ('Buys and sends a letter') and ties it to the exact upstream tool that produced the input ('that prepare_certified_letter prepared IN THIS CONVERSATION'), which cleanly separates it from get_certified_letter_status and the quote/prepare siblings. An agent can tell what this does without opening the 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?

Gives two explicit, checkable preconditions (person approved the exact total/recipient/service in this conversation; a Stripe spt_ token granted to Piloxa exists) and an explicit when-not path: without a token nothing is charged and approval_url is returned for the person to pay. It also routes retry behavior away from this tool at OUTCOME_UNCERTAIN toward get_certified_letter_status.

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