create_physical_stock

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

With readOnlyHint=false, the description carries the burden of disclosing mutation behavior and exceeds it: it discloses a prior failure mode ('an earlier version of this tool was found to corrupt the closing balance to a nonsensical negative number'), the fix verification ('counting 95 of an item that had 100 correctly closed the item at 95'), a technical XML detail (DIFFACTUALQTY=Yes at voucher level), and a deliberate non-behavior (no ledger write-off). No contradiction with annotations — readOnlyHint=false aligns with the stated balance mutation.

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 purpose is front-loaded in sentence one and the create_voucher boundary is a clean closing sentence. However, the middle sentence is a ~55-word run-on mixing low-signal implementation minutiae (DIFFACTUALQTY, per-line flag, XML template) with the verification story, which could be split and trimmed. At roughly 95 words, it is informative but denser than necessary for an agent deciding whether to invoke.

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 write tool with readOnlyHint=false and no output schema, the description covers the essential operational facts: what it mutates, the verified behavior, the scope boundary (no monetary posting), and the known failure path is covered in the schema's voucherNumber guidance. The only gaps are the lack of explicit return-value expectations and the missing update_physical_stock contrast — minor given the rich schema carrying the godown and retry edge cases.

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 schema already documents date format (DD-MM-YYYY), godown auto-fill conditional behavior and failure mode ('the call fails naming the available godowns'), batchName default, and voucherNumber retry logic. The description adds tool-level context but no per-parameter meaning beyond what the schema provides, so it neither needs to compensate nor does it elevate.

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 names a specific verb ('Create') and resource ('Physical Stock voucher in TallyPrime') and defines the core behavior: 'records a physical count and updates the stock item's book quantity to match it (that's the point of the voucher)'. It explicitly distinguishes itself from create_voucher by stating what it does NOT do ('does not post any monetary/ledger write-off'), making sibling differentiation concrete.

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 an explicit alternative and condition: 'do that separately with create_voucher if needed' for the shortage/excess write-off. The schema adds a concrete retry path via get_vouchers when creation fails with 'EXCEPTIONS:1' and voucherNumber guidance. However, it never contrasts with the natural sibling update_physical_stock, so when to create vs. update is left to name inference rather than stated.

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