Skip to main content
Glama

Record an invoice payment

record_payment
Destructive

Use this when the user says a client paid an invoice, fully or in part, and asks to record or mark it as paid. Records a payment the client made against an issued invoice, through the same path as recording it in Fatura Go (accounting journal, paid status). Two steps: without confirmation_token nothing is recorded and the result is a preview (invoice, amount, date, method, account, remaining after) with a confirmation_token valid 10 minutes for one use; call again with the same arguments and the token only after the user answered (a confirmation sent within 10 seconds of the preview is refused). amount must be above 0 and at most the remaining balance; an overpayment is recorded in Fatura Go, not here. Not for a Shopify order's invoice. The date must not be in a closed accounting period. method is one of bank_transfer, cash, cheque, card, other: cash posts to cash on hand, any other or none to the default bank account. A recorded payment can be undone in the app; there is no undo tool. Do not use it for supplier bill payments or refunds: those are recorded in Fatura Go.

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": {
      "amount": "<amount>"
    },
    "name": "record_payment"
  }
}

Input Schema

NameRequiredDescriptionDefault
dateNoYYYY-MM-DD, the day the money was received. Default today (UAE).
amountYesThe amount received, in the invoice currency, above 0, at most 2 decimals.
methodNoOne of bank_transfer, cash, cheque, card, other.
currencyNoOptional check: must be the invoice currency.
referenceNoBank or cheque reference, if the user gave one.
invoice_idNoFrom list_invoices or get_invoice.
business_idNoFrom list_businesses. May be left out: the invoice is then looked up in every business shared with this connection.
invoice_numberNoInstead of invoice_id.
confirmation_tokenNoLeave out on the first call (preview). Pass the token from the preview only after the user confirmed it, with the same other arguments.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Far exceeds the annotations: it discloses that a call without confirmation_token records nothing and returns a preview, that the token is single-use and valid 10 minutes, that a confirmation sent within 10 seconds is refused, that overpayment is rejected rather than clamped, that the date must not fall in a closed accounting period, and that undo exists only in the app, not as a tool. These are exactly the behavioral facts the destructiveHint/idempotentHint flags 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?

Front-loaded with the trigger and the recording path, with exclusions and the two-step protocol following in logical order. It is dense and one sentence chains the token timing plus the 10-second refusal rule, which is slightly hard to scan, but no sentence is filler.

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 9-parameter destructive mutation with no output schema, the description covers the trigger, the preview/confirm flow, monetary limits, date constraints, method posting behavior, and reversibility — everything an agent needs to invoke it correctly and safely. Return-value shape is partially covered by enumerating the preview fields.

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 genuine meaning beyond the schema: amount must not exceed the remaining balance, method values map to concrete posting accounts (cash to cash on hand, everything else to the default bank account), and date is constrained to open accounting periods. It does not add anything for currency, reference, business_id, or invoice_number 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?

States a specific verb and resource ('Records a payment the client made against an issued invoice') and explicitly excludes three adjacent cases: Shopify order invoices, supplier bill payments, and refunds. An agent can distinguish this from prepare_invoice or create_draft_invoice without inspecting other schemas.

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?

Gives an explicit trigger ('when the user says a client paid an invoice, fully or in part, and asks to record or mark it as paid') plus explicit exclusions routed elsewhere ('those are recorded in Fatura Go'). It also spells out the two-call protocol, which is the real usage condition an agent must follow.

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