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

Annotations give only the bare safety flags, and the description adds genuinely useful behavioral context: the call is effectively a dry run, it returns a preview of proposed changes plus a confirmation link, and only the merchant can commit. The note of tension with readOnlyHint=false is minor since the tool does produce a side effect (the confirmation artifact), and destructiveHint=false is consistent with 'changes nothing'.

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?

Short and front-loaded, which is good, but the middle sentence about money being integer minor units is irrelevant to this tool's only parameter and reads as boilerplate carried over from sibling order tools. That sentence does not earn its place.

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 single-parameter mutation-ish tool with no output schema, the description covers the important surprise (no immediate mutation, preview plus confirmation link, merchant-only commit). What remains missing is guidance on alternatives and failure/precondition behavior, which keeps it short of complete.

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 description coverage is 100% (orderNumber is documented as the human order number, e.g. 1003), so the baseline is 3. The description's sentence about money in integer minor units adds no meaning to the single orderNumber parameter and does not map to any field here.

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 concrete verb and resource ("Mark an order as paid") that distinguishes it from nearby siblings like orders_refund, orders_fulfil, and orders_send_payment_link. The added detail that it produces a preview rather than an immediate state change sharpens the meaning, though the headline verb and the 'changes nothing' qualifier sit in slight tension.

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?

Usage is implied through the workflow it describes (call it, receive a preview and confirmation link, merchant completes it). However, there is no explicit guidance on when to choose this over orders_send_payment_link, orders_refund, or a manual note, and no stated preconditions such as the order being unpaid or having pending payment.

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