stub

Save income

save_income

Create or edit income ACCOUNTING ENTRIES (category, client, tax); to change the BANK LINE itself (its description, ignored flag or notes) use update_transaction, and to record a payment against an invoice prefer record_document_payment. When the bank line that paid the invoice already has its own income (its $incomeids in list_transactions), settle by saving that income with id = the income and accountid = the invoice id instead, so the payment is not counted twice. For one, send its fields inline (pass an id to update, omit to create). To create/update many at once, send an items array — preferred over repeated calls: the whole batch is one all-or-nothing transaction with a single ledger recompute. Each item with an id updates; each without creates. Use create_income_expenses_bulk to add income and expenses together in one transaction.

Input Schema

Name	Required	Description
`id`	No	Income id. Present → update that income; omit → create a new one.
`date`	No	Income date (ISO 8601).
`name`	No	Display name / description of the income.
`alert`	No	Alert/reminder note to surface on this income.
`items`	No	Vector of income objects to create/update in one all-or-nothing batch. Preferred over repeated calls. Each item with an id updates; each without creates.
`notes`	No	Free-text notes.
`split`	No	Whether this income is one line of a split transaction.
`amount`	No	Unit amount before quantity/tax, in the record's currency.
`client`	No	Client id, or an exact client name to resolve (see list_clients).
`method`	No	Payment method as free text (e.g. "cash", "card", "eft") — no fixed set.
`unlink`	No	Id of a currently-linked invoice/asset to detach from this income. Ignored unless it is an invoice/asset id.
`assetid`	No	Asset id to link this income to (e.g. proceeds from an asset).
`groupid`	No	Group id linking split lines of one real-world transaction together.
`product`	No	Product id this income is for (see list_products).
`category`	No	Income category name; forced to "Sales" when linked to an invoice.
`currency`	No	ISO 4217 currency code (e.g. "ZAR", "USD"). Defaults to the business currency.
`accountid`	No	Chart-of-accounts income category account id, or an exact account name to resolve (see list_accounts). Set to a supplier id (sup-…) to record a refund paid by that supplier: it posts once to Payables, tagged to the supplier, with no VAT, and draws down the credit they owe.
`invoiceid`	No	Invoice id this income pays toward.
`incometype`	No	Income type/classification label.
`exchangerate`	No	Manual FX rate to the business base currency; omit to use the stored/auto rate.
`baseaccountid`	No	Base/control account id override; rarely needed — defaults from the category.
`transactionid`	No	Bank transaction id to reconcile this income against.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 6, 2026

changedInput schema / properties / accountid / description

Previous value: -"Chart-of-accounts income category account id, or an exact account name to resolve (see list_accounts)."New value: +"Chart-of-accounts income category account id, or an exact account name to resolve (see list_accounts). Set to a supplier id (sup-…) to record a refund paid by that supplier: it posts once to Payables, tagged to the supplier, with no VAT, and draws down the credit they owe."

First observedSep 7, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations only declare that this is a non-read-only, non-destructive write. The description adds real behavior beyond that: the batch is one all-or-nothing transaction with a single ledger recompute, and the double-counting risk when a bank line already holds income. It stops short of stating permission requirements or what is returned/rolled back on failure, so not a 5.

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 purpose and alternatives before the edge-case settlement rule, and every sentence carries operational content. It is dense and backtick-heavy, and the batching guidance is split across two adjacent sentences, but nothing is filler.

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 22-parameter mutation tool with no output schema, the description covers the decisions that actually cause errors (create vs update, bank line vs accounting entry, batch vs loop, duplicate payment). It does not say what the call returns (e.g. created income ids) or how failures surface in a batch, which is the main remaining gap.

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 meaning the schema does not: omit `id` to create vs include it to update, and the non-obvious `accountid` = invoice id settlement pattern (the schema's `accountid` text only covers the supplier-refund case). It also frames `items` as per-item create/update by presence of `id`.

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 and resource ("Create or edit income ACCOUNTING ENTRIES") and immediately scopes what it is not: it does not touch the bank line (update_transaction) or invoice payments (record_document_payment). An agent can distinguish it from save_expense, update_transaction and record_document_payment without opening any 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: use update_transaction for the bank line, record_document_payment for invoice payments, create_income_expenses_bulk to mix income and expenses. It also gives a concrete deduplication rule (settle via `id` = existing income and `accountid` = invoice id when the bank line already carries `$incomeids`) and states that `items` batching is preferred over repeated calls.

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

All stub 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?