update_invoice

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

No annotations are present, so the description carries full behavioral burden. It discloses the destructive line-replacement behavior ('lines, if given, REPLACES all existing lines') and the posted-document rejection. However, it does not mention whether 'values' merges or overwrites header fields, nor does it describe return values or permissions, which slightly reduces transparency.

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 sentences with zero waste. The first sentence states purpose, the second gives a critical exclusion, and the third details the destructive lines behavior. Information is front-loaded and each 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?

Given the tool's complexity (nested objects, no output schema, no annotations), the description covers the main functionality and key caveats. It leaves minor gaps such as the exact behavior of 'values' (merge vs replace) and response format, but the critical info for safe usage is present. The reference to create_invoice helps with line-dict shape.

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 description coverage is 0%, so the description must compensate. It explains 'lines' thoroughly (replaces all existing lines, same shape as create_invoice) and implies 'values' is for header fields from the opening sentence. 'move_id' is self-evident. Lacks explicit detail on the 'values' object structure, but coverage is strong overall.

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 uses a specific verb 'Update' with a clear resource ('draft invoice/bill') and scope ('header fields and/or replace its lines entirely'). It distinguishes itself from siblings like post_invoice and create_invoice by explicitly stating draft-only status and the line replacement behavior.

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?

Provides explicit guidance: 'Odoo will reject this once the move is posted -- use a reversal/credit note for posted documents instead.' This clearly states when NOT to use the tool and names an alternative for posted documents. Also references create_invoice's lines argument for shape consistency.

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