stub

Save income

save_income

Create or update income record(s). 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 update_income_bulk when you only need to recategorise/relink existing income, or create_income_expenses_bulk to add income and expenses together in one transaction.

Input Schema

TableJSON 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).
`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.

First observedSep 7, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations only provide readOnlyHint=false and destructiveHint=false. The description adds meaningful behavior: id presence controls create-vs-update, batch operations are all-or-nothing, and a single ledger recompute occurs. It does not cover partial-update semantics or return value, but it exceeds what annotations alone convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: core behavior first, then batch mode, then transactional guarantee, then sibling alternatives. Every sentence earns its place and there is no 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 tool with no output schema, the description covers the essential mode distinction, transaction semantics, and sibling routing. It is slightly incomplete in not stating the return shape and not explicitly saying whether inline fields and items can be combined, but the rich schema compensates for most parameter-level gaps.

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 100%, so the schema already documents all 22 parameters. The description's id/items semantics are useful but largely duplicate what the items schema description already states, so the description adds little beyond marginal guidance like preferring the batch form.

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 opens with a specific operation, 'Create or update income record(s)', and clearly distinguishes single vs batch modes. It also names sibling tools (update_income_bulk, create_income_expenses_bulk), so an agent can tell exactly what this tool is for.

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?

The description explicitly says when to use inline fields vs an items array, states that items are preferred over repeated calls, and names the exact conditions for choosing update_income_bulk or create_income_expenses_bulk instead. This is unambiguous routing guidance.

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?