create_voucher

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

Annotations are all false, so the description carries the burden; it does disclose real behavioral traits: Tally's numbering series can silently restart (with a concrete example), the entries path is pre-validated so double-entry mismatch fails with a clear error before reaching Tally, and buyerTrn/buyerState/buyerCountry behave differently for Sales-class vs Purchase-class vouchers. It stops short of describing the full response shape or other failure modes, which is why it is a 4 rather than a 5.

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 is longer than the average tool description, but nearly every clause earns its place: it compresses the 2-leg vs multi-line distinction, the numbering failure workaround, and a cross-tool pointer into roughly three dense sentences. It front-loads the core action and the mode choice before the edge-case voucherNumber caveat. It could be tightened slightly, but it is structured and information-dense rather than redundant.

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 22-parameter mutation tool with no output schema, the description does an unusually complete job: it explains when to use entries, when to override numbering, what the double-entry constraint is, how reference relates to bill-wise settlement, and which Sales-class caveats apply to buyerTrn/buyerState/buyerCountry. What is missing is mostly what an agent would learn from the output schema or from trying the tool (e.g. exact response format, whether the call fails synchronously), so the gap is not a description failure.

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 100%, so the baseline is 3; the description earns the extra point several ways. It clarifies the mutual exclusivity between entries and debitLedger/creditLedger/amount, explains that entries replaces the simple mode entirely, adds the real-world voucherNumber auto-numbering caveat, distinguishes reference (voucher-level REFERENCE) from per-leg bill references (debitBillName/creditBillName), and gives a working example for reference. These go well beyond restating the property names.

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 phrase 'Create a new voucher ... in TallyPrime', enumerates concrete voucher types (Payment, Receipt, Sales, Purchase, Journal), and immediately differentiates the two supported modes (simple 2-leg vs multi-line entries). This clearly distinguishes it from create_sales_invoice, create_purchase_invoice, update_voucher, and the other sibling create_* tools.

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 explicit when-to-use guidance: use debitLedger/creditLedger/amount for a simple 2-leg voucher, use 'entries' for 3+ lines, and pass voucherNumber only when Tally's auto-numbering misbehaves, with a concrete live example. It also directs the agent to check get_vouchers for the correct next number first, and points to create_purchase_invoice's separate buyerTrn/supplierTrn when the purchase-class caveat applies. This proactively routes to alternatives and even warns against misuse.

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