Delete batch

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

Annotations already declare destructive=true and idempotent=false, and the description adds genuinely new behavior: deletion is gated on the draft being unpaid, and bought labels will not be removed. It stops short of saying what the agent sees when the gate fails (error vs silent no-op) or that a batch delete removes multiple items at once.

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?

Two short sentences, the operation and its scope up front, the alternative path second. Nothing redundant and nothing buried.

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 one-parameter mutation with no output schema, the description covers the safety constraint and the escape hatch, which is the core need. Minor gaps remain around failure behavior and batch-level scope, but nothing an agent needs before invoking it correctly is missing.

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 0% and the single required batch_id is undocumented, but the description partly compensates by attributing the batch to create_shipment/create_batch, implying where a valid identifier comes from. It gives no hint about identifier format or that list_batches/get_batch can supply one, so it adds only marginal meaning.

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 ("Deletes an unpaid draft batch") and ties the object back to its origin (create_shipment / create_batch), which separates it cleanly from refund_batch and the other siblings. The phrase "or single shipment" is a slight mismatch with a tool whose only parameter is batch_id, leaving a small ambiguity about whether shipment-level deletion is really supported by this call.

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 defines the usable domain (unpaid drafts, anything not yet bought) and the excluded domain (bought labels cannot be deleted), then routes the agent to refund_label or refund_batch for that case. Both the when and the when-not, with named alternatives, are present.

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