update-order

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

No annotations are provided, so the description carries the full burden, and it discloses almost nothing beyond the bare fact of mutation. It does not say whether this is a partial update (do omitted fields get cleared or preserved?), whether it requires write scopes, whether changes are reversible, or how shipping address and metafield writes 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?

A single short sentence is front-loaded and free of padding, so it is structurally fine. The brevity comes from under-specification rather than discipline, which caps the score.

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 mutation tool with 9 parameters, nested objects, no annotations and no output schema, one sentence is grossly insufficient. An agent cannot tell what a successful response looks like, what happens to unspecified fields, or how metafield updates differ from set-metafields.

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 22% across 9 parameters and nested metafield/customAttribute objects, so the description must compensate — and it mentions zero parameters. No field names, no id requirement, no metafield upsert semantics, nothing an agent could not already read from the raw 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?

The verb and resource are identifiable ("Update an existing order"), but "with new information" is filler that adds nothing, and the description never says which parts of an order can be changed. Against order-cancel, order-close-open, order-mark-as-paid and order-edit siblings, it gives no hint of scope that would separate it from those more specific mutations.

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?

There is no guidance on when to use this tool versus the many other order-mutation siblings, and no prerequisites stated in the description. The only routing hints (look up by order number via get-order-by-id, prefer set-metafields for standalone metafield work) live in the schema, not in the description.

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