Payment Reconciliation & Matching

payment_reconciliation

Read-only

Match payments to invoices and reconcile the bank. Send receipts (id, date, amount or credit/debit, narration, payer name, reference) with open_items (invoice no, party code and name, date, amount or balance, taxable value; credit notes allowed); and/or bank_lines with ledger_entries; and/or gstr2b_rows with purchase_register (GSTIN, invoice no, date, taxable, IGST/CGST/SGST/cess). Returns proposed matches with confidence and reasons: party found by code, learned alias, invoice number in the narration or Jaro-Winkler / abbreviation name matching; exact and reference matches settled by Hungarian assignment so no invoice is used twice; combinations by subset-sum over paise; TDS and bank charge deductions; part payments; short payments as disputes; overpayments and unidentified receipts as exceptions; bank one-to-one, batch and split matches, charges / interest not in books, timing items and the reconciliation statement; GSTR-2B matched / amount, date or GSTIN mismatch / probable / missing in books / missing in 2B with ITC at risk by supplier; report with ageing; updated rules_snapshot. Never posts. Not for invoice creation, payment-timing or tax advice. Up to 5,000 receipts / bank lines; larger: payment_reconciliation_get_engine.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "payment_reconciliation"
  }
}

Input Schema

Name	Required	Description	Default
`side`	No		receivable
`as_of`	No	Report date YYYY-MM-DD for ageing.
`currency`	No		INR
`receipts`	No	Receipts or payments: id, date, amount (or credit / debit), narration, payer name, reference, party code (optional).
`max_items`	No
`bank_lines`	No	Bank statement: date, amount or deposits / withdrawals, narration, cheque / UTR.
`max_listed`	No
`open_items`	No	Open invoices or bills: invoice no, party code, party name, date, amount or balance, taxable value, type (credit note).
`gstr2b_rows`	No	GSTR-2B: supplier GSTIN, invoice no, date, taxable value, IGST, CGST, SGST, cess, ITC availability.
`auto_threshold`	No
`ledger_entries`	No	Bank ledger in the books: voucher no, date, debit / credit or signed amount, narration, cheque no.
`max_candidates`	No
`max_charge_pct`	No
`name_threshold`	No
`rules_snapshot`	No	rules_snapshot from an earlier run: aliases, tds_rates, tolerances.
`currency_symbol`	No
`max_bank_charge`	No	Largest bank charge (default 500).
`amount_tolerance`	No	Rounding tolerance (default 1.00).
`date_window_days`	No
`confirmed_matches`	No	Matches the user confirmed or corrected: payer_name or narration, party_ref, party_name, receipt_amount, invoice_total, taxable_total.
`default_tds_rates`	No	TDS rates to try (default 1%, 2%, 10%).
`purchase_register`	No	Purchase register with the same columns as GSTR-2B.
`short_payment_pct`	No
`bank_closing_balance`	No
`book_closing_balance`	No
`gst_amount_tolerance`	No
`max_invoice_age_days`	No
`bank_date_window_days`	No
`gst_date_tolerance_days`	No

Output Schema

Name	Required	Description
`gst`	No
`bank`	No
`alerts`	No
`status`	Yes	1 = ok, 0 = nothing could be matched
`message`	No
`metadata`	Yes
`receipts`	No
`decisions`	Yes	Plain-language cards, priority order. Relay these first.
`assumptions`	No
`rules_snapshot`	No
`data_quality_report`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 30, 2026

TDQS

A4.1/5.0

Behavior5/5

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

Annotations already cover the safety profile (readOnlyHint/destructiveHint=false), and the description goes well beyond them: 'Never posts', it enumerates the matching strategies (party code, learned alias, invoice-in-narration, Jaro-Winkler/abbreviation, Hungarian assignment, subset-sum over paise), how deductions and short payments are classified (disputes, exceptions), and that a `rules_snapshot` is updated, implying state carried between runs. That is exactly the non-obvious behavior an agent needs before trusting the output.

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

Conciseness3/5

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

The lead sentence is correctly front-loaded and there is no filler, but everything after it is one ~180-word semicolon-chained run-on with a deeply nested parenthetical column list. It is information-dense yet hard to scan, so an agent must parse a wall of text to extract the routing rules and input contracts.

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?

Given 29 optional parameters, no required fields, and an output schema that already covers return values, the description supplies the missing behavioral contract (what gets matched, what becomes an exception, that nothing is posted) and a hard size limit. It leaves gaps on receivable-vs-payable semantics and on how the tuning parameters interact, but the core picture is complete enough to invoke correctly.

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

Parameters2/5

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

With 29 parameters at 41% schema description coverage, the description must compensate, but it only restates the column lists for the array inputs (receipts, open_items, bank_lines, gstr2b_rows, purchase_register) — content the schema already documents. The high-impact knobs are untouched: `side` (receivable vs. payable), `auto_threshold`, `name_threshold`, `max_candidates`, `short_payment_pct`, `date_window_days`, `bank_date_window_days`, `max_charge_pct`, and the closing-balance pair are never mentioned, so an agent cannot tell which lever changes matching strictness.

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?

Opens with a specific verb+resource pair — 'Match payments to invoices and reconcile the bank' — that any agent can map to its task, then names the exact domain objects (receipts, open_items, bank_lines, gstr2b_rows, purchase_register). It explicitly rules out adjacency ('Not for invoice creation, payment-timing or tax advice') and names the sibling `payment_reconciliation_get_engine` as the escape hatch, so it is distinguishable without opening either schema.

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 guidance: use this tool up to 5,000 receipts/bank lines, otherwise go to `payment_reconciliation_get_engine`, and it lists the valid input combinations ('and/or bank_lines with ledger_entries; and/or gstr2b_rows with purchase_register'), which is real decision guidance. Negative scope is stated explicitly. It stops short of saying which combination to choose for which business scenario (e.g. pure AR matching vs. GST ITC reconciliation), which keeps it off a 5.

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

All Payment Reconciliation & Matching tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.