canalesb93 · mintlify · Jun 25, 2026
diff --git a/guides/multi-agent-reviewer.mdx b/guides/multi-agent-reviewer.mdx
@@ -39,7 +39,7 @@ can work them.
 
 Each run:
 
-1. `count_transactions(tags=["needs-review"])`. If zero, submit a report
+1. `query_transactions(tags=["needs-review"], count_only=true)`. If zero, submit a report
    and stop.
 2. `query_transactions(tags=["needs-review"], fields="core,category",
    limit=50)`.

diff --git a/guides/on-demand-analysis.mdx b/guides/on-demand-analysis.mdx
@@ -103,7 +103,7 @@ include pending transactions."
 I'll:
 1. Call list_categories to find the grocery category slugs available.
 2. Call list_users to get the user IDs.
-3. Call count_transactions with category_detailed=FOOD_AND_DRINK_GROCERIES,
+3. Call query_transactions(count_only=true) with category_detailed=FOOD_AND_DRINK_GROCERIES,
    start_date=2026-01-01, end_date=2026-03-31, pending=false. If the
    count is manageable (<500), proceed.
 4. Call query_transactions with the same filters, paginated as needed.

diff --git a/guides/openclaw-recurring-workflows.mdx b/guides/openclaw-recurring-workflows.mdx
@@ -54,7 +54,7 @@ On each run:
 1. Call `create_session` with purpose "12h triage — <ISO date>".
    Save the returned session_id for all subsequent write calls.
 
-2. Call `count_transactions(tags=["needs-review"])`.
+2. Call `query_transactions(tags=["needs-review"], count_only=true)`.
    - If the count is 0: call `submit_report` with title
      "Triage check — queue empty." and stop.
    - If the count is 1–150: proceed to step 3.

diff --git a/guides/single-routine-reviewer.mdx b/guides/single-routine-reviewer.mdx
@@ -11,7 +11,7 @@ Every iteration the agent does the same four things:
 
 <Steps>
   <Step title="Size up the backlog">
-    Call `count_transactions(tags=["needs-review"])` to see how many transactions are pending. If the count is very large, the agent narrows by date or account.
+    Call `query_transactions(tags=["needs-review"], count_only=true)` to see how many transactions are pending. If the count is very large, the agent narrows by date or account.
   </Step>
   <Step title="Fetch a working batch">
     Call `query_transactions(tags=["needs-review"], fields="core,category", limit=30)` to pull a page worth of detail. Keep batches small — one batch is the unit the agent reasons over end-to-end.
@@ -77,7 +77,7 @@ Step-by-step, every run:
 1. Call `get_sync_status`. If any connection has `status = "error"` or
    `status = "pending_reauth"`, note it in the report and skip those
    accounts' transactions.
-2. Call `count_transactions(tags=["needs-review"])`. If the count is over
+2. Call `query_transactions(tags=["needs-review"], count_only=true)`. If the count is over
    200, narrow the batch by the most recent 7 days.
 3. Call `query_transactions(tags=["needs-review"], fields="core,category",
    limit=30)`. Work in batches of 30.
@@ -129,4 +129,4 @@ Until you hit one of those, keep it simple.
 
 - [Breadbox in a nutshell](/guides/breadbox-in-a-nutshell) — the primitives the loop rests on.
 - [Review workflow](/transactions/review-workflow) — the full spec for the `needs-review` tag and its seeded rule.
