proforma_invoices_convert

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

No annotations are provided, so the description carries the full burden. It does disclose key behaviors: it creates a new invoice, marks the proforma as converted (a state change), and links the two documents together. It also discloses the return of both objects. However, it doesn't state whether the operation is reversible or destructive to the proforma, whether the proforma's status precludes conversion (e.g., already converted), or what happens to the linked state afterward.

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 sentences, zero wasted words. It front-loads the primary action and then covers the side effects and return value efficiently. Every sentence earns its place.

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?

The description covers the core flow well (create, mark, link, return). No output schema exists, but the return value is described ('both the new invoice and updated proforma'). However, it lacks details on edge cases relevant to a conversion: preconditions (is the proforma required to be in a certain status?), what happens if the proforma is already converted, and whether conversion can be undone. For a multi-effect operation, a bit more on preconditions and failure semantics would be valuable.

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 baseline is 3. The description adds value by clarifying the overall conversion flow, and the schema properties themselves have good descriptions (override dates with defaults, series override). The description doesn't add param-specific meanings beyond schema, but the schema is already comprehensive, so this is adequate.

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 clearly states the verb ('Convert'), the resource ('proforma invoice into final invoice'), and the exact behavior: creates a new invoice with all proforma data, marks proforma as converted, and links the two documents. This distinguishes it from sibling proforma tools (create, accept, reject, cancel) and is very specific.

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 description implies when to use it (when you want to convert a proforma into a final invoice). However, it doesn't explicitly state when NOT to use it or name alternatives (e.g., delivery_notes_convert, receipts_convert_to_invoice exist as sibling converters). There are no exclusions, prerequisites, or mention of related conversion tools for other document types.

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