Execute reviewed commerce tasks

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

Annotations already flag destructive/non-idempotent/open-world, but the description goes well beyond them: prevalidation of all tasks, hash verification before the first request, sequential ordering, stop-on-first-failure with known results and unattempted indices, and the absence of retry, transaction, rollback or implicit continuation. For a destructive batch executor, these atomicity guarantees are exactly what an agent needs.

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?

Three tight sentences with no filler; the count and confirmation constraint are front-loaded and the failure/atomicity rules follow. Dense and efficient, though the first sentence is fragmentary enough that its subject depends on the title.

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?

With no output schema, the description usefully explains the partial-failure result shape (known results plus unattempted indices), which is the critical return case for a non-transactional batch. It does not describe the success response, a minor gap, but covers preconditions and semantics thoroughly.

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%, so tasks, account, confirm and review_sha256 are fully documented in the schema. The description adds no syntax or format detail beyond mapping loosely to the review hash, so the baseline 3 applies.

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?

The description states the tool executes 'one-to-twenty ordered effects,' and with the title 'Execute reviewed commerce tasks' plus the enum of 16 commerce operations, the purpose is unambiguous. It stops short of naming preview_commerce_batch, which is the natural sibling, but the reference to an 'exact review hash' implies the preview workflow clearly enough.

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?

'Confirmed' and 'check the exact review hash before the first request' establish the precondition that this must follow a review/preview step, and the failure semantics tell the agent how to behave mid-run. It never explicitly says 'use preview_commerce_batch first' or states when-not to use it, so a small gap remains.

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