Update a draft invoice

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds real context beyond them by disclosing the draft-only precondition and the exact error code on violation. It stops short of saying whether items/taxes arrays are replaced wholesale or merged, which matters for an update tool.

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 short sentences with the identity statement first and the constraint second. No filler, no restating of the title, and the error code is placed exactly where an agent will look for it.

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 7-parameter mutation with nested objects and no output schema, the definition covers the critical precondition but leaves the caller guessing on update semantics for arrays and on what the response contains. Adequate to invoke, not fully complete.

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 only 14% across 7 parameters, so the description has to carry weight; it enumerates which fields are updatable, which does map to the optional params. However, it adds no meaning beyond the field names — no note that `id` is required, no currency-unit guidance, and no replacement-vs-merge semantics for the nested arrays.

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 ("Update a draft invoice") and enumerates the mutable surface (customer, items, taxes, due date, memo, metadata). This clearly separates it from sibling write operations like finalize_invoice, void_invoice, and mark_invoice_uncollectible.

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 when-not: only drafts can be changed, and the failure mode is named (`409 invoice_not_draft`). It doesn't route the agent to the sibling to use instead when an invoice is finalized (e.g. void_invoice or mark_invoice_uncollectible), which keeps it short of a 5.

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