Transaction write MCP reference

Compound writes for category, tags, and comments on transactions. Categorization lives on its own page.

Write tools for editing transactions. update_transactions is the single primitive — it covers category sets, category resets, tag adds/removes, flag toggles, and a free-form comment in one atomic op per row, for up to 50 transactions per call. The retired per-row tools (categorize_transaction, batch_categorize_transactions, reset_transaction_category, bulk_recategorize, flag_transaction, unflag_transaction) all fold into it.

All tools on this page are Write scope. See Categorization for category-only writes.

---

update_transactions

Compound write for up to 50 transactions at once. Each operation can set a category (category_slug), add tags (tags_to_add), remove tags (tags_to_remove), and attach a comment — all atomically per transaction. This is the tool for closing review work (set category + remove needs-review + explain) in one call.

Every change lands as a single linked annotation per operation, so the activity timeline reads as one event per transaction rather than a separate entry for each change.

Compound op semantics

What “compound” means here. Each element in the operations array is a bundle of mutations targeting one transaction. Within a single operation:

• The category, tag additions, tag removals, and comment are applied atomically — either all land or none do.
• The annotations written for those changes are linked so the activity timeline reads as one event, not four.
• Tag note fields are preserved on both tag_added and tag_removed annotations.

on_error behavior

• continue (default) — each operation runs in its own DB transaction. A failure on row 17 doesn’t roll back rows 1–16. The response returns per-row status so you can retry the failed ones.
• abort — the whole batch runs in one DB transaction. The first error rolls back every operation and the response includes aborted: true.

Parameters

operations · array of objects · required

Array of per-transaction operations. Max 50. See the operation shape below.

on_error · string · default: "continue"

continue or abort.

Operation shape

transaction_id · string · required

UUID or short ID.

category_slug · string

Category slug to set. Sets category_override = 'agent' (skips the row if a user has already set it to 'user'). Omit to leave the category unchanged. Mutually exclusive with reset_category.

reset_category · boolean · default: "false"

Drop the transaction back to uncategorized so rules can re-categorize it on the next sync. Mutually exclusive with category_slug. Use to undo a prior agent or rule decision.

tags_to_add · array

List of {slug, note?} entries. Auto-creates persistent tags if the slug is unknown.

tags_to_remove · array

List of {slug, note?} entries. note is recommended for workflow tags like needs-review.

flagged · boolean

Flag (true) or unflag (false) the transaction for human attention without changing its category. Pair flagged: true with a comment carrying the reason; retrieve flagged rows later with query_transactions(flagged=true). Omit to leave the flag untouched. Replaces the retired flag_transaction / unflag_transaction tools.

comment · string

Free-form comment written as an annotation. Max 10000 chars. Markdown supported.

Example input

{
  "on_error": "continue",
  "operations": [
    {
      "transaction_id": "k7Xm9pQ2",
      "category_slug": "food_and_drink_groceries",
      "tags_to_remove": [
        { "slug": "needs-review", "note": "clearly groceries (Whole Foods)" }
      ]
    },
    {
      "transaction_id": "k8Yn0qR3",
      "category_slug": "transportation_ride_share",
      "tags_to_remove": [
        { "slug": "needs-review", "note": "Uber to airport" }
      ],
      "comment": "Work trip — filed to expense tracker 2026-04-20."
    }
  ]
}

Example output

{
  "results": [
    { "transaction_id": "k7Xm9pQ2", "status": "ok" },
    { "transaction_id": "k8Yn0qR3", "status": "ok" }
  ],
  "succeeded": 2,
  "failed": 0
}

Flagging a transaction

To mark a transaction for follow-up without changing its category, pass flagged: true with a comment carrying the reason. Retrieve flagged rows later with query_transactions(flagged=true). Clearing a flag is flagged: false.

{
  "operations": [
    {
      "transaction_id": "k7Xm9pQ2",
      "flagged": true,
      "comment": "Charge from a merchant we don't recognize — verify before next statement."
    }
  ]
}