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

Annotations already declare idempotent=true and destructive=false; the description adds the critical behavior beyond them — existing samples and quotes are replaced, and revision must be based on the current expected_revision. It still doesn't state what happens to omitted optional parameters (whether they reset), which matters for a full-replace revision.

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 sentences, each carrying distinct information: what it does, the replacement side effect, and the trigger condition. The side-effect warning is placed before the routing hint, which is the right order.

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 19-parameter, no-output-schema, open-world mutation, the description covers revision semantics, precondition, and selection criteria. The remaining gap is whether optional fields are cleared on revise, which the schema does not resolve either.

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 63%, and the description compensates by explaining the semantics of the key parameter (expected_revision must be current) and the full-set-of-fields expectation, which clarifies that this behaves like a replace rather than a patch. It doesn't address the optional fields' reset behavior, leaving a real ambiguity.

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 (revise) plus the constrained resource (an unpaid request) and the mechanism (expected_revision with the full set of required fields). It also distinguishes from siblings implicitly by scoping to unpaid requests, versus submit_requisition for new ones and confirm_quote/start_order for later stages.

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 an explicit trigger: use it when next_action is revise, including the no_capability reason_code path with guidance to try other sources or fields. It does not name the sibling to avoid (submit_requisition) for a request that was never submitted, so it is not fully routing-complete.

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