> ## Documentation Index
> Fetch the complete documentation index at: https://breadbox-mintlify-7401d007.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP conventions

> Amount sign, compact IDs, cursor pagination, sessions, compound ops, and error shape — the cross-cutting rules every Breadbox MCP tool follows.

Every tool in the reference follows the same handful of conventions. Reading this page once saves repeating them forty times.

## Amounts

Breadbox uses the Plaid sign convention. It applies everywhere — REST, MCP, and the admin UI.

* **Positive amount** — money leaving the account (debits, purchases, fees, payments out).
* **Negative amount** — money entering the account (credits, deposits, refunds, transfers in).

A grocery charge of $42.50 appears as `42.50`. A direct deposit of $2,500 appears as `-2500.00`.

Every amount field ships with an `iso_currency_code` sibling (`"USD"`, `"EUR"`, etc.). Agents summing amounts must filter to one currency first — the server does not convert between them.

## Compact IDs

Entity IDs returned by MCP tools are 8-character base62 strings:

```text theme={null}
k7Xm9pQ2
Wm5kTrU9
```

Behind the scenes every row has both a full UUID and a short ID. The MCP response pipeline walks the JSON, replaces every `id` with the sibling `short_id` value, and drops the `short_id` field to save tokens. The REST API returns both unchanged.

Tool inputs accept either form. `transaction_id: "k7Xm9pQ2"` and `transaction_id: "a1b2c3d4-..."` resolve to the same row.

## Dates and date ranges

* All dates are `YYYY-MM-DD` strings. No timezones — dates align with how the institution posted the transaction.
* Where a tool takes `start_date` and `end_date`, `start_date` is inclusive and `end_date` is exclusive. January 2025 in full is `start_date=2025-01-01&end_date=2025-02-01`.
* Some tools have sensible defaults — `transaction_summary` defaults to the last 30 days; `merchant_summary` defaults to the last 90 days. See the tool's reference page.

## Cursor pagination

Tools that return lists (`query_transactions`, `list_transaction_rules`) use opaque cursor pagination:

```json theme={null}
{
  "data": [ ... ],
  "next_cursor": "eyJkYXRlIjoiMjAyNS0wMS0yNSIsImlkIjoiV201a1RyVTkifQ",
  "has_more": true
}
```

When `has_more` is `true`, pass the returned `next_cursor` on the next call to get the next page. When it's `false`, `next_cursor` is `null` and there's nothing more to fetch.

Cursors are bound to the query shape — changing filters mid-pagination will produce meaningless results. Start a new query if you need to change filters.

## Sessions

Sessions are **automatic** — Breadbox creates and binds one to every transport connection. There is no `create_session` tool and no `session_id` or `reason` field in any tool's input schema. The MCP admin dashboard shows call history grouped by session.

To add an audit label to an individual call, pass an optional `reason` string in the `_meta` block alongside the tool arguments:

```json theme={null}
{
  "transaction_id": "k7Xm9pQ2",
  "category_slug": "food_and_drink_groceries",
  "_meta": { "reason": "categorizing clearly valid grocery charge" }
}
```

`_meta.reason` is optional and informational only — the server never rejects a call for omitting it.

## Compound operations

`update_transactions` is Breadbox's preferred write primitive. One call carries up to 50 per-transaction operations, and each operation is a bundle: set a category, add tags, remove tags, and attach a comment — all in one atomic database transaction per row. Every change lands as a single linked annotation in the activity timeline.

Each operation in the batch is atomic — category, tags, and comment land together or not at all. Compound ops:

* Write one linked annotation per transaction (covering the whole edit, not one per change).
* Round-trip once for up to 50 transactions.
* Give you per-row success/failure accounting in the response.

The tool details are on [Transaction writes](/mcp/reference/transactions-write).

<Note>
  If you're only doing one thing to one transaction — and the change is a category set with no accompanying tag or comment — passing a single-element `operations` array to `update_transactions` is still the right call. It writes one linked annotation, one round-trip.
</Note>

## Error shape

Tool errors come back as an MCP call result with `isError: true` and a text content block carrying JSON:

```json theme={null}
{ "error": "operation failed: transaction k7Xm9pQ2 not found" }
```

The handler never panics and never throws — every error path returns this envelope. There is no structured error code the way REST returns `{"error": {"code": "..."}}`; MCP clients match on the message string or the presence of `isError`.

## Amount filters and sign

Filters like `min_amount` and `max_amount` follow the same sign convention as the stored amounts.

* Find debits over \$100: `min_amount=100`.
* Find credits only: `max_amount=-0.01`.
* Find everything between $10 and $500 debits: `min_amount=10&max_amount=500`.

Zero is a valid filter value — the underlying fields are pointer types, so `min_amount=0` actually filters, rather than being treated as "unset".

## Search modes

Tools that accept `search` also accept `search_mode`:

* `contains` (default) — plain substring match. `star` matches `Starbucks`.
* `words` — all words must appear, word-boundary aware. `century link` matches `CenturyLink`.
* `fuzzy` — trigram similarity, tolerates typos. `starbuks` matches `Starbucks`.

Comma-separated values in `search` are ORed. `search=starbucks,dunkin` matches either.

`exclude_search` uses the same syntax to filter results out.

## Tag filters

`query_transactions` accepts two tag filters (also honored when called with `count_only: true`):

* `tags` — array, AND semantics. All tags must be present.
* `any_tag` — array, OR semantics. At least one tag must match.

The review queue is just `tags=["needs-review"]`.

## Fields aliases

`query_transactions` accepts a `fields` parameter to prune the response:

* `minimal` — `name`, `amount`, `date`
* `core` — `id`, `date`, `amount`, `name`, `iso_currency_code`
* `category` — `category`, `category_primary_raw`, `category_detailed_raw`
* `timestamps` — `created_at`, `updated_at`, `datetime`, `authorized_datetime`

`id` is always included. Comma-separate aliases and custom field names: `fields=core,category`.

## Limits

* List tools default to `limit=50`, max 500.
* `update_transactions` caps at 50 operations per call.
* `create_transaction_rule` accepts 1–100 rules per call via its `rules` array.

Exceeding a cap returns an error; the server does not silently truncate.