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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds genuinely new behavioral context in that `items` REPLACES all previous items and that customer/payment changes are out of scope. It stops short of describing permission requirements or partial-failure behavior.

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?

Three dense sentences plus an endpoint, all front-loaded with the WRITE marker. Nothing is repeated and every clause carries actionable information.

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 5-parameter mutation with no output schema but strong annotations, the description covers scope, replacement semantics, exclusions, and the target endpoint. Minor gaps remain around authorization and how the implicit product-creation side effect for new item ids interacts with the update.

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 80% (baseline 3), and the description adds meaning on top: it names which fields are mutable, clarifies partial-update semantics, and flags the full-replace behavior of `items` — the one parameter whose consequence is not obvious from the schema alone.

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?

States a specific verb and resource ('change an order record's campaign, currency, total or items') and explicitly marks it as a WRITE, which cleanly separates it from read siblings like mailbluster_get_order and mailbluster_list_orders.

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?

Gives clear operating context ('send only what should change') and exclusions ('The customer cannot be changed here. No payment or email is involved'), so the agent knows the boundaries of the mutation. It does not name a specific sibling alternative the way a 5 would, but the when-to-use is unambiguous.

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