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

Annotations already declare a non-destructive, idempotent write; the description goes further by explaining the create-vs-revision branching, that the receipt token is the same as the requirement token used by request_status and offers, and that no order is placed. These are state-consequence details the annotations cannot convey. There is mild tension with idempotentHint=true since a changed requirement produces a new revision, but the description does not contradict the annotation.

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 action and gate are front-loaded, and every clause carries information — create vs revision, token identity, no-order guarantee. The nested parenthetical makes one sentence dense, but nothing is redundant.

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 seven-parameter mutation with annotations and no output schema, the description covers what gets created, the token relationship, and the negative guarantee about ordering. The remaining gaps (contact requirement, op_id purpose, error behavior) are modest against the structured fields already supplied.

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 57%, so the description should compensate for the undocumented parameters. It does add real meaning for "revision" ("Name the revision the buyer saw"), which the schema leaves bare, but says nothing about contact or op_id, and nothing about how token and revision interact. Useful but partial coverage of the semantic gap.

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 gives a specific verb and resource ("Send the requirement to Plumbline") and distinguishes the two modes of the call: first send records a request, later send of a changed requirement records a revision. It also carves out what it is not ("This orders nothing"), which separates it from send_order_draft/submit_purchase_order, though it never names those siblings directly.

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?

The trigger condition is explicit — "once the buyer says to" — and the downstream flow is spelled out (an offer comes later and is accepted separately on its exact terms), which tells the agent not to treat this as a purchase. It does not, however, point at edit_requirement or submit_request as alternatives when the requirement is not yet approved, so one routing decision is left to inference.

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