goodwill-mcp

Add an expense

add_expense

Add a shared expense to a group and preview balance changes before confirming. Detects duplicates and splits costs equally among participants.

Instructions

Add a shared expense to a group from a sentence ("dinner 84, I paid, split with everyone") or from explicit fields. Step 1 returns a preview naming everyone whose balance changes and asks for confirmation. Nothing is posted until the user confirms. Checks for likely duplicates first. Equal split only in this version; give participants to limit who shares it.

Input Schema

TableJSON Schema

Name	Required	Description
`cost`	No	Decimal string like "84.00". Overrides text.
`date`	No	YYYY-MM-DD. Defaults to today.
`text`	No	A sentence like "taxi 16 paid by Sam split with me and Sam".
`payer`	No	"me" or a member name or id. Defaults to me.
`currency`	No	ISO code. Defaults to your Splitwise default currency.
`group_id`	Yes	Group to post into. See splitwise://groups.
`category_id`	No	From splitwise://categories.
`description`	No	Overrides the description parsed from text.
`participants`	No	Member names or ids who share the cost. Defaults to everyone in the group.
`idempotency_key`	No	Repeat the same key to retry safely without a second post.

Output Schema

TableJSON Schema

Name	Required	Description
`cost`	No	Decimal amount as a string, two places, e.g. "84.00"
`note`	Yes
`posted`	Yes
`affected`	No
`currency`	No
`group_id`	Yes
`expense_id`	No
`description`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 20, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Adds significant behavioral context beyond the annotations: the two-step preview/confirmation flow, 'Nothing is posted until the user confirms,' duplicate checking, and the equal-split-only restriction. This gives an agent accurate expectations about side effects and user interaction.

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 front-loaded with the main purpose and each subsequent sentence adds a distinct behavioral constraint: input modes, preview, confirmation, duplicate check, and equal-split limitation. No filler or redundant detail.

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 10-parameter tool with an output schema, this description covers the essential workflow and constraints well. Minor gaps remain: it does not state what happens when a duplicate is detected or explicitly route itemized splits to split_by_items, but these are not blockers for correct invocation.

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?

The schema already documents all parameters with 100% coverage, so the baseline is 3. The description's example and 'give participants to limit who shares it' reinforce text and participants meaning but do not add substantive semantics beyond the schema.

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?

Directly states the verb and resource: 'Add a shared expense to a group.' It also specifies the two input modes (sentence or explicit fields) and the equal-split constraint, making it clearly distinct from the sibling query/settlement tools.

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?

Clearly describes how to use the tool: provide a sentence or explicit fields, and include participants to limit the split. It states the equal-split limitation, which implies when not to use it, but it does not explicitly name alternatives such as split_by_items for itemized expenses.

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

Deploy Server