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

Beyond annotations marking it destructive and non-idempotent, the description discloses irreversibility through the API, customer-email side effects with the exact default and whole-order restriction, tracking-number storage only for shipped status, and scoping rules for partial updates. This is rich behavioral context that materially reduces misuse risk.

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 definition is dense but front-loaded: it starts with the write action and scope, then covers irreversibility, side effects, partial-update mechanics, and the endpoint. Every sentence adds operational value with no filler.

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?

Given eight parameters, no output schema, and rich annotations, the description provides enough context to call the tool safely: scope, status constraints, email side effects, irreversibility, and endpoint. No critical behavioral or parameter guidance 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 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: contact_customer sends an email only on whole-order changes and defaults to false, shipping_code applies only to shipped status, and workflow_item_id plus qty target part of a line. These details help an agent choose and combine parameters correctly.

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 a specific write action and resource: moving an order, line item, or part of a line item to 'produced' or 'shipped'. It clearly distinguishes the three scopes and names the exact endpoint, so an agent can identify the operation 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?

It gives explicit conditions for contact_customer, order_line_id, workflow_item_id, and qty, and warns that the action cannot be undone through the API. It does not explicitly route the agent to a sibling alternative, but no direct alternative exists for this mutation; the guidance is clear and actionable.

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