PNPC-MCP-Tally-Prime

create_debit_note

Records a purchase return by creating an item-invoice Debit Note in TallyPrime, reversing stock quantity and expense for returned items against the supplier ledger.

Instructions

Create an item-invoice Debit Note in TallyPrime — a Purchase return, reversing stock and expense for returned items. Same shape as create_purchase_invoice but with the debit/credit convention flipped, matching Sales's sign pattern (a Debit Note is structurally a reverse Purchase entry). Confirmed live on a real company: returning 3 units correctly decreased the item's book quantity by exactly 3. Same godown and dual-role deletion caveats as create_purchase_invoice apply.

Input Schema

Name	Required	Description
`date`	Yes	Debit note date in DD-MM-YYYY format
`items`	Yes	One entry per returned line.
`billName`	No	Bill reference to settle against, e.g. the original bill's name. Defaults to 'Agst Ref' billType.
`billType`	No	Defaults to 'Agst Ref' — settling against the original purchase's bill, unlike create_purchase_invoice's 'New Ref' default.
`buyerTrn`	No	YOUR OWN company's TRN on this debit note (Tally's BASICBUYERSSALESTAXNO field) — you are the buyer on a purchase-side document. Normally constant; check get_company_info.
`narration`	No	Narration / description
`reference`	No	Free-text reference for this debit note (Tally's voucher-level REFERENCE field).
`vatLedger`	No	Default VAT ledger for items without their own override.
`buyerState`	No	YOUR OWN company's Emirate/state on this debit note's Party Details.
`partyLedger`	Yes	Supplier ledger name (the party being debited)
`supplierTrn`	No	The supplier's (party's) TRN on this debit note (Tally's TRADERCONSVATTINNO field). Distinct from buyerTrn below — NOTE the asymmetry: on a purchase-side document the party is the supplier, not the buyer.
`voucherType`	No	Voucher type to post as, for a company that uses its own Debit Note-class type in Item Invoice mode (e.g. 'Tax Invoice', 'Export Invoice'). Defaults to 'Debit Note'.
`buyerCountry`	No	YOUR OWN company's country on this debit note's Party Details.
`referenceDate`	No	Date for the reference above, in DD-MM-YYYY format.
`voucherNumber`	No	Explicit voucher number. Normally omit and let Tally auto-number — but some Tally configurations stop auto-numbering item-invoice vouchers via the XML gateway (confirmed live). If creation fails with a blank EXCEPTIONS:1, check get_vouchers for the highest existing number of this voucher type and retry with voucherNumber set to the next one.
`vatRatePercent`	No	Default VAT rate. Required if vatLedger is set.
`placeOfSupplyCountry`	No	UAE VAT Place of Supply Country for this debit note.
`placeOfSupplyEmirate`	No	UAE VAT Place of Supply Emirate for this debit note.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.14.0Nov 6, 2026

addedInput schema / properties / items / items / properties / description

Added value: +{
+  "description": "Description lines shown under this stock line on the invoice, one array entry per line (e.g. a size, colour or service period). Optional.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / voucherType

Added value: +{
+  "description": "Voucher type to post as, for a company that uses its own Debit Note-class type in Item Invoice mode (e.g. 'Tax Invoice', 'Export Invoice'). Defaults to 'Debit Note'.",
+  "type": "string"
+}

Addedv1.11.2Sep 4, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Beyond the annotations (write, non-idempotent, non-destructive), it discloses concrete side effects: returning 3 units decreased book quantity by exactly 3, verified on a live company. It adds failure-mode guidance for auto-numbering via the XML gateway (blank EXCEPTIONS:1, fetch highest number, retry with voucherNumber) and notes differing defaults ('Agst Ref' for billType) plus the buyer/supplier TRN asymmetry — rich context annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and sign convention are front-loaded, then caveats and troubleshooting, with no filler sentences. The density is high and appropriate for an 18-parameter mutation tool, though the 'confirmed live' anecdote could be trimmed to a shorter statement of verified stock behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 18-parameter, nested-items, no-output-schema write tool, the description covers identity, sign convention, defaults, godown constraints, and a documented failure/recovery path. What remains thin is the batch/VAT nuance, but the 100% schema coverage fills those gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the schema carries the baseline, but the description adds meaning beyond it: the flipped debit/credit sign convention, the billType default difference from create_purchase_invoice, godown auto-fill only for single-godown companies, and the voucherNumber workaround. It does not walk through the remaining VAT/place-of-supply fields, which is acceptable given schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Create an item-invoice Debit Note in TallyPrime") and immediately defines it as a purchase return reversing stock and expense. It also explicitly differentiates itself from create_purchase_invoice ("same shape ... but with the debit/credit convention flipped"), and the sibling list contains create_credit_note and create_purchase_invoice against which this distinction matters.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes clear this is the tool for returning purchased items and repeatedly anchors it against create_purchase_invoice, including inherited caveats for godown and deletion. It does not explicitly distinguish when to use this over create_credit_note or update_debit_note, so an agent must infer the boundary, but the usage context is otherwise unambiguous.

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

Deploy Server

create_debit_note

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools