Transaction read MCP reference

The core read surface of Breadbox. Agents query transactions, aggregate spending, and read activity context through the tools on this page. All amounts use the Plaid sign convention: positive = money out, negative = money in. See Conventions for the full cross-cutting rules.

query_transactions

Returns a paginated list of transactions matching the supplied filters. This is the workhorse read tool — almost every agent session goes through it. Scope: Read Mirrors: GET /api/v1/transactions

Parameters

start_date

string (YYYY-MM-DD)

Start date inclusive.

end_date

string (YYYY-MM-DD)

End date exclusive.

account_id

string

Filter to a single account (UUID or short ID).

user_id

string

Filter to all accounts owned by a family member. Attribution-aware — includes transactions attributed to this user via account links.

category_slug

string

Filter by category slug. Parent slugs include all children.

min_amount

number

Minimum amount (positive = debit, negative = credit).

max_amount

number

Maximum amount.

pending

boolean

Filter by pending status. Omit to return both.

string

Case-insensitive substring match on name and merchant_name. Comma-separate values for OR.

search_mode

string

default:"contains"

contains, words, or fuzzy.

exclude_search

string

Exclude transactions whose name or merchant matches this text.

Example input

{
  "start_date": "2026-03-01",
  "end_date": "2026-04-01",
  "category_slug": "food_and_drink_groceries",
  "fields": "core,category",
  "limit": 100
}

Example output

{
  "transactions": [
    {
      "id": "k7Xm9pQ2",
      "date": "2026-03-28",
      "amount": 67.43,
      "name": "WHOLE FOODS MARKET #10452",
      "iso_currency_code": "USD",
      "category": {
        "slug": "food_and_drink_groceries",
        "display_name": "Groceries",
        "primary_slug": "food_and_drink",
        "primary_display_name": "Food and Drink"
      },
      "category_primary_raw": "FOOD_AND_DRINK",
      "category_detailed_raw": "FOOD_AND_DRINK_GROCERIES"
    }
  ],
  "next_cursor": "eyJkYXRlIjoiMjAyNi0wMy0yOCIsImlkIjoiazdYbTlwUTIifQ",
  "has_more": true,
  "limit": 100
}

count_transactions

Returns the count of transactions matching the filters, without fetching any rows. Agents use this as a cheap pre-flight to decide whether to paginate or narrow filters. Scope: Read Mirrors: GET /api/v1/transactions/count

Parameters

Accepts the same filters as query_transactions except cursor, limit, sort_by, sort_order, and fields.

Example input

{
  "start_date": "2026-01-01",
  "end_date": "2026-04-01",
  "category_slug": "food_and_drink_groceries"
}

Example output

{ "count": 128 }

transaction_summary

Returns aggregated transaction totals grouped by category, month, week, day, or category × month. Replaces the need to paginate through every transaction for spending analysis. Amounts follow the Plaid convention — positive = money out. Scope: Read Mirrors: GET /api/v1/transactions/summary

Parameters

group_by

string

required

One of category, month, week, day, category_month.

start_date

string (YYYY-MM-DD)

Defaults to 30 days ago.

end_date

string (YYYY-MM-DD)

Defaults to today.

account_id

string

Filter by account.

user_id

string

Filter by family member (attribution-aware).

Example input

{
  "group_by": "category",
  "start_date": "2026-03-01",
  "end_date": "2026-04-01"
}

Example output

{
  "summary": [
    {
      "category": "food_and_drink_groceries",
      "total_amount": 843.21,
      "transaction_count": 34,
      "iso_currency_code": "USD"
    },
    {
      "category": "transportation_gas",
      "total_amount": 312.50,
      "transaction_count": 18,
      "iso_currency_code": "USD"
    }
  ],
  "totals": {
    "total_amount": 1155.71,
    "transaction_count": 52
  },
  "filters": {
    "start_date": "2026-03-01",
    "end_date": "2026-04-01",
    "group_by": "category"
  }
}

merchant_summary

Lists distinct merchants with aggregated stats — count, total, average, and date range. Agents use this to scan for recurring charges, find top merchants, or surface unknown subscriptions. Scope: Read Mirrors: GET /api/v1/transactions/merchants

Parameters

start_date

string (YYYY-MM-DD)

Defaults to 90 days ago.

end_date

string (YYYY-MM-DD)

Defaults to today.

account_id

string

Filter by account.

user_id

string

Filter by family member.

category_slug

string

Filter by category.

min_amount

number

Minimum per-transaction amount.

max_amount

number

Maximum per-transaction amount.

string

Search merchant/transaction names.

search_mode

string

default:"contains"

contains, words, fuzzy.

exclude_search

string

Exclude merchants matching this text.

min_count

integer

default:"1"

Minimum transaction count to include a merchant. Set to 2 for recurring, 3 for likely subscriptions.

spending_only

boolean

default:"false"

Only include positive amounts (spending).

Example input

{
  "start_date": "2026-01-01",
  "end_date": "2026-04-01",
  "min_count": 3,
  "spending_only": true
}

Example output

{
  "merchants": [
    {
      "merchant": "Netflix",
      "transaction_count": 3,
      "total_amount": 42.00,
      "avg_amount": 14.00,
      "first_date": "2026-01-15",
      "last_date": "2026-03-15",
      "iso_currency_code": "USD"
    },
    {
      "merchant": "Whole Foods Market",
      "transaction_count": 12,
      "total_amount": 843.21,
      "avg_amount": 70.27,
      "first_date": "2026-01-03",
      "last_date": "2026-03-28",
      "iso_currency_code": "USD"
    }
  ],
  "totals": {
    "merchant_count": 2,
    "transaction_count": 15,
    "total_amount": 885.21
  },
  "filters": {
    "start_date": "2026-01-01",
    "end_date": "2026-04-01",
    "min_count": 3
  }
}

list_transaction_comments

Deprecated. Use list_annotations with kinds=['comment'] instead. The new tool returns the same comment data using the canonical annotation shape — note the field renames: actor_type / actor_id / actor_name (was author_*) and payload.content (was top-level content). list_transaction_comments will be removed in a future release.

Returns all comments attached to a transaction, ordered chronologically. Agents should check comments before writing to understand prior context. Scope: Read

Parameters

transaction_id

string

required

UUID or short ID of the transaction.

Example input

{ "transaction_id": "k7Xm9pQ2" }

Example output

[
  {
    "id": "c4Xp2mQr",
    "transaction_id": "k7Xm9pQ2",
    "content": "Shared grocery run — split with roommate.",
    "author_type": "user",
    "author_id": "u4Xm9pQ2",
    "author_name": "Alice",
    "created_at": "2026-03-29T10:12:00Z",
    "updated_at": "2026-03-29T10:12:00Z"
  }
]

list_transaction_matches

Lists transaction pairs matched by an account link. Used to audit which primary-account transactions were attributed to a dependent user via the account-link dedup system. Scope: Read

Parameters

link_id

string

required

The account link ID to list matches for.

Example input

{ "link_id": "L9Xm2pQr" }

Example output

[
  {
    "id": "M4Xp9mQr",
    "account_link_id": "L9Xm2pQr",
    "primary_transaction_id": "k7Xm9pQ2",
    "dependent_transaction_id": "n3Xr5mQp",
    "match_confidence": "auto",
    "matched_on": ["date", "amount"],
    "primary_txn_name": "WHOLE FOODS MARKET #10452",
    "primary_txn_merchant": "Whole Foods",
    "dependent_txn_name": "WHOLE FOODS #10452",
    "dependent_txn_merchant": "Whole Foods",
    "amount": 67.43,
    "date": "2026-03-28",
    "created_at": "2026-03-28T08:15:00Z"
  }
]

