Create batch from orders

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

Adds real context beyond the annotations: the batch is rated but not paid, no label is purchased, and large batches are built asynchronously with progress reported in the answer. That async behavior is not derivable from readOnlyHint=false / idempotentHint=false, and it materially affects how the agent should interpret the response. It stops short of saying what happens to unratable orders or how repeated calls behave.

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?

The core fact is front-loaded in one line, and the second paragraph elaborates usefully. Slight redundancy — 'nothing is bought' and 'no label is bought' say the same thing twice — but nothing is padding.

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 five-parameter creation tool with full schema coverage and no output schema, the description covers the essentials: what feeds the batch, that it is rated only, that nothing is charged, and that large batches return before completion with progress in the answer. An agent can call this correctly without further reading.

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 genuine meaning: recipient data comes from the orders while size and weight come from the saved package — the coupling between order_ids and package_id that the schema does not state. It leaves ship_from_id, title and override_multiple entirely to the schema, which is acceptable given full coverage.

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 first sentence names a specific verb and resource — turning store orders into a batch of shipments — plus the key constraint of a single saved package, so the agent knows exactly what is produced. It implicitly separates itself from create_batch and create_shipment by 'from imported orders' and 'batch of shipments', but never names those siblings explicitly.

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: it is the tool for orders already imported (schema even points to list_import_orders). 'Nothing is bought / no label is bought' steers the agent away from expecting labels, but there is no explicit when-to-use versus create_batch or when-to-ship versus create_shipment guidance.

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