Skip to main content
Glama

Mark a split as settled

expense_split_settle

Mark a single debtor's share of an expense as settled after cash repayment, or reopen it if marked by mistake; the expense itself remains unchanged.

Instructions

Marks one debtor share of an expense as settled (the person paid it back in cash), or reopens it with settled false; the expense itself stays unchanged. Use it for a single share; to settle several shares between two members use settlement_preview then settlement_commit, to settle the whole net debt use cash_payment_record. Only the debtor or the payer of that expense may call it (otherwise not_split_party). Settling is refused with 409 split_already_offset when the share is larger than what the debtor still owes net, and split_not_found when the split id does not belong to the expense. Settling notifies the other party; reopening does not. The answer holds the split.

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": {
      "id": "<id>",
      "splitId": "<splitId>"
    },
    "name": "expense_split_settle"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesId of the expense the split belongs to, from expenses_list.
wgCodeNoShare code of the flat (code from wg_list). Leave it out when the account belongs to one flat.
settledNotrue marks the share as paid back; false reopens a share that was settled by mistake.
splitIdYesId of the split to change, from the splits of that expense in expenses_list.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.1.1
    • addedInput schema / properties / id / description
      Added value: +"Id of the expense the split belongs to, from expenses_list."
    • addedInput schema / properties / settled / description
      Added value: +"true marks the share as paid back; false reopens a share that was settled by mistake."
    • addedInput schema / properties / splitId / description
      Added value: +"Id of the split to change, from the splits of that expense in expenses_list."
  2. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Goes well beyond the annotations: annotations only say it is not read-only, not idempotent, and not destructive, while the description discloses that the expense itself is unchanged, that settling fires a notification to the other party while reopening does not, and which error codes guard the operation. This is exactly the context an agent needs to predict side effects and handle failures.

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?

Effect is front-loaded in the first clause, then alternatives, then permissions and errors, then side effects — a sensible information hierarchy. It is a single dense paragraph, but nearly every sentence carries distinct routing or behavioral 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?

With no output schema the description still indicates the response ('The answer holds the split'), and all four parameters plus the failure modes are covered. The only remaining gap is a fuller description of the returned split's fields, which is minor for a single-object mutation.

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; the description earns extra by tying settled=false to the 'settled by mistake' recovery case and by making clear the split id must belong to the given expense id, reinforcing parameter relationships rather than just repeating field text.

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 ('Marks one debtor share of an expense as settled') plus the inverse operation via settled=false, and explicitly scopes it to a single share versus the sibling tools settlement_preview/settlement_commit and cash_payment_record.

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 explicit routing rules: use this for a single share, use settlement_preview then settlement_commit for several shares between two members, and cash_payment_record for the whole net debt. It also states the authorization constraint (only debtor or payer) and the failure conditions (not_split_party, 409 split_already_offset, split_not_found).

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