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

With destructiveHint=true already declared, the description adds the meaningful nuance that updates are partial and additive ('Nothing is deleted', 'Send only the fields you want to change'), plus a read-before-write validation step and the underlying PUT /api/orders. It does not describe the response body or error payloads, and 'nothing is deleted' sits in mild tension with the destructive hint, though modification of existing lines justifies it.

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?

Front-loaded with the operation and its guard condition, then the write semantics, then the nested-array rule. Dense but nearly every clause carries information; the long parenthetical and the 'PUT /api/orders' tail add a little clutter without much payload value.

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 14-parameter, nested-object mutation with no output schema and thin schema documentation, the description supplies the semantics that matter most: partial update behavior, no-deletion guarantee, id-based line editing, and refusal on shipped/printed orders. Remaining gaps are in the less ambiguous scalar fields, which an agent can reasonably infer from their names.

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 only 21%, so the description must compensate and largely does: it groups the mutable fields and, critically for the nested arrays, explains that including item_id/package_id modifies an existing line while an id-less line is added. Left unexplained are several top-level fields (currency, signature_required, order_number, shipping_description), so it is helpful but not exhaustive.

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 opening clause gives a specific verb, resource, and scope: 'change details of ONE UNSHIPPED order by order_id.' It then enumerates the mutable field families (addresses, shipping method/carrier/service, items, packages, reference, note), so an agent can distinguish it from create_order and the various list_* siblings without opening the schema.

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?

Explicit preconditions ('refused if it is already printed or shipped') and explicit exclusions ('never sends status or manifest flags... does not print a label or buy postage') route the agent away from print/label/manifest tools. It also tells the agent to send only changed fields and where to obtain item_id/package_id (starshipit_get_order with include=Items,Packages).

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