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 query_transactions with count_only: true and its intended filters so it knows whether to expect fifty results or five thousand. Only then does it call query_transactions for real, 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

{
  "accounts": [
    {
      "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"
    },
    {
      "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"
    }
  ]
}

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 (inclusive).
`end_date`	string (YYYY-MM-DD)	No	Include transactions before this date (exclusive). To cover all of January, pass `2025-02-01`.
`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 `provider_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-02-01",
  "category_slug": "food_and_drink",
  "limit": 50
}

Example output

{
  "transactions": [
    {
      "id": "txn_111222333",
      "account_id": "acc_xyz789",
      "account_name": "Chase Checking",
      "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,
  "limit": 50
}

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

Counting without paginating: `query_transactions(count_only=true)`

There’s no separate count_transactions tool. To get just a count for a given set of filters, call query_transactions with count_only: true and the same filters you’d otherwise use. The response is {"count": N} with no rows, no pagination, and no cursor — cursor, limit, sort_by, sort_order, and fields are ignored. It’s the cheap pre-flight an agent uses to decide whether to narrow filters or brace for pagination. Example input

{
  "start_date": "2025-01-01",
  "end_date": "2025-02-01",
  "count_only": true
}

Example output

{ "count": 347 }

Returns the Breadbox category taxonomy as a flat list. Each category has a stable slug — the handle agents pass to query_transactions to filter by category, and to rule actions to set a category. Scope: Read Input parameters None. Pass an empty object. Example input

{}

Example output

{
  "categories": [
    {
      "id": "cat_abc123",
      "slug": "food_and_drink",
      "display_name": "Food & Drink",
      "parent_id": null,
      "icon": "utensils",
      "color": "#f97316",
      "is_system": true
    },
    {
      "id": "cat_def456",
      "slug": "food_and_drink_groceries",
      "display_name": "Groceries",
      "parent_id": "cat_abc123",
      "parent_slug": "food_and_drink",
      "icon": "shopping-cart",
      "color": "#f97316",
      "is_system": true
    }
  ]
}

Pass a category slug as the category_slug parameter in query_transactions to filter by category. Parent slugs (e.g., food_and_drink) include all child categories automatically.

`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

{
  "users": [
    {
      "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

{
  "connections": [
    {
      "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 groups recurring charges into series. A series is a thin surrogate identity (id, name, type) — its membership is maintained by assign_series rules in the rule engine, not by a built-in detector. These tools are the agent-facing side of the Recurring page; an agent uses them to mint or rename a series and to one-off-link or unlink specific charges.

Tool	Scope	What it does
`list_series`	Read	List recurring series. Lean by default (`name`, `type`); pass `fields=all` for the full row. Use `query_transactions` with a `series_id` filter to enumerate a series’ charges.
`get_series`	Read	Fetch one series by short ID or UUID.
`assign_series`	Write	Link transactions to a series, creating it if needed. Provide `series_id` to assign to an existing series, or `series_name` + `create_if_missing: true` to mint one (surrogate-first — the same name always resolves the same series). Optional `type` (`subscription`, `bill`, `loan`, `other`) for a minted series. `transaction_ids` (≤50) back-link members; an `assign_series` call never steals a charge already in another series.
`update_series`	Write	Edit a series’ `name` and/or `type`. Both optional; omit to leave unchanged. Renaming onto another live series’ name is rejected — the name is the series’ unique mint key.
`unlink_series_transactions`	Write	Detach transactions (≤50) from a series — the inverse of `assign_series`. Each listed transaction must currently belong to the series; the call errors out otherwise so it can’t silently touch the wrong rows.

When you want every future charge from a merchant to land in a series automatically, encode that as an assign_series rule via create_transaction_rule instead of calling assign_series for each new transaction.

​What a typical agent session looks like

​list_accounts

​query_transactions

​Counting without paginating: query_transactions(count_only=true)

​list_categories

​list_users

​get_sync_status

​Series (subscriptions)

What a typical agent session looks like

`list_accounts`

`query_transactions`

Counting without paginating: `query_transactions(count_only=true)`

`list_categories`

`list_users`

`get_sync_status`

Series (subscriptions)