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

Annotations already establish write, non-idempotent, non-destructive, closed-world, so the bar is lower. The description still adds real value: it says what comes back (PO number and totals), that currency/VAT/buyer block are inherited from the shared profile, and that the tool is rate-limited to 5 documents per calendar month — a quota note the annotations do not carry.

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 short sentences, each earning its place: what it does, the unit/defaults caveat, the quota. No filler, front-loaded with purpose.

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 an 11-parameter write tool with no output schema, the description usefully names the return values and profile-derived defaults. But it omits any mention of nested line-item constraints (all lines must share one currency, max 200 items) and, worse, gives a unit convention that conflicts with the schema, leaving an agent materially misinformed on the most error-prone parameter.

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?

The sentence 'unit_price is in MAJOR units' directly contradicts the schema parameter unit_price_minor, whose own description says 'MINOR units: 9000 = 90.00 EUR ... Never a decimal'. An agent trusting the description would send prices 100x too high. The defaults note (currency, VAT, buyer block from profile) does add some meaning, but the unit error is material and dangerous; the schema's 100% coverage carries the rest.

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?

Name says it, and the description says it: specific verb 'Raise', resource 'purchase order', and states the inputs (items) and output (PO number and totals). Clearly distinguished from the sibling set (list/get/receive/pdf/delete), which all operate on existing POs rather than creating them.

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?

Creation intent is obvious, but the description never routes against alternatives — e.g., when to use purchase_order_create vs. purchase_order_receive, or that an unknown supplier gets created implicitly on the invoice server. The free-tier quota sentence gives useful routing context for constrained accounts.

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