Skip to content

docs(mcp): sync mcp-tools-reference.md to the real 35-tool registry #1923

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
canalesb93 merged 1 commit into from
Jun 24, 2026
+21 −143
Merged

docs(mcp): sync mcp-tools-reference.md to the real 35-tool registry #1923

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 21 additions & 143 deletions docs/mcp-tools-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Every tool response is also subject to a **byte cap** (default ~100 KB ≈ 25K t

## Sessions

Before using any tools, agents should call `create_session` to establish a session. This provides the agent with dataset context and server instructions.
Audit sessions are automatic — there is **no** `create_session` tool. Every tool call is logged under a session keyed off your transport connection (the `MCP-Session-Id` header for HTTP, a per-process id for stdio), lazy-created on your first call. To label a specific call, pass an optional `reason` string in `tools/call._meta`. Read `get_overview` at the start of a session for dataset context.

---

Expand Down Expand Up @@ -125,76 +125,9 @@ Read this to see what runs automatically before proposing new rules or reports

---

## Categorization Tools
## Transaction Writes & Annotations

### categorize_transaction (Write)

Set a transaction's category. Creates a category override.

| Parameter | Type | Description |
|-----------|------|-------------|
| `transaction_id` | string | Transaction ID (8-char short ID or UUID) |
| `category_slug` | string | Category slug (e.g., `food_and_drink_groceries`) |

### reset_transaction_category (Write)

Remove a transaction's category override, reverting to the provider's original category.

| Parameter | Type | Description |
|-----------|------|-------------|
| `transaction_id` | string | Transaction ID |

### batch_categorize_transactions (Write)

Categorize multiple transactions at once. Max 500 items per call.

| Parameter | Type | Description |
|-----------|------|-------------|
| `items` | array | Array of `{ transaction_id, category_slug }` pairs |

### bulk_recategorize (Write)

Server-side UPDATE of all transactions matching filters. Requires at least one filter for safety. Moves transactions matching `from_category` (and other filters) to `to_category`.

| Parameter | Type | Description |
|-----------|------|-------------|
| `to_category` | string | Destination category slug (required) |
| `from_category` | string | Optional source category slug filter |
| Plus filters | | Same as `query_transactions` |
| `target_category_slug` | string | Deprecated — use `to_category` |
| `category_slug` | string | Deprecated — use `from_category` |

### import_categories (Write)

Import categories from TSV format. Creates or updates categories.

---

## Tag & Annotation Tools

### list_tags (Read)

The tag vocabulary — see **Reference Data Tools → `list_tags`** above.

### add_transaction_tag (Write)

Attach a tag to a transaction. Auto-creates a persistent tag if the slug is unknown. Idempotent.

| Parameter | Type | Description |
|-----------|------|-------------|
| `transaction_id` | string | UUID or short ID |
| `tag_slug` | string | Tag slug |
| `note` | string | Optional rationale (recorded on the `tag_added` annotation) |

### remove_transaction_tag (Write)

Remove a tag from a transaction. An optional `note` lands on the `tag_removed` annotation. Idempotent.

| Parameter | Type | Description |
|-----------|------|-------------|
| `transaction_id` | string | UUID or short ID |
| `tag_slug` | string | Tag slug |
| `note` | string | Optional rationale for removal — recorded on the audit trail. |
Per-transaction writes — category, tags, comments, flags, and metadata — all flow through `update_transactions` and `set_transaction_metadata`. There are no single-purpose `categorize_transaction` / `add_transaction_tag` / `flag_transaction` tools; they were folded into `update_transactions`.

### update_transactions (Write)

Expand All @@ -218,6 +151,19 @@ Each operation:

Use this to close a review entry: `set category + remove needs-review (with note) + comment` in one call.

### set_transaction_metadata (Write)

Write a transaction's free-form metadata JSONB store — household enrichment that isn't a first-class field (NOT a substitute for category or tags). Returned on every transaction read. Keys are slug-like (max 128 chars); values may be any JSON.

| Parameter | Type | Description |
|-----------|------|-------------|
| `transaction_id` | string | UUID or short ID. Required. |
| `set` | object | Key→value pairs to upsert. **Merged** by default — keys you don't list stay untouched. |
| `unset` | array | Keys to delete (no-op if absent). Applied after `set`. |
| `replace` | bool | When `true`, the result is **exactly** the `set` object (clears every pre-existing key first). `replace:true` with `set` omitted clears all metadata. |

Folds the former `remove_transaction_metadata` / `replace_transaction_metadata` / `clear_transaction_metadata` tools.

### list_annotations (Read)

Return the activity timeline for a transaction. Rows are returned in a `{ "annotations": [...] }` envelope (the MCP `structuredContent` slot requires a JSON record, not a bare array — mirrors the REST `/transactions/{id}/annotations` shape). Each row carries a generic `kind` plus an `action` for the specific event:
Expand Down Expand Up @@ -261,27 +207,27 @@ Branch on `action` when the add-vs-remove distinction matters (e.g. building a t

### create_tag / update_tag / delete_tag (Write)

Admin-only tag CRUD. Agents typically don't need these — `add_transaction_tag` auto-creates tags on demand. Use these to set display name, color, or cascade-delete a tag.
Admin-only tag CRUD. Agents typically don't need these — `update_transactions` auto-creates a tag when an operation's `tags_to_add` references an unknown slug. Use these to set display name, color, or cascade-delete a tag.

---

## Subscriptions (Recurring Series) Tools

### list_series (Read)

List recurring series — thin, rule-maintained entities: each is a surrogate identity (`id`/`short_id`), a `name`, and a `type` (`subscription` | `bill` | `loan` | `other`), plus its `tags`. Membership comes from `assign_series` rules, not a shipped detector. **Lean by default** (`fields` omitted → `overview` projection: `name`, `type`, `tags`); pass `fields=all` for timestamps. Get a series' charges via `query_transactions(series_id=...)`.
List recurring series — thin, rule-maintained entities: each is a surrogate identity (`id`/`short_id`), a `name`, and a `type` (`subscription` | `bill` | `loan` | `other`). Membership comes from `assign_series` rules, not a shipped detector. **Lean by default** (`fields` omitted → `name`, `type`); pass `fields=all` for timestamps. Get a series' charges via `query_transactions(series_id=...)`.

### get_series (Read)

Get one series by short ID or UUID: its `name`, `type`, and `tags`. A series' linked charges come from `query_transactions(series_id=...)`; its governing rules (the `assign_series` rules that define its membership) are visible on the admin Recurring detail page.
Get one series by short ID or UUID: its `name` and `type`. A series' linked charges come from `query_transactions(series_id=...)`; its governing rules (the `assign_series` rules that define its membership) are visible on the admin Recurring detail page.

### assign_series (Write)

Link transactions to a recurring series, creating it if needed — the agent's path for a **one-off** assignment (encode a durable pattern as an `assign_series` **rule** instead when you want future charges to resolve automatically). Provide `series_id` to assign to an existing series, **or** `series_name` + `create_if_missing:true` to mint/resolve one by name (surrogate-first: the same name always resolves the same series). Optional `type` (`subscription`|`bill`|`loan`|`other`) for a minted series. Pass `transaction_ids` (≤50) to back-link members (NULL-fill only — never steals a charge already in another series).

### update_series (Write)

Edit a recurring series in one call: its `name`, `type` (`subscription` | `bill` | `loan` | `other`), and tag membership (`tags_to_add` / `tags_to_remove`). Every field optional — omit to leave unchanged. Renaming onto an existing live series name is rejected (the name is the series' unique mint key). Tags must already exist (`create_tag`); an added tag is materialized onto every linked charge and applied to future members, a removed tag strips the series-inherited copies (a tag a user added directly to a charge survives).
Edit a recurring series' `name` and/or `type` (`subscription` | `bill` | `loan` | `other`). Both optional — omit to leave unchanged. Renaming onto an existing live series name is rejected (the name is the series' unique mint key).

### unlink_series_transactions (Write)

Expand Down Expand Up @@ -447,63 +393,7 @@ Rule 2 sees rule 1's `coffee` tag mid-sync; rule 3 sees both the tag and (if we'

---

## Account Link Tools

Account links connect authorized user cards to primary cardholder accounts for transaction deduplication.

### list_account_links (Read)

List all account links with match statistics.

### create_account_link (Write)

Create a link between a dependent and primary account. Auto-runs initial reconciliation.

| Parameter | Type | Description |
|-----------|------|-------------|
| `dependent_account_id` | string | The authorized user's account |
| `primary_account_id` | string | The cardholder's account |

### delete_account_link (Write)

Delete an account link by ID.

### reconcile_account_link (Write)

Re-run matching for a specific link.

### list_transaction_matches (Read)

List matched transaction pairs for a link.

| Parameter | Type | Description |
|-----------|------|-------------|
| `account_link_id` | string | Account link ID |

### confirm_match (Write)

Confirm a matched transaction pair is correct.

### reject_match (Write)

Reject a matched transaction pair.

---

## Comment & Report Tools

### add_transaction_comment (Write)

Add a comment to a transaction.

| Parameter | Type | Description |
|-----------|------|-------------|
| `transaction_id` | string | Transaction ID |
| `body` | string | Comment text |

### list_transaction_comments (Read) — Deprecated

Deprecated: prefer `list_annotations` with `kinds=['comment']`. Returns the same comment data with renamed fields (`author_*` instead of `actor_*`, `content` lifted out of `payload`). Will be removed in a future release.
## Reports

### submit_report (Write)

Expand All @@ -516,18 +406,6 @@ Submit a report for human review. Reports appear on the admin dashboard.

---

## Sync & Session Tools

### create_session (Write)

Establish a session. Returns dataset context (users, accounts, connection status, pending transaction count) and server instructions. Call this first.

### trigger_sync (Write)

Trigger a manual sync for all active connections.

---

## Resources

Breadbox exposes **no MCP resources** — they were retired entirely (invisible on clients that can't `resources/list`). Everything is a tool:
Expand Down
Loading