update_delivery_note

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses critical matching logic ('Matched by date + voucher number') and a subtle safety behavior: it refuses when a voucher-type collision exists, warning that Tally's Alter lookup can 'silently corrupt the wrong one.' This is valuable context not captured in 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?

The description is dense but every sentence serves a purpose: purpose, matching, collision warning, and resolution. It front-loads the action and then details necessary prerequisites and failure modes without redundancy. Concise and well-structured.

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 (12 params, update semantics, matching criteria, collision risk, no output schema), the description covers the essential knowledge: how it matches, what it replaces, what to do first, and how it handles ambiguity. Nothing critical is missing for correct invocation.

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?

The schema has 100% coverage with detailed per-parameter descriptions, so baseline is 3. The description adds meaning by clarifying that the tool 'replacing its item lines, party, and narration' (which is only partially explicit in the schema) and noting that voucherNumber is the update key. This adds a little beyond the schema, justifying a 4.

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 precise action ('Update an existing Delivery Note in TallyPrime') and explicitly lists what gets replaced (item lines, party, narration). It distinguishes itself from create_delivery_note by mentioning the additional voucherNumber field, making its purpose unambiguous.

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 pre-conditions: 'use get_ledger_vouchers or get_vouchers first to confirm it exists and is unique.' It also provides actionable guidance on the collision failure ('resolve the collision in Tally first if that happens'), and implies when to use the create counterpart by referencing its shared fields.

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