Skip to main content
Glama

Taokeh MCP server

Pending draft: match a posted payment to open invoices or bills (human approves in Taokeh)

create_payment_match_draft

FILES A PENDING DRAFT ONLY — NOTHING CHANGES UNTIL A HUMAN REVIEWS AND APPROVES IT IN TAOKEH. Propose how ONE bank line already posted as a customer payment (money in) or a supplier payment (money out) settles open invoices or bills — the owner's "this deposit paid these three invoices". An admin or bookkeeper reviews it and approves; only that tap allocates, exactly as Banking → Match → Save does, and the documents then read as paid. Pass bankTransactionId (a POSTED line from bank_review_queue with status "posted") and allocations: [{saleId, amount}] for money in, [{purchaseId, amount}] for money out, ringgit, adding up to the WHOLE line to the sen (the in-app pane's ±0.10 rounding allowance does not apply to a proposal). At most 50 documents. WHICH DOCUMENTS: only the ones Banking → Match offers this line — the open invoices of the customer the line is posted against (or, when that customer has none open, the invoices of the company's walk-in customer — the one the owner marked on its customer page, else a customer named 'CASH SALES'), or the supplier's open bills. A line with no customer at all is offered nothing. A document of ANY other party is refused, because no screen in Taokeh offers it: if the payment was posted against the wrong customer, or no customer, the owner unposts the line in Banking, sets the right customer, and posts it again — then file this. A refusal lists the documents the line can take, with their ids. ALSO REFUSED BY NAME, at filing and again at approval: a line not posted, not a customer/supplier payment, already matched (a match someone saved is never replaced — that includes a line applied only IN PART: the rest of it is applied in-app, on Banking → Match or Sales → Official receipts → Receive payment, never by this draft), or on a foreign-currency account (Taokeh does not post or match those lines yet); a line whose posted entry booked an exchange difference on a foreign-currency invoice or bill (the owner unposts it in Banking, then matches it and posts it again); a document not open; an amount over what a document still owes; a FOREIGN-currency invoice or bill dated after the payment (it is matched by hand on Banking → Match); an OPENING invoice or bill paid by a line dated on or before the accounting start date (the opening balance already counts that money); a match whose line AND document are both dated on or before the lock date (it would apply inside the locked period, whose books are filed: an admin unlocks in Opening balances → Review & lock, matches, then locks again); the same document twice; a pending match already filed for the line. A ringgit INVOICE or BILL dated after the payment is allowed — a customer's deposit, or an advance paid to a supplier: the money sits on that party's account until the document's date and pays it then, and the review page and this answer (paidBeforeInvoice / paidBeforeBill) say so. If the line or a document changes before approval (paid, credited, re-tagged, matched), approval refuses and nothing is allocated. A payment holding an official receipt (recorded with Receive payment) can only pay that customer's invoices — never the walk-in customer's or anyone else's; to move it, the owner undoes it in Banking and records it again. note: one short line for the owner saying how you know (the remittance, the customer's message). A supplier DEBIT NOTE's credit used as a negative line here is refused when the bank line is dated before the debit note (its credit did not exist yet). And approving a new allocation that takes money OFF a bill is refused while one of that bill's debit notes has credit above what the bill owed that was already refunded or used on another payment — the refusal names the note; that refund or payment is undone first, in Taokeh.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "bankTransactionId": "<bankTransactionId>",
      "allocations": "<allocations>"
    },
    "name": "create_payment_match_draft"
  }
}

Input Schema

NameRequiredDescriptionDefault
noteNoA SHORT note for the owner: how you know which documents it paid.
linesNoNOT a filter on this tool. Pass the documents as `allocations`: [{saleId or purchaseId, amount}].
notesNoNOT a filter on this tool. Pass the owner note as `note`.
bankLineIdNoNOT a filter on this tool. Pass the bank line as `bankTransactionId`.
allocationsYesWhere the money goes. An unknown key is refused by name.
needsReviewNoSet true when something gave you pause.
transactionIdNoNOT a filter on this tool. Pass the bank line as `bankTransactionId`.
bankTransactionIdYesREQUIRED — the posted bank line, from bank_review_queue (status "posted").

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only say it is a non-read-only, non-destructive, non-idempotent write; the description adds the crucial behavioral fact that nothing changes until a human approves in Taokeh, plus approval-time staleness refusal, draft-already-filed refusal, and the fact that a saved match is never replaced. It also discloses permission-free requirements (unpost/re-post workflow) and edge-case economics (debit-note credit ordering, refund interaction). No contradiction with destructiveHint=false.

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 single most important constraint (draft only, human approves) is front-loaded in caps, which is correct. However, the description is a very long unbroken block that mixes core contract, refusal catalogue, and rare edge cases (supplier debit note ordering, refunded credit) — a shorter core plus listed exclusions would read much better.

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

Completeness5/5

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

For a complex, approval-gated matching tool with no output schema, the description covers input contract, eligibility rules, refusal behavior (including that refusals name the candidate documents and their ids), and even the returned `paidBeforeInvoice`/`paidBeforeBill` signals. An agent has essentially everything needed to call it correctly or to explain why it cannot.

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 100%, so the baseline is 3, but the description adds constraints not present in the schema: allocations must sum to the whole line to the sen with no ±0.10 rounding tolerance, at most 50 documents, ringgit only, and the saleId/purchaseId split tied to money direction. It also explains the `note` field's intent (how you know). The `needsReview` parameter is not explained beyond the schema.

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?

The description names a specific verb and resource (files a pending draft that matches one posted bank line to open invoices or bills) and scopes it precisely: money-in via customer payments, money-out via supplier payments. It draws the line against the in-app Banking → Match / Receive payment flows, so an agent can tell this apart from create_payment_draft or create_receipt_draft.

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

Usage Guidelines5/5

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

It gives explicit when-to-use (a posted line that should settle open documents), when-not-to-use with named alternatives (unpost in Banking and re-post if the wrong customer; use Banking → Match or Receive payment for in-app matching; use Opening balances → Review & lock for locked periods). Refusal conditions are enumerated up front rather than left to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources