Transaction read MCP reference

MCP read tools for querying, counting, summarizing transactions and reading comments, matches, and annotations.

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.

flagged · boolean

Filter to flagged transactions (true) or unflagged (false). Omit to return both. Use flagged=true to retrieve transactions you (or an agent) marked for follow-up via update_transactions.

search · 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.

tags · array of strings

Tags the transaction must have (AND). The review queue is ["needs-review"].

any_tag · array of strings

Tags the transaction must have at least one of (OR).

limit · integer · default: "50"

Max 500.

cursor · string

Opaque pagination cursor from a previous response. Only valid with sort_by=date.

sort_by · string · default: "date"

date, amount, or provider_name.

sort_order · string · default: "desc"

desc or asc.

fields · string

Comma-separated fields or aliases (minimal, core, category, timestamps). See Conventions. id is always included.

count_only · boolean · default: "false"

When true, return only {"count": N} for the given filters — no rows, no pagination. cursor, limit, sort_by, sort_order, and fields are ignored. Use this to size a result set or compare counts across date ranges or categories before paginating. Replaces the retired count_transactions tool.

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
}

---

Counting matches: query_transactions(count_only=true)

There is no separate count_transactions tool. To get just a count for a given set of filters, pass count_only: true to query_transactions with 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. Agents use this as a cheap pre-flight to decide whether to paginate or narrow filters.

Scope: Read

Mirrors: GET /api/v1/transactions/count

Example input

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

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).

category · string

Filter by primary category before aggregating.

include_pending · boolean · default: "false"

Include pending transactions.

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"
  }
}

---

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.