Rule write MCP reference

Transaction rules are condition trees that fire during sync to auto-categorize, tag, or annotate new transactions. See Rules (read) for list_transaction_rules and preview_rule, and Categorization for apply_rules (retroactive application). The full DSL grammar is available via get_reference(kind="rule-dsl"). Key concepts recapped below under Pipeline stages. All tools on this page are Write scope.

create_transaction_rule

Create one or more transaction rules in a single call. Pass a rules array of 1–100 rule specs — a single rule is just a one-element array. Rules match condition trees against transactions during sync and fire in pipeline-stage order (priority ASC — lower runs first). Set apply_retroactively: true on any item to immediately back-fill it against existing transactions. This tool absorbs the retired batch_create_rules — there is no separate batch tool. Earlier-stage rules’ tag and category mutations feed later-stage rules’ conditions in the same pass, so composable pipelines (rule A tags coffee → rule B reads that tag → rule C sets a category) should be authored as a single multi-rule call.

Parameters

array of objects

required

Array of rule specs, 1–100 entries. Each spec follows the shape below.

Rule spec shape

string

required

Human-readable description. Convention: "<pattern-type>: <match> → <category>".

object

Condition tree. Omit or pass {} to match every transaction. See Condition grammar.

array of objects

Array of typed actions. Shapes:

{"type": "set_category", "category_slug": "..."}
{"type": "add_tag", "tag_slug": "..."}
{"type": "remove_tag", "tag_slug": "..."}
{"type": "add_comment", "content": "..."}

Actions compose — a rule can set a category, add a tag, and add a comment on the same match. add_comment fires only at sync time (not on retroactive apply). If omitted, supply category_slug as a shorthand.

string

Shorthand for [{"type": "set_category", "category_slug": "<slug>"}]. Either actions or category_slug is required.

string

default:"on_create"

When the rule fires: on_create (default — first-synced transactions), on_change (existing transactions that change on re-sync), or always (both). on_update is accepted as a legacy alias for on_change. Retroactive apply ignores trigger.

string

Semantic pipeline stage. Preferred over raw priority. One of baseline (priority 0), standard (10, default), refinement (50), override (100). If both stage and priority are supplied, priority wins.

integer

default:"10"

Raw pipeline-stage integer, 0–1000. Lower runs first. Prefer stage for shared vocabulary.

string

Optional expiry duration: 24h, 30d, 1w. Rule auto-disables after this period.

boolean

default:"false"

If true, immediately apply this rule to existing transactions after creation. Materializes set_category, add_tag, remove_tag; skips add_comment (sync-only).

Example — single rule

{
  "rules": [
    {
      "name": "name: Starbucks → food_and_drink_coffee",
      "conditions": {
        "field": "merchant_name",
        "op": "contains",
        "value": "starbucks"
      },
      "actions": [
        { "type": "set_category", "category_slug": "food_and_drink_coffee" }
      ],
      "stage": "standard",
      "trigger": "on_create"
    }
  ]
}

Example — composable pipeline

Earlier stages’ tag and category mutations are visible to later stages in the same sync pass, so a three-rule pipeline can be authored atomically:

{
  "rules": [
    {
      "name": "Tag coffee shops",
      "stage": "baseline",
      "conditions": {
        "field": "merchant_name",
        "op": "contains",
        "value": "starbucks"
      },
      "actions": [{ "type": "add_tag", "tag_slug": "coffee" }]
    },
    {
      "name": "Categorize coffee-tagged",
      "stage": "standard",
      "conditions": { "field": "tags", "op": "contains", "value": "coffee" },
      "actions": [
        { "type": "set_category", "category_slug": "food_and_drink_coffee" }
      ]
    },
    {
      "name": "Flag expensive coffee",
      "stage": "refinement",
      "conditions": {
        "and": [
          { "field": "tags", "op": "contains", "value": "coffee" },
          { "field": "amount", "op": "gt", "value": 15 }
        ]
      },
      "actions": [{ "type": "add_tag", "tag_slug": "expensive" }]
    }
  ]
}

Example output

{
  "created": 3,
  "failed": 0,
  "rules": [
    { "id": "r9Xm2pQr", "name": "Tag coffee shops", "priority": 0 },
    { "id": "rAYn0qR3", "name": "Categorize coffee-tagged", "priority": 10 },
    { "id": "rBZo1rS4", "name": "Flag expensive coffee", "priority": 50 }
  ],
  "errors": []
}

