# Settle The Tab agent guide

Settle The Tab exposes account-scoped tools for shared expense ledgers. A user creates one active AI API key from Settings and supplies it directly to their agent. Treat that key like a password.

## Connect

- Remote MCP: `https://settlethetab.com/api/v1/ai/mcp`
- OpenAPI: `https://settlethetab.com/api/v1/ai/openapi.json`
- REST base: `https://settlethetab.com/api/v1/ai`
- Authentication: `Authorization: Bearer stt_ai_v1_...`

Never put the key in a URL, prompt transcript, log, analytics event, or tool output. A newly generated key immediately replaces the previous key.

## Tools

- `get_account`: identify the account represented by the key.
- `list_groups`: list accessible groups and obtain group/member IDs.
- `get_group`: read members, expenses, and cash settlements for one accessible group.
- `get_balances`: read derived balances by currency.
- `get_settle_plan`: derive a Simply Settle proposal without changing the ledger.
- `add_expense`: add an equal, exact-amount, percentage, or share-weighted expense, including multiple payers.
- `record_settlement`: record an actual cash repayment.

## Safety and accounting rules

1. Read the group and member IDs before constructing a write. Never guess IDs or match people by name alone.
2. Money is always a base-10 integer string in minor units plus an ISO 4217 currency. USD 12.99 is `"1299"` and `"USD"`.
3. Keep currencies separate. Never silently convert them.
4. Confirm the user's intended payer, participants, amount, currency, and description before adding an expense.
5. A settle plan is only a proposal. Call `record_settlement` only after the user says a payment actually happened.
6. Every write requires a fresh client-generated UUID in `operationId` and an explicit `paidAt` or `settledAt` timestamp. Retry identical content with the same ID and timestamp after an ambiguous failure. Never reuse that ID for different content.
7. Equal, percentage, and weighted-share splits are rounded deterministically by the service. Payer contributions and exact shares must each total the expense amount; percentage inputs use basis points totaling 10,000.
8. A key has exactly the same group access and role restrictions as its owner. A missing group may mean either nonexistent or unauthorized; do not probe.

## Recommended flow

For an expense: `list_groups` -> `get_group` -> confirm intent -> `add_expense` -> report the accepted revision.

For settlement: `list_groups` -> `get_balances` or `get_settle_plan` -> confirm an actual payment -> `record_settlement`.