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

Annotations already declare readOnly=false, idempotent=true, destructive=false and openWorld=false. The description adds genuinely new behavioral scope: only the status field is recorded, and no message is sent nor invoice created — important expectations for a mutation tool, though it says nothing about whether arbitrary status transitions are validated.

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?

Two sentences with zero padding: the action and its inputs come first, and the negative scope follows as a guardrail. Every clause carries 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 two-parameter mutation with rich annotations and no output schema, the definition covers what is needed to call it correctly. The only mild gap is transition validity — whether any status may be set from any other state.

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%, with both parameters documented and the status enum spelled out inline in the schema. The description restates the status values and the quote-number example rather than adding new meaning, so the baseline of 3 applies.

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 ('Sets the status of a quote or invoice'), identifies the key ('by its number'), and enumerates the allowed values (draft, sent, viewed, accepted, rejected, invoiced). The closing clause separates it from tools that actually send or invoice.

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 context for use and an explicit exclusion ('it does not send anything or create an invoice'), which steers an agent away from expecting delivery side effects. It stops short of naming a specific sibling alternative for the send/invoice cases, so it is not a full when/when-not/alternative triad.

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