Simpler.Asia

invoice_payment_record

Records a money-in fact row against an invoice (by invoice_id or its invoice_number) in ONE call: money is integer CENTS via amount_cents, or a decimal STRING via amount — never multiply or divide yourself. A draft invoice auto-advances to 'sent'; a cancelled invoice refuses; an amount above the remaining balance refuses unless allow_overpayment is true. status 'paid' derives from the ledger this writes, so this is how an invoice becomes paid. A same invoice/amount/day repeat refuses as a likely duplicate unless resent with force:true. NEXT: invoice_read to read it back.

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": "invoice_payment_record"
  }
}

Input Schema

Name	Required	Description
`note`	No
`force`	No	Confirms a genuine second payment when the same invoice/amount/day already has one recorded (default false refuses it as a likely duplicate) — resend the SAME call with force:true.
`amount`	No	Money as a decimal STRING ("1500.00" = $1,500.00), parsed server-side. Use amount_cents for integer CENTS instead — never convert units yourself.
`method`	No
`currency`	No
`invoice_id`	No
`occurred_at`	No
`amount_cents`	No
`invoice_number`	No	Alias of invoice_id — the invoice's own number (tenant-unique), resolved server-side.
`allow_overpayment`	No	Explicit override (default false): record more than the remaining balance / pay an already-settled invoice.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 23, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Goes well beyond the annotations: it states the draft→'sent' auto-advance, the refusal on cancelled invoices, the overpayment guard and its override flag, the duplicate-detection behavior with force:true, and the derived 'paid' status. These are exactly the side effects an agent cannot infer from readOnlyHint/destructiveHint/idempotentHint alone.

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?

The critical behavior (unit convention, refusal conditions, duplicate handling) is front-loaded and the 'NEXT:' pointer is a clean closing cue. It is dense with semicolon-chained clauses, but nearly every clause carries operational information.

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 10-param mutation with no output schema, the description covers the important decisions and defers read-back to invoice_read. It leaves defaults for method, currency, and occurred_at unexplained, and the empty required array means the agent must infer that an invoice identifier and an amount are in practice mandatory.

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 40%, and the description does add real meaning for the highest-risk params: amount_cents is integer cents vs amount is a decimal string with 'never convert units yourself', plus force and allow_overpayment override semantics. However, method, currency, occurred_at, and note are left with no explanation in either place, so the compensation is partial rather than full.

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?

Specific verb+resource: 'Records a money-in fact row against an invoice', with the variant paths (invoice_id or invoice_number) spelled out. It also distinguishes itself from adjustment/debit-note style siblings by framing the operation as a money-in fact row and by noting that status 'paid' derives from this ledger.

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 concrete use conditions and exclusions: a cancelled invoice refuses, an overbalance refuses without allow_overpayment, a same-day repeat refuses without force, and a NEXT step pointing to invoice_read. It never names a competing sibling (e.g. invoice_adjustment_record) as the alternative for non-payment ledger entries, so it stops short of full routing guidance.

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

All Simpler.Asia 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.

Resources

Need Help?