How the workflow is assembled
Three pieces make up the default experience:A seeded `needs-review` tag
A workflow tag that is expected to come off once a transaction has been reviewed. When you remove it, you can include an optional note that gets recorded on the transaction’s activity timeline.
A seeded rule on `on_create`
A system-created rule fires for every newly-synced transaction and applies the
needs-review tag. No conditions — it matches everything by default.Resolving a review
To take a transaction out of the queue, remove theneeds-review tag. You can include an optional note when removing it — the note is saved as an annotation so anyone (or any agent) looking at the transaction later can see why the review was closed.
In the dashboard, the transaction detail view has a Remove tag action with a note prompt. An MCP-connected agent does the same thing in a single compound write via update_transactions — set the category, remove needs-review with a note, and optionally leave a comment, all in one operation.
Leaving the tag in place is the “skip” action — the transaction stays in the queue for next time. There is no separate reject or approve state; the decision is captured by whichever category ends up on the transaction plus the note you leave when the tag comes off.
The REST surface covers both sides of a review: PATCH /api/v1/transactions/{id}/category for category changes, plus the Tags API (POST /api/v1/transactions/{id}/tags to attach, DELETE /api/v1/transactions/{id}/tags/{slug} to detach with an optional note). MCP’s update_transactions remains the ergonomic path for agents — it bundles category + tag + comment into a single compound op — but direct REST works too if you prefer scripting without an MCP client.
Making the workflow your own
The same primitives that powerneeds-review power any review-style workflow you want. Create a flagged tag for follow-ups, a disputed tag for charges to contest with your bank, a tax-deductible tag for end-of-year collection — each with its own rule conditions.
Common customizations:
- Narrow the auto-tag rule so only transactions that need attention get flagged — for example, only uncategorized rows, only amounts above a threshold, or only accounts you actually reconcile.
- Add parallel tags for specific workflows (e.g., a
high-amountrule that tags anything over $500 in addition toneeds-review), so you can filter to the subset you care about first. - Disable the auto-tag rule entirely if you don’t want every new transaction on the queue by default.
Disabling the auto-tag rule
The seeded rule is named Auto-tag new transactions for review and is owned by thesystem creator type. You can disable the seeded rule from Rules in the admin UI (or, if you’re scripting, via the rules API — see Rules API).
System-seeded rules can be disabled but not deleted, so you can always turn the default back on.
Disabling the rule only affects future syncs. Transactions already tagged
needs-review stay tagged until you resolve them (or bulk-remove the tag).AI agents in the workflow
Because the queue is just a tag filter, AI agents connected over MCP can participate using the same tools humans would:query_transactions(tags=["needs-review"])to fetch the backlogcount_transactions(tags=["needs-review"])to check the size before diving inupdate_transactionswith a compound op ( +tags_to_removewith a note + an optionalcomment) to resolve items in batches- Leave the tag in place when an agent isn’t confident — that’s the equivalent of “skipping”
Fetch the backlog
count_transactions(tags=["needs-review"]) to size it up, then query_transactions(tags=["needs-review"], fields=core,category, limit=30).Decide per transaction
For each row the agent inspects name, merchant, amount, and any pre-applied category. It applies your review guidelines (configurable in settings) to decide whether to accept the category, change it, or defer.
Resolve in batches
update_transactions with up to 50 compound ops — set category if needed, remove needs-review with a short rationale, optionally leave a comment.Submit a report
The agent submits a short Markdown summary via the reports API so the household can see what was done and what was deferred.
submit_report MCP tool). For an end-to-end walkthrough, see the Single Routine Reviewer guide. To connect an AI agent to your Breadbox instance, see the MCP overview.