MCP tools for querying financial data

This page is for you — the person deciding what to hand an agent. Agents receive these tool schemas at inference time and don’t need to read this page; they see the parameters, descriptions, and JSON schemas directly through the MCP protocol. Use this reference to understand the surface area a connected AI client can touch, so you can pick the right API-key scope and know what will show up in your audit log.

Looking for the full tool list? This page walks through the handful of tools you’re most likely to care about as a human. For the complete enumeration of every MCP tool with full parameters, examples, and scope labels, see the MCP Reference tab.

Amount convention: Amounts follow Plaid’s convention. Positive values are debits (money leaving an account). Negative values are credits (money entering). If an agent talks about “total spend,” it’s summing positive amounts only.

What a typical agent session looks like

An agent connected to Breadbox usually opens a session by orienting itself before it starts querying. First it calls list_users and list_accounts to see who’s in the household and which accounts exist — this gives it the IDs it needs to filter anything downstream. Then, before pulling rows, it calls count_transactions with its intended filters so it knows whether to expect fifty results or five thousand. Only then does it call query_transactions, paginating with the returned cursor if has_more is true. That pattern — orient, size, query — keeps token usage predictable and matches how Breadbox’s tools are designed. You don’t need to enforce it from the outside; the tool descriptions nudge the agent toward it.

`list_accounts`

Lists all connected bank accounts with their current balances. An agent typically calls this early in a session to learn what accounts exist and get their IDs. Scope: Read Input parameters

Parameter	Type	Required	Description
`user_id`	string	No	Return only accounts owned by this family member. Omit to return all accounts.

Example input

{ "user_id": "usr_abc123" }

Example output

{
  "data": [
    {
      "id": "acc_xyz789",
      "name": "Chase Checking",
      "type": "depository",
      "subtype": "checking",
      "mask": "4321",
      "balance_current": 2450.18,
      "balance_available": 2380.00,
      "balance_limit": null,
      "iso_currency_code": "USD",
      "institution_name": "Chase",
      "user_id": "usr_abc123",
      "user_name": "Alice"
    },
    {
      "id": "acc_def456",
      "name": "Amex Gold",
      "type": "credit",
      "subtype": "credit card",
      "mask": "1008",
      "balance_current": -541.20,
      "balance_available": null,
      "balance_limit": 10000.00,
      "iso_currency_code": "USD",
      "institution_name": "American Express",
      "user_id": "usr_abc123",
      "user_name": "Alice"
    }
  ]
}

For credit accounts, balance_current represents the amount owed, not available funds. Amounts across different iso_currency_code values should not be summed.

`query_transactions`

Searches transactions using a combination of filters. Results are cursor-paginated with a default page size of 50 and a maximum of 500. This is the workhorse tool — almost every non-trivial agent session goes through it. Scope: Read Input parameters

Parameter	Type	Required	Description
`start_date`	string (YYYY-MM-DD)	No	Include transactions on or after this date.
`end_date`	string (YYYY-MM-DD)	No	Include transactions on or before this date.
`account_id`	string	No	Filter to a specific account.
`user_id`	string	No	Filter to accounts owned by this family member.
`category_slug`	string	No	Filter by category slug (e.g., `food_and_drink`). Parent slugs include all children. See MCP: categories for the full list.
`min_amount`	number	No	Minimum transaction amount in USD. Zero is a valid value.
`max_amount`	number	No	Maximum transaction amount in USD. Zero is a valid value.
`pending`	boolean	No	`true` returns only pending transactions; `false` returns only posted. Omit for both.
`search`	string	No	Full-text search over merchant name and description.
`sort_by`	string	No	Sort field: `date` (default), `amount`, or `name`. Cursor pagination requires `date`.
`sort_order`	string	No	Sort direction: `desc` (default) or `asc`.
`limit`	integer	No	Results per page. Default: 50. Maximum: 500.
`cursor`	string	No	Pagination cursor from the previous response. Omit for the first page.

Example input

{
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "category_slug": "food_and_drink",
  "limit": 50
}

Example output

{
  "data": [
    {
      "id": "txn_111222333",
      "account_id": "acc_xyz789",
      "account_name": "Chase Checking",
      "user_id": "usr_abc123",
      "user_name": "Alice",
      "amount": 14.50,
      "iso_currency_code": "USD",
      "date": "2025-01-15",
      "authorized_date": "2025-01-14",
      "merchant_name": "Blue Bottle Coffee",
      "name": "BLUE BOTTLE COFFEE #12",
      "category_primary": "FOOD_AND_DRINK",
      "category_detailed": "FOOD_AND_DRINK_COFFEE",
      "payment_channel": "in store",
      "pending": false
    }
  ],
  "next_cursor": "dHhuXzExMTIyMzM0",
  "has_more": true
}

When there are no more pages, the response includes "has_more": false and "next_cursor": null.

Each transaction object is roughly 50 tokens. At the default page size of 50, one call returns approximately 2,500 tokens of content. At the maximum of 500, a single call can reach 25,000 tokens. If your agent pulls large result sets unfiltered, your context budget will disappear fast.

Page size guidance

Use case	Recommended `limit`
Sampling or spot-checking	25
Single-month analysis	50 (default)
Full dataset processing	200–500
Maximum allowed	500

`count_transactions`

Counts matching transactions without returning any transaction data. Accepts the same filters as query_transactions (excluding cursor, limit, sort_by, and sort_order). It’s the cheap pre-flight an agent uses to decide whether to narrow filters or brace for pagination. Scope: Read Input parameters

