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

Beyond the annotations (non-destructive, non-idempotent, not open-world), the description explains the lifecycle: a draft commits to nothing, can be cancelled and re-raised, and once issued prices are frozen and matched against bills. It also states the direct effect ('purchase order created in draft'), which tells the agent exactly what state change to expect.

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?

It is front-loaded with purpose and key constraints, then lifecycle and effects. It is slightly long but each sentence carries operational value, with no filler.

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?

No output schema exists, but the description states the effect (created in draft) and the post-draft/issue consequences, which is enough for a mutation tool whose annotations already cover the safety profile. It doesn't describe what ID or handle is returned, but that is a minor omission.

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%, so the schema already documents every parameter. The description still adds real semantic content: it explains that unit_price must be the vendor's quote price (not sell price) and that lines must reference core items, clarifying intent beyond the field descriptions.

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 opens with a specific verb and resource ('Draft an order to a vendor') and immediately clarifies the semantic content ('what, how many, at the price they quoted'). The distinction from issuing (p2p_issue_po) is implied via 'drives nothing until issued', so an agent can separate drafting from committing.

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?

It gives concrete operational guidance: use items as on record (core items), one line per item, use the vendor's quote price never the sell price, and 'never invent a price or a quantity: ask'. It doesn't explicitly name a sibling alternative, but the draft-vs-issue lifecycle is clear enough to route correctly.

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