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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds substantive context beyond them: the change propagates to the marketplace, the order becomes 'partial' and requires later repeat calls, and the operation cannot be undone via the API and is never retried. The timeout warning is exactly the operational caveat an agent needs for a non-idempotent destructive write.

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?

Purpose is front-loaded, then the required inputs, then the partial-shipment branch and its exception, then endpoint and safety caveats. Every sentence carries information an agent would otherwise have to guess; nothing is redundant with the title or annotations.

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 an 8-parameter destructive, non-idempotent write with no output schema, the description covers the irreversibility, the retry hazard, marketplace propagation, and the partial-shipment lifecycle. It stops short of stating permission/auth requirements or the shape of a successful response, which are the only remaining gaps for an otherwise thorough definition.

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 every parameter is already documented at baseline 3. The description still adds real semantics: transporter must be a Channable transporter code with a pointer to the lister, and order_item_ids changes the resulting order state to 'partial' and implies a later follow-up call — consequences the schema does not state. Optional params like delivery_bill_id and return_tracking_code are left to the schema.

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?

Opening clause states a precise verb and resource ("Set an order to shipped, with tracking data") and the endpoint confirms it is a shipment mutation. Siblings like cancel_order, create_return, and mark_order_manual are clearly distinct operations, so no ambiguity arises.

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 routes the agent to channable_list_transporters for transporter codes, spells out the partial-shipment condition (pass order_item_ids) versus the whole-order case (omit it), and names the exception (Spartoo and Veepee do not support partial shipments). The retry-after-timeout guidance tells the agent exactly what to do in the failure case instead of blindly re-calling.

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