The response returns the created rules plus any per-item errors so a partial batch is recoverable. If apply_retroactively: true was set on a rule, that rule’s entry also carries retroactive_matches: <count> (or retroactive_error: "<msg>" on failure).

update_transaction_rule

Update one rule. Every field is optional — omit to leave unchanged. conditions={} explicitly clears conditions (match-all). actions=[...] replaces the entire action set. expires_at="" clears expiry.

Parameters

string

required

Rule UUID or short ID.

string

object

New condition tree. Pass {} to explicitly change to match-all. Omit entirely to leave conditions unchanged.

array of objects

Replace the entire actions array. Pass an empty array to reject (rules must have at least one action).

string

Shorthand: replace only the set_category action. Other action types on the rule are preserved.

string

integer

boolean

Disabled rules are excluded from sync and retroactive apply.

string

RFC3339 timestamp, or empty string to clear expiry.

Example input

{
  "id": "r9Xm2pQr",
  "enabled": false
}

Example output

{
  "id": "r9Xm2pQr",
  "name": "name: Starbucks → food_and_drink_coffee",
  "enabled": false,
  "priority": 10,
  "hit_count": 47,
  "last_hit_at": "2026-04-12T14:32:00Z"
}

delete_transaction_rule

Delete a rule by ID. System-seeded rules (the needs-review auto-tagger) cannot be deleted — disable them via update_transaction_rule instead.

Parameters

string

required

Rule UUID or short ID.

Example input

{
  "id": "r9Xm2pQr"
}

Example output

{
  "deleted": true,
  "id": "r9Xm2pQr"
}

Pipeline stages and priority

Rules fire in priority-ASC order during each sync pass, and within a single pass each rule observes mutations from earlier-stage rules. That makes rules composable — rule A can add a tag, rule B’s condition can react to that tag, rule C can set a category based on the combined state.

Stage	Priority	Typical use
`baseline`	0	Broad defaults — tagging coffee shops, marking credit card payments
`standard`	10 (default)	Most categorization rules
`refinement`	50	Rules that react to earlier-stage tags or categories
`override`	100	Rules that forcibly win `set_category` regardless of what earlier stages did

Rules of thumb:

Per-merchant rules (priority 20–30 or refinement) > name-pattern rules (standard) > category_primary rules (baseline).
Prefer contains over exact match — bank feeds format merchant names inconsistently.
Always use category_slug, not category_id, when authoring actions or filters.

Condition grammar

Same grammar used by preview_rule.

Fields — name, merchant_name, amount, category_primary, category_detailed, category (assigned slug, live-updated by earlier-stage rules), pending, provider, account_id, account_name, user_id, user_name, tags.
Operators —
- String/category: eq, neq, contains, not_contains, matches (RE2), in.
- Numeric: eq, neq, gt, gte, lt, lte.
- Bool: eq, neq.
- Tags: contains, not_contains, in.
Combinators — and, or, not (nest freely, max depth 10).

Nested example:

{
  "or": [
    {
      "and": [
        { "field": "merchant_name", "op": "contains", "value": "starbucks" },
        { "field": "amount", "op": "gte", "value": 5 }
      ]
    },
    { "field": "tags", "op": "contains", "value": "coffee" }
  ]
}

Overview

Data Access (Read)

Mutations (Write)

Rule write MCP reference

create_transaction_rule

Parameters

Rule spec shape

Example — single rule

Example — composable pipeline

Example output

update_transaction_rule

Parameters

Example input

Example output

delete_transaction_rule

Parameters

Example input

Example output

Pipeline stages and priority

Condition grammar

​create_transaction_rule

​Parameters

​Rule spec shape

​Example — single rule

​Example — composable pipeline

​Example output

​update_transaction_rule

​Parameters

​Example input

​Example output

​delete_transaction_rule

​Parameters

​Example input

​Example output

​Pipeline stages and priority

​Condition grammar

create_transaction_rule

Parameters

Rule spec shape

Example — single rule

Example — composable pipeline

Example output

update_transaction_rule

Parameters

Example input

Example output

delete_transaction_rule

Parameters

Example input

Example output

Pipeline stages and priority

Condition grammar