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

Annotations already flag destructive=true, non-idempotent, openWorld, so the bar is lower, yet the description adds genuine context beyond them: which actions move real money on the owner's Stripe account, the confirmation gate required for five of them, and the cross-action side effect that unbook reopens dates without refunding. It says nothing about reversibility, failure modes, or what non-money actions like decline or send_balance_link actually do.

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?

Four short sentences, front-loaded with the money-moving scope and then the confirmAmount rule, with no filler. The phrasing is telegraphic enough ("the tool says the amount to ask the owner about") that it reads more like compressed shorthand than polished guidance, but nothing is wasted.

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 destructive 14-action, 8-parameter money tool with no output schema, the description covers the highest-risk surface: the Stripe account it charges, the owner-confirmation requirement, and the unbook side effect. The remaining actions are largely self-explanatory and their parameters are schema-documented, though the description never says what a successful call returns or how a partial refund behaves at the order level.

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 88%, so the schema already documents id, orderId, amount, confirmAmount, carrier, tracking and notifyBuyer; the description's added meaning is the mapping of which actions require confirmAmount, which is useful but narrow. The bulk of its parameter information duplicates what the schema already says.

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?

"Act on an order" is a soft verb, but the description immediately names the domain and effect (moves money on the site's own Stripe account) and enumerates the money-moving actions, which distinguishes it from read siblings like get_order and list_orders. It stops short of stating that this is the single mutation endpoint for all order state changes, leaving the full action surface inferable only from the enum.

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?

It gives an explicit operating constraint — only for an order and amount the owner asked about — plus a concrete fallback: without confirmAmount the tool returns the amount to ask the owner about. That is real when-to-use/when-not guidance, but it never points to an alternative tool (e.g. get_order to inspect state first), so the alternative routing is only implied.

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