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. |
{ "user_id": "usr_abc123" }
{
"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. |
{
"start_date": "2025-01-01",
"end_date": "2025-02-01",
"category_slug": "food_and_drink",
"limit": 50
}
{
"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
}
"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.
| 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 (inclusive). |
end_date | string (YYYY-MM-DD) | No | Count 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. 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. |
{
"start_date": "2025-01-01",
"end_date": "2025-02-01"
}
list_categories
Returns the Breadbox category taxonomy as a flat list. Each category has a stable slug — the handle agents pass to query_transactions and count_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
}
]
}
slug as the category_slug parameter in query_transactions and count_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 | 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)
A series is a thin, rule-maintained entity — a surrogate identity, a name, and a type (subscription, bill, loan, or other). Membership comes from assign_series rules, not a shipped detector: a series is its governing rules. (The tool names stay *_series for API stability even though the surface is called Recurring.)
| Tool | Scope | What it does |
|---|
list_series | Read | List every live series — name, type, and charge count. Lean by default; pass fields=all for timestamps. |
get_series | Read | Fetch one series’ name and type by short ID or UUID. Its linked charges come from query_transactions(series_id=...); its governing rules appear on the admin Recurring detail page. |
assign_series | Write | A one-off link/mint — bind transactions to an existing series (series_id) or mint/resolve by series_name + create_if_missing:true. For durable patterns, author an assign_series rule instead. Optional type for a minted series. NULL-fill only — never steals a charge already in another series. |
update_series | Write | Rename a series or change its type. Both optional. Renaming onto an existing live name is rejected (the name is the series’ unique mint key). |
unlink_series_transactions | Write | Detach transactions from a series (inverse of assign_series’ link path). Errors if any listed transaction isn’t a current member. |
Series tags as a separate, inherited surface have been removed. Tag a series by adding an add_tag action to the same rule that does assign_series — every linked charge gets the tag at sync time and on retroactive apply.
Counterparties
A counterparty is the canonical, cross-provider “other side” of a charge — merchants and non-merchants alike (Venmo, people, employers). Same model as series: a thin entity (surrogate identity, name, optional enrichment fields like website_url, logo_url, category_id, mcc) whose membership comes from assign_counterparty rules.
| Tool | Scope | What it does |
|---|
list_counterparties | Read | List counterparties. |
get_counterparty | Read | Fetch one counterparty’s name and enrichment. Governing rules appear on the admin Counterparties detail page. |
assign_counterparty | Write | One-off link/mint — bind transactions to an existing counterparty (counterparty_id) or mint/resolve by name + create_if_missing:true, with optional enrichment in the same call. For durable patterns, author an assign_counterparty rule. |
update_counterparty | Write | Edit a counterparty’s name or enrichment fields. |
unlink_counterparty_transactions | Write | Detach transactions from a counterparty. |
