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

string (YYYY-MM-DD)

Start date inclusive.

string (YYYY-MM-DD)

End date exclusive.

string

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

string

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

string

Filter by category slug. Parent slugs include all children.

number

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

number

Maximum amount.

boolean

Filter by pending status. Omit to return both.

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.

string

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

string

default:"contains"

contains, words, or fuzzy.

string

Exclude transactions whose name or merchant matches this text.

array of strings

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

array of strings

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

integer

default:"50"

Max 500.

string

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

string

default:"date"

date, amount, or provider_name.

string

default:"desc"

desc or asc.

string

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

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

string

required

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

string (YYYY-MM-DD)

Defaults to 30 days ago.

string (YYYY-MM-DD)

Defaults to today.

string

Filter by account.

string

Filter by family member (attribution-aware).

string

Filter by primary category before aggregating.

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

string

required

UUID or short ID of the transaction.

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.

Overview

Data Access (Read)

Mutations (Write)

Transaction read MCP reference

query_transactions

Parameters

Example input

Counting matches: `query_transactions(count_only=true)`

Example input

Example output

transaction_summary

Parameters

Example input

list_annotations

Parameters

Example input

​query_transactions

​Parameters

​Example input

​Counting matches: query_transactions(count_only=true)

​Example input

​Example output

​transaction_summary

​Parameters

​Example input

​list_annotations

​Parameters

​Example input

query_transactions

Parameters

Example input

Counting matches: `query_transactions(count_only=true)`

Example input

Example output

transaction_summary

Parameters

Example input

list_annotations

Parameters

Example input