Skip to main content
Glama

Settle bills

settle_bills
DestructiveIdempotent

Settle a batch of bills in one call (bills only: an invoice's leftover FX or rounding gap is settled with save_document settled true) — each pair links a bill / purchase order / GRN (cont-…) to its payment: either an existing expense (expense) or a bank transaction (transaction: a bank-feed transaction's own unallocated expense is re-pointed at the bill; an unlinked transaction gets a new expense linking the two). Money-out settle = an expense whose accountid is the bill's id. record_document_payment settles ONE bill at a time (minting the expense from payment fields); this tool instead LINKS an existing expense or bank transaction and settles a whole batch, which the chat loop can't do with N single settles. Each pair is applied INDEPENDENTLY: one failing (missing/locked/bad ref) never aborts the rest. Every id (bill, expense, transaction) is owner-scoped; an already-settled bill, or a transaction whose expense already pays that bill, is a safe no-op (not a failure), so re-running the same batch is harmless. A transaction allocated elsewhere (income, another bill or category, several expenses) fails with a reason naming the allocation. A bank transaction slightly ABOVE the bill (a bank fee, at most 3% of the outstanding, same currency) is not refused: it comes back status "proposed" with a proposal {type bank-charge, amount, accountid 201, accountname Bank Charges, outstanding, paid} and NOTHING is written. Show the user the fee; only once they confirm, re-send the same pair with bankcharge = proposal.amount to settle the bill and post the fee to Bank Charges in one transaction (re-sending again is an already-settled no-op). Above 3% the over-settle refusal stands. A bank transaction in a DIFFERENT currency from the bill, worth within 3% of the outstanding at its date's rate, comes back status "proposed" with a proposal {type fx-gain|fx-loss, amount, currency, accountid, accountname, outstanding, paid, paidcurrency, paidbase, exchangerate; for a bill in a foreign currency also billcurrency, carrying (the bill's base value), paidbill} and NOTHING is written. Show the user the FX line; only once they confirm, re-send the same pair with fxadjustment = proposal.amount to settle the bill and post the difference to the Foreign Exchange account (when the business has autofxadjustment on, it is booked without asking). A bill in a foreign currency paid from a bank line in that same currency settles at once and books the rate move since the bill date to Foreign Exchange (fxadjustment, autobooked); with no dated rate it settles with no FX line and fxunsized true. Any other currency mismatch (an expense pair, no dated rate, outside 3%, a partial payment in another currency) is refused with status "failed", code "cross-currency-needs-fx", billcurrency and paymentcurrency, and NOTHING is written. Returns {results [{bill, status "settled"|"already-settled"|"proposed"|"failed", expenseid, created, bankchargeid, fxadjustmentid, fxadjustment, proposal, reason}], settled, already-settled, proposed, failed} — expenseid is the undo handle and created=false means the expense pre-existed (undo by UNLINKING it, never deleting); bankchargeid is the minted fee expense (safe to delete); fxadjustmentid is removed automatically when its expenseid is unlinked from the bill or deleted, so do NOT delete it separately (restoring a deleted expense does not bring its FX line back). Max 100 pairs per call. Only run after the user has confirmed the proposed matches.

Input Schema

NameRequiredDescriptionDefault
pairsYesThe confirmed bill↔payment pairs to reconcile. Each is applied independently.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / pairs / items / properties / fxadjustment
      Added value: +{
      +  "description": "Confirms a proposed FX gain/loss line (:transaction case). A bank payment in another currency from a base-currency bill, worth within 3% of the outstanding at the payment date's rate, comes back \"proposed\" with the FX line and writes nothing. Re-send the pair with fxadjustment = that proposal's amount, only after the user confirms, to settle the bill and post the difference to the Foreign Exchange account.",
      +  "type": "number"
      +}
  2. Changed1 schema field changed
    • addedInput schema / properties / pairs / items / properties / bankcharge
      Added value: +{
      +  "description": "Confirms a proposed bank-charges line (:transaction case). A payment above the bill by at most 3% of its outstanding comes back \"proposed\" with the fee and writes nothing. Re-send the pair with bankcharge = that proposal's amount, only after the user confirms, to settle the bill and post the fee to Bank Charges.",
      +  "type": "number"
      +}
  3. Changed1 schema field changed
    • changedInput schema / properties / pairs / items / properties / transaction / description
      Previous value: -"A bank transaction id to settle the bill from — a new expense is created linking the transaction to the bill. Provide this OR :expense, not both."New value: +"A bank transaction id to settle the bill from. A bank-feed transaction's own unallocated expense is re-pointed at the bill; an unlinked transaction gets a new expense linking it to the bill. Provide this OR :expense, not both."
  4. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Far exceeds the annotations (which only say non-readonly, idempotent, destructive). The description discloses that pairs apply independently and one failure never aborts the batch, that already-settled bills are safe no-ops, that proposals write NOTHING, the 3% bank-fee threshold, the cross-currency failure code, and precise undo semantics (unlink the expense, never delete; bankchargeid is safe to delete; fxadjustmentid is auto-removed).

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 purpose and the single-vs-batch contrast are front-loaded, but the body is a dense wall of nested parentheticals and em-dash clauses that is hard to scan; the FX and bank-charge rules are buried in one long paragraph. Almost every sentence carries information, so this is over-density rather than padding.

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?

Complete for a complex, destructive, batch-mutating tool with no output schema: it documents the full return shape (results array with statuses, expenseid, created, bankchargeid, fxadjustmentid, proposal, reason), aggregate counts, and the failure taxonomy including cross-currency-needs-fx.

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 real semantics beyond the schema: what `bankcharge` and `fxadjustment` mean as confirmation echoes of a returned proposal, and the exclusivity of `expense` vs `transaction` with different write paths for each. Some of this overlaps the schema text, which keeps it off a 5.

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 ('Settle a batch of bills in one call') and immediately narrows scope ('bills only'), naming the sibling path for the invoice case (save_document settled true) and contrasting with record_document_payment. An agent can distinguish this from every nearby tool without opening a schema.

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?

Explicit routing rules: use record_document_payment for one bill at a time, use save_document for an invoice's FX/rounding gap, and only run this after the user confirms the proposed matches. It also states the batch-size ceiling (max 100 pairs) and the confirmation-only re-send protocol.

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