list_annotations

Returns the activity timeline for a single transaction: comments, tag adds/removes, rule applications, and category sets. Ordered by created_at ascending. Use this to reconstruct “what happened to this transaction and when” before making further changes. Each row carries a generic kind plus an action for the specific event, so you can branch on the action without parsing the kind string:

`kind`	`action` values	Notes
`comment`	(omitted)	Free-form comment. `payload.content` carries the body.
`rule`	`applied`	A transaction rule fired. `payload.rule_name` and `rule_id` are populated.
`tag`	`added` / `removed`	Tag attached to or detached from the transaction. `tag_id` and `payload.slug` are populated.
`category`	`set`	Category was set (manual override or via rule).

Scope: Read

Parameters

transaction_id

string

required

UUID or short ID of the transaction.

kinds

string[]

Optional kind filter. Any of comment, rule, tag, category. Empty (default) returns the full timeline. Pass ['comment'] for the comment-only view (replaces the deprecated list_transaction_comments); pass ['tag'] for both add and remove tag events; pass ['comment','tag','category'] to skip rule-application churn.Only the generic kinds above are accepted at the MCP boundary — the underlying DB-level values (tag_added, tag_removed, rule_applied, category_set) will be rejected with an invalid kind error.

Example input

{ "transaction_id": "k7Xm9pQ2" }

Comment-only view (replaces list_transaction_comments):

{ "transaction_id": "k7Xm9pQ2", "kinds": ["comment"] }

All tag events (added and removed):

{ "transaction_id": "k7Xm9pQ2", "kinds": ["tag"] }

Example output

[
  {
    "id": "a1Xm2pQ9",
    "transaction_id": "k7Xm9pQ2",
    "kind": "tag",
    "action": "added",
    "actor_type": "system",
    "actor_name": "system",
    "tag_id": "t1Xm9pQ2",
    "payload": { "slug": "needs-review" },
    "created_at": "2026-03-28T06:00:00Z"
  },
  {
    "id": "a2Yn3qR0",
    "transaction_id": "k7Xm9pQ2",
    "kind": "category",
    "action": "set",
    "actor_type": "agent",
    "actor_name": "Review Agent",
    "session_id": "s9Xm2pQk",
    "payload": {
      "category_slug": "food_and_drink_groceries",
      "note": "clearly groceries"
    },
    "created_at": "2026-03-29T10:12:00Z"
  },
  {
    "id": "a3Zo4rS1",
    "transaction_id": "k7Xm9pQ2",
    "kind": "tag",
    "action": "removed",
    "actor_type": "agent",
    "actor_name": "Review Agent",
    "session_id": "s9Xm2pQk",
    "tag_id": "t1Xm9pQ2",
    "payload": { "slug": "needs-review", "note": "clearly groceries" },
    "created_at": "2026-03-29T10:12:00Z"
  }
]

kind carries the generic event family (comment, rule, tag, category) and action carries the specific event (added, removed, set, applied). Comment rows omit action because there is only one event. Actor identity is split across actor_type (user / agent / system), actor_name, and optional actor_id. When a write tool passed a session_id, it’s echoed here so you can group events by session. Rule applications set rule_id; tag events set tag_id.

​query_transactions

​Parameters

​Example input

​count_transactions

​Parameters

​Example input

​Example output

​transaction_summary

​Parameters

​Example input

​merchant_summary

​Parameters

​Example input

​list_transaction_comments

​Parameters

​Example input

​Example output

​list_transaction_matches

​Parameters

​Example input

​Example output

​list_annotations

​Parameters

​Example input

query_transactions

Parameters

Example input

count_transactions

Parameters

Example input

Example output

transaction_summary

Parameters

Example input

merchant_summary

Parameters

Example input

list_transaction_comments

Parameters

Example input

Example output

list_transaction_matches

Parameters

Example input

Example output

list_annotations

Parameters

Example input