> ## Documentation Index
> Fetch the complete documentation index at: https://breadbox-mintlify-7401d007.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Review workflow

> Understand how Breadbox's needs-review tag, seeded rule, and tag-based workflow combine into a configurable review workflow you can extend or turn off.

Breadbox does not have a dedicated review-queue table. The "review queue" is a **tag view** — the list of transactions that carry the <Tooltip headline="needs-review tag" tip="Seeded tag used as the default review queue. A system rule auto-tags every new transaction on sync; removing the tag takes the row out of the queue." cta="Review workflow" href="/transactions/review-workflow">`needs-review`</Tooltip> tag. The workflow is built out of general-purpose primitives (tags, rules, annotations), which means you can reshape it to fit how your household actually wants to triage transactions.

## How the workflow is assembled

Three pieces make up the default experience:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="A filter view in the dashboard">
    `/reviews` in the admin UI redirects to `/transactions?tags=needs-review`. There is no separate "reviews" page; the transactions list is the queue.
  </Step>
</Steps>

All three are **configurable**. The tag can be recolored or renamed, the rule can be narrowed or disabled, and you can layer your own tags on top for workflows Breadbox doesn't ship by default.

## Resolving a review

To take a transaction out of the queue, remove the `needs-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](/api/overview) (`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 power `needs-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-amount` rule that tags anything over \$500 in addition to `needs-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 the `system` 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](/api/overview)).

System-seeded rules can be disabled but not deleted, so you can always turn the default back on.

<Note>
  Disabling the rule only affects **future** syncs. Transactions already tagged `needs-review` stay tagged until you resolve them (or bulk-remove the tag).
</Note>

## 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 backlog
* `query_transactions(tags=["needs-review"], count_only=true)` to check the size before diving in
* `update_transactions` with a compound op (<Tooltip headline="category_slug" tip="Breadbox's internal category slug (e.g. `food_and_drink_groceries`). Takes precedence over raw provider fields for display and filtering." cta="See categories" href="/transactions/categories">`category_slug`</Tooltip> + `tags_to_remove` with a note + an optional `comment`) to resolve items in batches
* Leave the tag in place when an agent isn't confident — that's the equivalent of "skipping"

A typical agent loop:

<Steps>
  <Step title="Fetch the backlog">
    `query_transactions(tags=["needs-review"], count_only=true)` to size it up, then `query_transactions(tags=["needs-review"], fields=core,category, limit=30)`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Submit a report">
    The agent submits a short Markdown summary via the [reports API](/api/overview) so the household can see what was done and what was deferred.
  </Step>
</Steps>

Agents summarize each session via the [reports API](/api/overview) (or the [`submit_report` MCP tool](/mcp/reference/reports)). For an end-to-end walkthrough, see the [Single Routine Reviewer guide](/guides/single-routine-reviewer). To connect an AI agent to your Breadbox instance, see the [MCP overview](/mcp/overview).