update_purchase_invoice

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

Beyond the destructiveHint annotation, the description reveals exactly what gets replaced, how the voucher is matched, and a serious failure mode: Tally's Alter lookup can silently corrupt the wrong voucher when another type shares the same number. It also states the tool refuses to run under collision, giving the agent accurate expectations about destructive risk and prerequisites.

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?

The description uses three dense sentences, each earning its place: the action and scope, the parameter-relationship and matching prerequisite, and the collision warning with a remediation step. The most important information is front-loaded, and there is no filler or repetition of schema content.

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 destructive 17-parameter update tool with no output schema, the description is remarkably complete: it specifies the matching identity, preconditions, what is replaced, and a known failure mode with the correct response. It leverages the schema for parameter detail and the create_purchase_invoice sibling for field semantics, leaving no critical gap for an agent to invoke it correctly.

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 high (88%), so the baseline is 3. The description adds meaning by clarifying that the parameter set is identical to create_purchase_invoice plus voucherNumber, and by identifying date + voucherNumber as the matching key. This is valuable semantic context beyond the individual field descriptions, though much of the parameter detail is already in the schema.

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 opens with a specific verb ('Update'), a specific resource ('existing item-invoice Purchase voucher in TallyPrime'), and the exact scope of the update ('replacing its item lines, party, and narration'). It also distinguishes itself from the likely alternative create_purchase_invoice by noting 'Same fields as create_purchase_invoice, plus voucherNumber', and from the generic update_voucher sibling by specifying item-invoice Purchase vouchers.

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 gives clear usage context: it is for updating an existing item-invoice Purchase voucher, and it instructs the agent to confirm existence and uniqueness via get_ledger_vouchers or get_vouchers first. It also explains the matching logic (date + voucher number) and what to do on collision. However, it does not explicitly state when not to use this tool versus alternatives such as create_purchase_invoice or update_voucher, though that is strongly implied.

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