Skip to main content
Glama

Read expenses and payments

expenses_list
Read-onlyIdempotent

List a flat's expenses newest first with splits and cash payments, page by page, to find expense, split, or payment IDs and review history before updates.

Instructions

Lists the flat's expenses, newest first by occurredAt, each with its splits (debtorMemberId, amountCents, settledAt) and the recorded cash payments, one page at a time. Use it to find an expense, split or payment id, to check updatedAt before expense_update, or to review history. For what others owe the caller use balances_get, for the amount to settle between two members use settlement_preview. Read only. The answer carries expenses, payments, total (all expenses) and hasMore; payments are returned in full on every page.

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

Input Schema

NameRequiredDescriptionDefault
limitNoPage size: how many expenses to return.
offsetNoNumber of newest expenses to skip. Use limit plus the previous offset while hasMore is true.
wgCodeNoShare code of the flat (code from wg_list). Leave it out when the account belongs to one flat.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.1.1
    • addedInput schema / properties / limit / description
      Added value: +"Page size: how many expenses to return."
    • addedInput schema / properties / offset / description
      Added value: +"Number of newest expenses to skip. Use limit plus the previous offset while hasMore is true."
  2. First observedv0.1.0

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so 'Read only' is mostly redundant. The description nevertheless adds non-obvious behavior: payments are returned in full on every page (i.e. they are not paginated with the expenses), plus the response envelope and the fact that total covers all expenses rather than the page.

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?

Three sentences, front-loaded with what is returned and in what order, then when to use it, then alternatives and return shape. No filler, and the pagination caveat is placed where it matters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/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 carries the return-value burden and does so by naming expenses, payments, total and hasMore. For a read-only paginated list with fully documented parameters, nothing an agent needs in order to call it correctly is missing.

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 still adds meaning by framing results as 'one page at a time' and tying hasMore to the offset progression, which clarifies the paging contract beyond the per-parameter text. It does not restate limit bounds or the wgCode pattern, which is correct since the schema covers them.

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 ('Lists the flat's expenses'), the ordering ('newest first by occurredAt'), and the nested payload ('splits ... and the recorded cash payments'). An agent can distinguish it from balances_get and settlement_preview 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?

Gives three concrete use cases (find an expense/split/payment id, check updatedAt before expense_update, review history) and two explicit alternatives with the condition that selects each: balances_get for what others owe, settlement_preview for the two-member settle amount.

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