Parameter	Type	Required	Description
`start_date`	string (YYYY-MM-DD)	No	Count transactions on or after this date.
`end_date`	string (YYYY-MM-DD)	No	Count transactions on or before this date.
`account_id`	string	No	Filter to a specific account.
`user_id`	string	No	Filter to accounts owned by this family member.
`category_slug`	string	No	Filter by category slug. Parent slugs include all children.
`min_amount`	number	No	Minimum transaction amount.
`max_amount`	number	No	Maximum transaction amount.
`pending`	boolean	No	Filter by pending status.
`search`	string	No	Full-text search over merchant name and description.

Example input

{
  "start_date": "2025-01-01",
  "end_date": "2025-01-31"
}

Example output

{ "count": 347 }

Lists all distinct transaction category pairs — primary category and detailed subcategory — that exist in your database. Useful for discovering valid category values before filtering transactions. Scope: Read Input parameters None. Pass an empty object. Example input

{}

Example output

{
  "data": [
    { "primary": "FOOD_AND_DRINK", "detailed": "FOOD_AND_DRINK_GROCERIES" },
    { "primary": "FOOD_AND_DRINK", "detailed": "FOOD_AND_DRINK_RESTAURANTS" },
    { "primary": "TRANSPORTATION", "detailed": "TRANSPORTATION_GAS" }
  ]
}

The returned primary values are valid for query_transactions’s category parameter; detailed values are valid for category_detailed.

`list_users`

Lists all family members tracked in Breadbox. Users are labels for account ownership — they are not login accounts. Returned IDs are what an agent uses to filter accounts and transactions by person. Scope: Read Input parameters None. Pass an empty object. Example input

{}

Example output

{
  "data": [
    {
      "id": "usr_abc123",
      "name": "Alice",
      "email": "alice@example.com"
    },
    {
      "id": "usr_def456",
      "name": "Bob",
      "email": "bob@example.com"
    }
  ]
}

`get_sync_status`

Returns the health status of all bank connections: whether they are syncing successfully, when they last synced, and whether any connection needs re-authentication. This is how an agent answers “why don’t I see yesterday’s transactions?” without guessing. Scope: Read Input parameters None. Pass an empty object. Example input

{}

Example output

{
  "data": [
    {
      "id": "conn_aaa111",
      "institution_name": "Chase",
      "provider": "plaid",
      "status": "active",
      "last_synced_at": "2025-01-20T14:32:00Z",
      "error_message": null,
      "accounts_count": 3
    },
    {
      "id": "conn_bbb222",
      "institution_name": "Bank of America",
      "provider": "plaid",
      "status": "error",
      "last_synced_at": "2025-01-18T09:15:00Z",
      "error_message": "ITEM_LOGIN_REQUIRED: User must re-authenticate via Plaid Link.",
      "accounts_count": 2
    }
  ]
}

Status values

Status	Meaning
`active`	Connection is healthy and syncing normally.
`error`	Last sync failed. Check `error_message` for details.
`pending_reauth`	Connection requires user re-authentication (e.g., bank login changed).
`disconnected`	Connection has been disconnected or removed.

To trigger a manual sync from outside an agent session, use POST /api/v1/sync (REST) or breadbox sync trigger (CLI). Breadbox does not expose a trigger_sync MCP tool — syncs run on the configured cron, and agents are expected to call get_sync_status to check freshness rather than kick off their own syncs.

Series (subscriptions)

Breadbox detects recurring charges and groups them into series. These tools are the agent-facing side of the Recurring page — they let a scheduled reviewer adjudicate what the detector proposed and fill in anything it missed. (The tool names stay *_series for API stability even though the surface is now called Recurring.)

Tool	Scope	What it does
`list_series`	Read	List detected series. Filter by `status` (`active`, `candidate`, `paused`, `cancelled`); `candidate` surfaces the ones awaiting a verdict. Each row carries cadence, expected amount + currency, next expected date, and the detection signals.
`get_series`	Read	Fetch one series by ID, including the full evidence the detector used.
`review_series`	Write	Apply a verdict: `confirm`, `reject` (sticky — never re-proposed at that amount band), `pause`, or `cancel`. A user’s prior confirmation outranks a later agent verdict.
`assign_series`	Write	Create a series the detector missed, or back-link transactions to an existing one. Never steals a charge already in another series.
`explain_series_candidates`	Read	Answer “why isn’t X recurring?” — lists recurring-looking merchants the precision-first detector skipped, with the reason (too few occurrences, irregular cadence, unstable amount, …).
`rekey_series`	Write	Fix a series grouped under a wrong or fallback merchant key (e.g. `payment` → `spotify`), repointing it and its charges.
`split_series`	Write	Break an over-grouped series in two — move stray charges into a new series (e.g. a $4.99 add-on swept into a$ 139/yr renewal).
`add_series_tag` / `remove_series_tag`	Write	Tag a series; every linked transaction inherits the tag automatically. Removing strips only the inherited copies.

A typical reviewer agent calls list_series(status="candidate"), inspects each with get_series, and resolves it with review_series — the same confirm/reject loop a person runs on the Recurring page.

​What a typical agent session looks like

​list_accounts

​query_transactions

​count_transactions

​list_categories

​list_users

​get_sync_status

​Series (subscriptions)

What a typical agent session looks like

`list_accounts`

`query_transactions`

`count_transactions`

`list_categories`

`list_users`

`get_sync_status`

Series (subscriptions)