proforma_invoices_update

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

Annotations cover the safety profile (not read-only, not destructive, idempotent, closed-world), so the description earns credit for the extra constraints it adds: the status gate and the fact that line items are wholesale replaced rather than merged. It does not clarify what happens to optional fields that are omitted (cleared vs preserved) or whether the document is regenerated/re-numbered on update.

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, zero filler, with the identity, the precondition, and the most surprising side effect front-loaded. Every sentence carries actionable information.

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 23-parameter, 8-required mutation with no output schema, the biggest open question is whether this behaves as a full replacement of the whole document (fields omitted get reset) or a partial merge; the description only resolves this for lines. The draft precondition is present, but the payload-replacement model and post-update state are left to inference.

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 all 23 parameters, including the per-line 'omit to create new' hint and the replacement semantics on the lines array. The description's 'replaces all line items' restates what the schema already says rather than adding syntax or defaulting guidance beyond it, so baseline 3 applies.

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 an existing proforma invoice'), which is unambiguous against the many siblings prefixed with proforma_invoices_ and distinguishable from invoices_update. It does not explicitly contrast with proforma_invoices_create or proforma_invoices_convert, but the verb+resource is precise enough to route correctly.

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?

'Only invoices in draft status can be updated' is a genuine when-not condition that prevents failed calls on issued/accepted invoices. What is missing is routing guidance against alternatives such as proforma_invoices_cancel or proforma_invoices_convert for non-draft documents.

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