Sivella

Record an expense

record_expense

Record one expense or income entry in a ledger. Commits immediately. amount_cents is MINOR units (cents): pass 2500 for 25.00, never a decimal. The returned amount is in currency units (e.g. "25.00"). To attribute the source of money, pass expense_account_id (the numeric id from list_expense_accounts) — do NOT stuff the account into description, and do NOT pass a name. When omitted, the ledger's default account (if any) is applied.

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": {
      "ledger_id": "<ledger_id>",
      "category": "<category>",
      "amount_cents": "<amount_cents>"
    },
    "name": "record_expense"
  }
}

Input Schema

Name	Required	Description
`date`	No	Entry date as ISO YYYY-MM-DD. Defaults to today if omitted; resolve relative dates yourself.
`category`	Yes	Category slug or name. Call list_budget_categories first if unsure.
`direction`	No
`ledger_id`	Yes
`description`	No
`amount_cents`	Yes	Amount in minor units (cents). 2500 = 25.00.
`expense_account_id`	No	Optional source-of-money account id from list_expense_accounts. Omit to use the ledger's default.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 10, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds the materially important facts that the write commits immediately with no confirmation step, and that the input unit (minor/cents) differs from the returned unit (currency units). The unit asymmetry is exactly the kind of trap that annotations cannot express. It does not describe error behavior or what happens on a failed write, keeping it below 5.

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?

Four dense sentences with the mutation and unit contract front-loaded, then the account-attribution rule, then the fallback. Zero filler and no restatement of the title or of schema fields already documented.

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 7-parameter write with no output schema, it covers the highest-risk facts: immediate commit, unit conventions on both sides of the call, and correct account attribution. Gaps are the unmentioned direction enum (debit/credit default) and ledger_id semantics, both of which the agent must infer from the schema alone.

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?

With 57% schema coverage, the description compensates on the two genuinely ambiguous parameters: amount_cents is spelled out as minor units with a worked example ('2500 for 25.00, never a decimal'), and expense_account_id is given source-of-money meaning, its provenance (list_expense_accounts), and its default-when-omitted behavior. It also warns against misusing the description parameter. ledger_id, category, date and direction are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Record one expense or income entry in a ledger.' The scope ('one ... entry') and the 'income' half make the tool's domain unambiguous. It stops short of naming a sibling it is not (e.g. add_upcoming_expense for planned entries), so it is clear but not sibling-differentiated.

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 usable routing guidance: 'pass the numeric id from list_expense_accounts', 'do NOT stuff the account into description, and do NOT pass a name', plus the default-account fallback when omitted. 'Commits immediately' implicitly frames this as the immediate-entry tool rather than a planned one. No explicit when-not/exclusion statement against a named alternative, so not a 5.

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

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