update_voucher

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description builds on them substantially: it discloses that ledger entries and narration are overwritten, that matching is by type + date + number and must be exact, and — most valuably — that the tool refuses on type collisions because Tally's Alter lookup ignores voucher type and can 'silently corrupt the wrong one'. That live-confirmed corruption warning is exactly the kind of behavior an agent cannot infer from annotations or schema. No contradiction with annotations.

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?

Four sentences with zero filler, ordered by importance: core action first, then matching criteria and perequisite, then the two input modes, then the failure mode and remediation. For an 18-parameter destructive tool, every sentence carries distinct operational value.

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 complex, destructive tool, the description covers the critical operational facts: what gets replaced, how the target voucher is identified, the uniqueness requirement, the existence-check prerequisite, both input modes, and the collision refusal with its remedy. The main gap is that it does not route agents among the many update_* siblings (e.g., when to prefer update_sales_invoice over this generic updater), and with no output schema it says nothing about return behavior — a minor gap against an otherwise rich coverage.

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 real value on top by explaining the mode split the schema only hints at: debitLedger/creditLedger/amount for simple 2-leg vouchers versus entries for 3+ lines, with mutual exclusivity made explicit. It also elevates the three required parameters (voucherType, voucherNumber, date) into a matching-key constraint, giving them meaning beyond their individual field descriptions.

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 states a specific verb and resource — 'Update an existing voucher in TallyPrime' — and specifies the scope of the operation ('replacing its ledger entries and narration'), which clearly separates it from create_voucher and delete_voucher. However, it never explicitly differentiates itself from the many specialized update_* siblings (update_sales_invoice, update_credit_note, etc.), so an agent must infer that this is the generic updater from the voucherType parameter.

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 actionable usage context: confirm the voucher exists first via get_ledger_vouchers or get_vouchers, and if the tool refuses on a number collision, resolve it in Tally before retrying. It does not, however, state when not to use this tool in favor of a specialized sibling like update_sales_invoice, so exclusions are left implicit.

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