Skip to main content
Glama
PNPC-MCP-Tally-Prime

PNPC-MCP-Tally-Prime

create_purchase_invoice

Creates an item-invoice Purchase voucher in TallyPrime, posting stock item lines to purchase ledgers with quantity, rate, and optional VAT/tax details.

Instructions

Create an item-invoice Purchase voucher in TallyPrime — mirror of create_sales_invoice for the buying side. A real invoice with stock item lines (quantity, rate), each posted to its own Purchase ledger, plus one optional VAT/tax line on the total. WARNING (confirmed live, same as create_sales_invoice): if the same party ledger or stock item is used in BOTH a Sales and a Purchase item-invoice, it can become undeletable via the API afterward — using it in only one of the two is fine and stays deletable. If it does happen, running Company Data → Rewrite in Tally itself clears it (confirmed live) — this is not a permanent lock.

Input Schema

NameRequiredDescriptionDefault
dateYesInvoice date in DD-MM-YYYY format
itemsYesOne entry per invoice line.
billNameNoBill reference name for bill-wise tracking (requires the party ledger's maintainBillWise to be on). Omit if not using bill-wise tracking.
billTypeNoDefaults to 'New Ref'.
buyerTrnNoYOUR OWN company's TRN, as it should appear on this purchase invoice (Tally's BASICBUYERSSALESTAXNO field) — you are the buyer on a purchase. Check get_company_info or an existing purchase invoice for the correct value; this is normally constant across all purchase invoices for one company.
narrationNoNarration / description for the invoice
referenceNoFree-text reference for this invoice (Tally's voucher-level REFERENCE field) — typically the supplier's own bill/invoice number.
vatLedgerNoDefault Input VAT ledger applied to any item that doesn't set its own vatLedger (optional — omit for a fully non-taxable invoice).
buyerStateNoYOUR OWN company's Emirate/state on this invoice's Party Details (voucher-level STATENAME) — you are the buyer on a purchase. Normally constant; check get_company_info.
partyLedgerYesSupplier ledger name (the party being paid)
supplierTrnNoThe supplier's (party's) TRN as it should appear on THIS invoice — Tally's TRADERCONSVATTINNO field. NOTE the asymmetry vs create_sales_invoice: on a purchase, the party is the supplier, not the buyer, so this is a distinct field from buyerTrn below (they held different real values in a reverse-engineered example — do not set them to the same value).
voucherTypeNoVoucher type to post as, for a company that uses its own Purchase-class type in Item Invoice mode (e.g. 'Tax Invoice', 'Export Invoice'). Defaults to 'Purchase'.
buyerCountryNoYOUR OWN company's country on this invoice's Party Details (voucher-level COUNTRYOFRESIDENCE). Normally constant; check get_company_info.
referenceDateNoDate for the reference above, in DD-MM-YYYY format. Independent of the invoice's own date.
voucherNumberNoExplicit voucher number. Normally omit this and let Tally auto-number — but some Tally configurations (confirmed live: after a Company Data → Rewrite in at least one case) stop auto-numbering item-invoice vouchers via the XML gateway and fail with a blank EXCEPTIONS:1/no error text unless a number is given explicitly. If a create call fails with no error text, check get_vouchers for the highest existing number of this voucher type and retry with voucherNumber set to the next one.
vatRatePercentNoDefault VAT rate as a percentage, e.g. 5. Required if vatLedger is set. Items with mixed rates can override this per-line.
placeOfSupplyCountryNoUAE VAT Place of Supply Country (Tally's PLACEOFSUPPLYCOUNTRY field), e.g. 'UAE'.
placeOfSupplyEmirateNoUAE VAT Place of Supply Emirate for this invoice (Tally's EMIRATEPOS field).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.14.0
    • 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 Purchase-class type in Item Invoice mode (e.g. 'Tax Invoice', 'Export Invoice'). Defaults to 'Purchase'.",
      +  "type": "string"
      +}
  2. Changed15 schema fields changedv1.11.2
    • addedInput schema / properties / buyerCountry
      Added value: +{
      +  "description": "YOUR OWN company's country on this invoice's Party Details (voucher-level COUNTRYOFRESIDENCE). Normally constant; check get_company_info.",
      +  "type": "string"
      +}
    • addedInput schema / properties / buyerState
      Added value: +{
      +  "description": "YOUR OWN company's Emirate/state on this invoice's Party Details (voucher-level STATENAME) — you are the buyer on a purchase. Normally constant; check get_company_info.",
      +  "type": "string"
      +}
    • addedInput schema / properties / buyerTrn
      Added value: +{
      +  "description": "YOUR OWN company's TRN, as it should appear on this purchase invoice (Tally's BASICBUYERSSALESTAXNO field) — you are the buyer on a purchase. Check get_company_info or an existing purchase invoice for the correct value; this is normally constant across all purchase invoices for one company.",
      +  "type": "string"
      +}
    • addedInput schema / properties / items / items / properties / batchName
      Added value: +{
      +  "description": "Real batch/lot number for this line, if the item has batch tracking. Defaults to 'Primary Batch'.",
      +  "type": "string"
      +}
    • addedInput schema / properties / items / items / properties / discountPercent
      Added value: +{
      +  "description": "Discount percentage applied to this line's amount (e.g. 10 for 10% off). Optional.",
      +  "type": "number"
      +}
    • addedInput schema / properties / items / items / properties / vatLedger
      Added value: +{
      +  "description": "Per-item VAT ledger override, if this line has a different tax rate than the invoice default. Requires vatRatePercent.",
      +  "type": "string"
      +}
    • addedInput schema / properties / items / items / properties / vatRatePercent
      Added value: +{
      +  "description": "Per-item VAT rate override, e.g. 5. Required if this item's vatLedger is set.",
      +  "type": "number"
      +}
    • addedInput schema / properties / placeOfSupplyCountry
      Added value: +{
      +  "description": "UAE VAT Place of Supply Country (Tally's PLACEOFSUPPLYCOUNTRY field), e.g. 'UAE'.",
      +  "type": "string"
      +}
    • addedInput schema / properties / placeOfSupplyEmirate
      Added value: +{
      +  "description": "UAE VAT Place of Supply Emirate for this invoice (Tally's EMIRATEPOS field).",
      +  "type": "string"
      +}
    • addedInput schema / properties / reference
      Added value: +{
      +  "description": "Free-text reference for this invoice (Tally's voucher-level REFERENCE field) — typically the supplier's own bill/invoice number.",
      +  "type": "string"
      +}
    • addedInput schema / properties / referenceDate
      Added value: +{
      +  "description": "Date for the reference above, in DD-MM-YYYY format. Independent of the invoice's own date.",
      +  "type": "string"
      +}
    • addedInput schema / properties / supplierTrn
      Added value: +{
      +  "description": "The supplier's (party's) TRN as it should appear on THIS invoice — Tally's TRADERCONSVATTINNO field. NOTE the asymmetry vs create_sales_invoice: on a purchase, the party is the supplier, not the buyer, so this is a distinct field from buyerTrn below (they held different real values in a reverse-engineered example — do not set them to the same value).",
      +  "type": "string"
      +}
    • changedInput schema / properties / vatLedger / description
      Previous value: -"Input VAT/tax ledger to apply against the invoice total (optional — omit for a non-taxable invoice)."New value: +"Default Input VAT ledger applied to any item that doesn't set its own vatLedger (optional — omit for a fully non-taxable invoice)."
    • changedInput schema / properties / vatRatePercent / description
      Previous value: -"VAT rate as a percentage, e.g. 5. Required if vatLedger is set."New value: +"Default VAT rate as a percentage, e.g. 5. Required if vatLedger is set. Items with mixed rates can override this per-line."
    • addedInput schema / properties / voucherNumber
      Added value: +{
      +  "description": "Explicit voucher number. Normally omit this and let Tally auto-number — but some Tally configurations (confirmed live: after a Company Data → Rewrite in at least one case) stop auto-numbering item-invoice vouchers via the XML gateway and fail with a blank EXCEPTIONS:1/no error text unless a number is given explicitly. If a create call fails with no error text, check get_vouchers for the highest existing number of this voucher type and retry with voucherNumber set to the next one.",
      +  "type": "string"
      +}
  3. Addedv1.0.4

TDQS

A4.3/5.0
Behavior5/5

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

Annotations only declare the generic profile (not read-only, not destructive, not idempotent, closed-world). The description goes well beyond that with a confirmed live warning about party/stock-item ledgers becoming undeletable when shared across Sales and Purchase item-invoices, including the exact remediation path (Company Data → Rewrite) and the reassurance it is not a permanent lock. It also discloses a second real failure mode — silent CREATED:0/EXCEPTIONS:1 with no error text — and its workaround, which no annotation conveys.

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?

Four sentences, front-loaded with the identity of the tool, then the risk warning, then the recovery step. Every sentence adds information, though the warning passage is dense and repeated detail ("confirmed live") across the warning and the sibling reference could be trimmed slightly.

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 a 3-required/18-total parameter mutation tool with no output schema, the description covers purpose, the key hazard, and the recovery paths well. It does not say what a successful call returns (voucher number, created count), which is the one thing an agent must guess at when there is no output schema.

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

Parameters3/5

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

Schema description coverage is 100%, so every one of the 18 parameters is already documented in the input schema, including the buyerTrn/supplierTrn asymmetry. The prose in the description adds little parameter-level meaning beyond the schema; its only addition is the summary that VAT is a single optional line on the total. Baseline 3 is appropriate when the schema carries this much weight.

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 Purchase voucher in TallyPrime"), then disambiguates from the sibling create_sales_invoice ("mirror of ... for the buying side"). It further narrows scope by describing the voucher shape (stock item lines with quantity and rate, per-line Purchase ledger, one optional VAT line), which separates it from generic create_voucher and from create_purchase_order.

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?

Gives clear routing context — it is the buying-side counterpart of create_sales_invoice — and repeatedly points the agent at prerequisite lookups (get_company_info, an existing purchase invoice, get_vouchers) before filling risky fields. It does not explicitly state when to prefer this over create_voucher or create_purchase_order, so the sibling arbitration is only partially covered.

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

Deploy Server

Other Tools