-- [MCP tools](/mcp/tools) — reference for `query_transactions`, `count_transactions`, and `update_transactions`.
+- [MCP tools](/mcp/tools) — reference for `query_transactions` (including its `count_only` mode) and `update_transactions`.
diff --git a/guides/tracking-subscriptions.mdx b/guides/tracking-subscriptions.mdx
@@ -74,10 +74,12 @@ To make every future charge from a merchant join a series on sync, use the [`ass
 
 The same surface is available over MCP, which is how a scheduled reviewer agent can keep your subscription list tidy:
 
-- `list_series` (optionally `status=candidate`) to find series awaiting a verdict, then `review_series` to confirm, reject, pause, or cancel.
-- `get_series` to inspect one series and the evidence behind it.
-- `assign_series` to create a series detection missed, or back-link charges to an existing one.
-- `add_series_tag` / `remove_series_tag` to tag a subscription and its members.
+- `list_series` to scan the current series; `get_series` to inspect one.
+- `assign_series` to mint a series an agent missed, or back-link transactions to an existing one.
+- `update_series` to rename a series or change its type (`subscription`, `bill`, `loan`, `other`).
+- `unlink_series_transactions` to detach charges that don't belong.
+
+When you want every future charge from a merchant to land in a series automatically, encode that as an `assign_series` rule via `create_transaction_rule` rather than calling `assign_series` repeatedly.
 
 See the [MCP tools](/mcp/tools#series-subscriptions) page for the agent-facing summary.
 

diff --git a/mcp/overview.mdx b/mcp/overview.mdx
@@ -20,25 +20,38 @@ Breadbox supports two ways to connect an MCP client.
 
 ## What the MCP server exposes
 
-The server advertises two capability types: **tools** and **resources**.
+The server advertises a single capability type: **tools**. Earlier versions of Breadbox also published a parallel `breadbox://` resources surface, but that has been retired — every read is now a tool call, including the orientation reads and the operating-guidance docs.
 
-**Tools** are callable functions the agent uses to query and change your data — listing accounts, searching transactions, counting results, categorizing, tagging, creating rules, triggering syncs, and submitting reports. Around 40 tools in total; see the [MCP Reference](/mcp/reference/overview) tab for the complete enumeration, or [MCP tools](/mcp/tools) for a human walkthrough of the ones you're most likely to grant access to.
+**Tools** are callable functions the agent uses to query and change your data — listing accounts, searching transactions, counting results, categorizing, tagging, creating rules, triggering syncs, and submitting reports. The registry has 35 tools. See the [MCP Reference](/mcp/reference/overview) tab for the complete enumeration, or [MCP tools](/mcp/tools) for a human walkthrough of the ones you're most likely to grant access to.
 
-**Resources** are passive context documents the agent can read to orient itself before taking action.
+### Orientation reads
 
-| Resource URI | What it contains |
+The first thing a connecting agent should do is orient itself with the bounded reference reads — each one is a dedicated tool:
+
+| Tool | What it returns |
 |---|---|
-| `breadbox://overview` | Live dataset summary organized as scope (counts, date range), freshness (last sync, ingest signals, errored connections), and backlog (needs-review and unmapped counts), plus the household roster |
-| `breadbox://accounts` | Bank accounts (checking, savings, credit cards, loans, investments) with balances, institution names, and currency |
-| `breadbox://categories` | Two-level category taxonomy keyed by slug; the source of valid `category_slug` values |
-| `breadbox://tags` | Current tag vocabulary keyed by slug; the `needs-review` tag is the review-queue handle |
-| `breadbox://users` | Household members with their roles (admin, editor, viewer) |
-| `breadbox://sync-status` | Per-connection sync status and last-sync timestamps |
-| `breadbox://review-guidelines` | Guidelines for reviewing transactions and creating categorization rules; editable from the MCP Settings page |
-| `breadbox://report-format` | Templates and formatting rules for agent-submitted reports; editable from the MCP Settings page |
-| `breadbox://rule-dsl` | Reference grammar for transaction rules: condition fields, action types, priority bands, and provider quirks |
-
-The `breadbox://overview` resource gives the agent ambient context about your household's financial state without requiring a round-trip tool call. An agent that reads it first knows how big the dataset is, whether it's currently in sync, and what's open in the review backlog — before it asks a single question.
+| `get_overview` | Live dataset summary organized as scope (counts, date range), freshness (last sync, ingest signals, errored connections), and backlog (needs-review and unmapped counts), plus the household roster |
+| `list_accounts` | Bank accounts (checking, savings, credit cards, loans, investments) with balances, institution names, and currency |
+| `list_categories` | Two-level category taxonomy keyed by slug; the source of valid `category_slug` values |
+| `list_tags` | Current tag vocabulary keyed by slug; the `needs-review` tag is the review-queue handle |
+| `list_users` | Household members with their roles (admin, editor, viewer) |
+| `get_sync_status` | Per-connection sync status and last-sync timestamps |
+| `list_transaction_rules` | The active rule roster |
+
+Calling `get_overview` first gives the agent ambient context about your household's financial state — how big the dataset is, whether it's currently in sync, and what's open in the review backlog — before it asks a single question.
+
+### Operating guidance
+
+The near-static markdown that teaches an agent how to drive the server (the rule DSL grammar, the review playbook, report-format conventions) is served by a single `get_reference` tool, keyed by `kind`:
+
+| `kind` | What it returns |
+|---|---|
+| `instructions` | Data model overview and how the tool surface is organized |
+| `rule-dsl` | Reference grammar for transaction rules: condition fields, action types, priority bands, and provider quirks |
+| `review-guidelines` | Guidelines for reviewing transactions and creating categorization rules; editable from the MCP Settings page |
+| `report-format` | Templates and formatting rules for agent-submitted reports; editable from the MCP Settings page |
+
+`get_reference` returns markdown. The `instructions`, `review-guidelines`, and `report-format` documents reflect any operator customization made on the MCP Settings page; `rule-dsl` is the fixed grammar.
 
 ## What agents can do
 

diff --git a/mcp/reference/categorization.mdx b/mcp/reference/categorization.mdx
@@ -82,4 +82,4 @@ Category writes follow the precedence **user > agent > rule**. If a transaction'
 
 To categorize in bulk by applying a stored rule to existing transactions, use `apply_rules`. Pass a `rule_id` to run one rule in isolation, or omit it to run the full active-rule pipeline in priority order.
 
-See [Rules (write)](/mcp/reference/rules-write) for the other rules write tools (`create_transaction_rule`, `update_transaction_rule`, `delete_transaction_rule`, `batch_create_rules`).
+See [Rules (write)](/mcp/reference/rules-write) for the other rules write tools (`create_transaction_rule` — accepts a `rules` array for batch creation, `update_transaction_rule`, `delete_transaction_rule`).
diff --git a/mcp/reference/conventions.mdx b/mcp/reference/conventions.mdx
@@ -118,7 +118,7 @@ Comma-separated values in `search` are ORed. `search=starbucks,dunkin` matches e
 
 ## Tag filters
 
-`query_transactions` and `count_transactions` accept two tag filters:
+`query_transactions` accepts two tag filters (also honored when called with `count_only: true`):
 
 - `tags` — array, AND semantics. All tags must be present.
 - `any_tag` — array, OR semantics. At least one tag must match.
@@ -140,6 +140,6 @@ The review queue is just `tags=["needs-review"]`.
 
 - List tools default to `limit=50`, max 500.
 - `update_transactions` caps at 50 operations per call.
-- `batch_create_rules` caps at 100 items.
+- `create_transaction_rule` accepts 1–100 rules per call via its `rules` array.
 
 Exceeding a cap returns an error; the server does not silently truncate.
diff --git a/mcp/reference/overview.mdx b/mcp/reference/overview.mdx
@@ -52,37 +52,50 @@ Entity IDs in MCP responses are compact 8-character base62 strings (e.g., `k7Xm9
 
 This differs from the REST API, which returns both `id` (UUID) and `short_id` on every record. If you're cross-referencing between an agent session and the admin UI, remember that what the agent sees as `id` is what the UI calls `short_id`.
 
-## Resources
+## Reads-as-tools, no MCP resources
 
-MCP resources are static or live documents the server exposes alongside tools. Breadbox serves nine, each annotated with an audience (`assistant`-only by default; the four with real attach-in-chat flows are dual-audience for both `user` and `assistant`), a priority, and a `lastModified` timestamp (build time for static prompts, read time for live data).
+Earlier versions of Breadbox exposed the orientation data and the operating-guidance docs as a parallel `breadbox://` resources surface. That surface has been retired entirely — the registry advertises **0 resources, 35 tools**. Resources weren't visible to MCP clients that can't call `resources/list` (notably Claude.ai), so every read is now a tool call.
 
-| URI | MIME | Audience | What it returns |
-| --- | --- | --- | --- |
-| `breadbox://overview` | `application/json` | user, assistant | Live dataset summary clustered as `scope`, `freshness`, and `backlog`, plus the household `users` roster |
-| `breadbox://accounts` | `application/json` | user, assistant | Bank accounts (checking, savings, credit cards, loans, investments) with balances, institution names, and currency |
-| `breadbox://categories` | `application/json` | assistant | Two-level category taxonomy keyed by slug; source for valid `category_slug` values when categorizing or authoring rules |
-| `breadbox://tags` | `application/json` | assistant | Current tag vocabulary keyed by slug; the `needs-review` tag is the review-queue handle |
-| `breadbox://users` | `application/json` | assistant | Household members with their roles (admin, editor, viewer) |
-| `breadbox://sync-status` | `application/json` | assistant | Per-connection sync status and last-sync timestamps |
-| `breadbox://review-guidelines` | `text/markdown` | user, assistant | Guidance for reviewing transactions and creating rules (user-editable in `/mcp` admin) |
-| `breadbox://report-format` | `text/markdown` | user, assistant | Report structure templates used by `submit_report` (user-editable) |
-| `breadbox://rule-dsl` | `text/markdown` | assistant | Reference grammar for transaction rules: condition fields, action types, priority bands, sync vs retroactive semantics, and provider quirks |
+The migration is mechanical:
+
+| Old resource URI | Now |
+| --- | --- |
+| `breadbox://overview` | `get_overview` tool |
+| `breadbox://accounts` | `list_accounts` tool |
+| `breadbox://categories` | `list_categories` tool |
+| `breadbox://tags` | `list_tags` tool |
+| `breadbox://users` | `list_users` tool |
+| `breadbox://sync-status` | `get_sync_status` tool |
+| `breadbox://rules` (rules list) | `list_transaction_rules` tool |
+| `breadbox://instructions` | `get_reference` tool, `kind=instructions` |
+| `breadbox://rule-dsl` | `get_reference` tool, `kind=rule-dsl` |
+| `breadbox://review-guidelines` | `get_reference` tool, `kind=review-guidelines` |
+| `breadbox://report-format` | `get_reference` tool, `kind=report-format` |
+
+A new agent is expected to call `get_overview` first to orient itself, and to call `get_reference(kind="review-guidelines")` before processing review work.
 
-The live `accounts`, `categories`, `tags`, `users`, and `sync-status` resources replace what would otherwise be redundant `list_*` tool calls — agents can read them on connect instead of paying for a round-trip per list.
+### Guidance docs via `get_reference`
 
-Agents are expected to read `breadbox://overview` first to orient themselves, and to read `breadbox://review-guidelines` before processing review work.
+`get_reference` is a single read tool that serves the near-static markdown that teaches an agent how to drive the server. Pass a `kind`:
 
-### `breadbox://overview` shape
+| `kind` | Returns |
+| --- | --- |
+| `instructions` | Data-model + conventions overview, how the tool surface is organized. |
+| `rule-dsl` | The full transaction-rule condition grammar, action types, pipeline-stage ordering, and sync-vs-retroactive semantics. Fixed grammar — not operator-customizable. |
+| `review-guidelines` | Principles for reviewing transactions and creating rules. Reflects operator customization from the MCP Settings page. |
+| `report-format` | Structure and formatting conventions for `submit_report`. Reflects operator customization. |
 
-The overview resource returns a JSON object with four top-level keys:
+The response is a single markdown content block.
+
+### `get_overview` shape
+
+`get_overview` returns a JSON object with four top-level keys:
 
 - `users` — minimal household roster (`id`, `name`).
 - `scope` — dataset size: `transaction_count`, `account_count`, `category_count`, `earliest_transaction_date`, `latest_transaction_date`.
 - `freshness` — ingest-time signals: `last_sync_at` (most recent successful sync across active connections), `errored_connection_count`, `pending_transaction_count`, `transactions_added_last_24h`, `transactions_added_last_7d`. The `transactions_added_last_*` counters track when Breadbox first ingested each row, not when the underlying transaction occurred.
 - `backlog` — what's open: `needs_review_count` (transactions tagged `needs-review`) and `unmapped_transaction_count` (transactions with no category).
 
-The 30-day spending summary, the per-connection list, and the `accounts_by_type` histogram that earlier versions of this resource returned have been removed — read `breadbox://accounts`, `breadbox://sync-status`, or call `transaction_summary` for that detail.
-
 ## Error shape
 
 Tool errors return a standard MCP call result with `isError: true` and a single text content block containing JSON:
@@ -103,7 +116,7 @@ A complete list of every tool Breadbox exposes, grouped by domain. Tools without
 
 **Data access (read)**
 
-- Overview: `get_overview` — household snapshot; mirrors `breadbox://overview`.
+- Overview: `get_overview` — household snapshot (scope, freshness, backlog).
 - Transactions: [`query_transactions`, `transaction_summary`, `list_annotations`](/mcp/reference/transactions)
 - Accounts and users: [`list_accounts`, `list_users`](/mcp/reference/accounts)
 - Categories: [`list_categories`](/mcp/reference/categories)
@@ -117,7 +130,7 @@ A complete list of every tool Breadbox exposes, grouped by domain. Tools without
 
 **Mutations (write)**
 
-- Transactions: [`update_transactions`](/mcp/reference/transactions-write) — compound write for category sets, tag adds/removes, and comments.
+- Transactions: [`update_transactions`](/mcp/reference/transactions-write) — compound write for category sets, tag adds/removes, flag toggles, and comments.
 - Transaction metadata: `set_transaction_metadata`
 - Rules: [`create_transaction_rule`, `update_transaction_rule`, `delete_transaction_rule`, `apply_rules`](/mcp/reference/rules-write)
 - Tags: [`create_tag`, `update_tag`, `delete_tag`](/mcp/reference/tags-write)

diff --git a/mcp/reference/reports.mdx b/mcp/reference/reports.mdx
@@ -18,7 +18,7 @@ The `title` IS the message — it's rendered as the primary line in the dashboar
 
 The `body` is where structure, headers, and detail go — the UI renders markdown with `##` section headers, bullet lists, tables, and inline transaction links (`[Transaction Name](/transactions/ID)`).
 
-Read `breadbox://report-format` for the full style guide and report templates (review report, spending report, anomaly report).
+Call `get_reference(kind="report-format")` for the full style guide and report templates (review report, spending report, anomaly report).
 
 ### Parameters
Original file line number	Diff line number	Diff line change
Expand Up		@@ -82,4 +82,4 @@ Category writes follow the precedence user > agent > rule. If a transaction'

		To categorize in bulk by applying a stored rule to existing transactions, use `apply_rules`. Pass a `rule_id` to run one rule in isolation, or omit it to run the full active-rule pipeline in priority order.

		See [Rules (write)](/mcp/reference/rules-write) for the other rules write tools (`create_transaction_rule`, `update_transaction_rule`, `delete_transaction_rule`, `batch_create_rules`).
		See [Rules (write)](/mcp/reference/rules-write) for the other rules write tools (`create_transaction_rule` — accepts a `rules` array for batch creation, `update_transaction_rule`, `delete_transaction_rule`).