Skip to main content
Tag CRUD. In most cases agents don’t need these — adding a tag to a transaction auto-registers it. Use these when you need to set a custom display name, color, icon, or description up front, or to rename/retire a tag. All tools on this page are Write scope and require session_id + reason.
Tag-record CRUD is MCP-only today. The REST equivalents for POST/PUT/DELETE /api/v1/tags are not yet exposed. The REST Tags API covers listing tags and attaching/detaching them from transactions; tag-record management stays on the admin dashboard and these MCP tools.

​
create_tag

Register a new tag in the system. Use when you need to set display_name, color, icon, or description up front. Most of the time agents can skip this — add_transaction_tag or update_transactions with a new slug auto-creates the tag.

​
Parameters

​
slug
string
required
Tag slug. Regex: ^[a-z0-9][a-z0-9\-:]*[a-z0-9]$. Examples: needs-review, subscription:monthly.
​
display_name
string
required
Human-readable name.
​
description
string
Optional description.
​
color
string
CSS color used for chip rendering (e.g. #4f46e5).
​
icon
string
Lucide icon name (e.g. inbox).
​
session_id
string
required
​
reason
string
required

​
Example input

{
  "session_id": "s9Xm2pQk",
  "reason": "setting up recurring-charges tracking",
  "slug": "subscription:monthly",
  "display_name": "Monthly Subscription",
  "description": "Recurring monthly charge.",
  "color": "#8B5CF6",
  "icon": "refresh-cw"
}

​
Example output

{
  "id": "t2Yn0qR3",
  "slug": "subscription:monthly",
  "display_name": "Monthly Subscription",
  "description": "Recurring monthly charge.",
  "color": "#8B5CF6",
  "icon": "refresh-cw",
  "created_at": "2026-04-23T14:40:00Z"
}

​
update_tag

Update a tag’s mutable fields (display_name, description, color, icon). Slug is immutable — to rename, create a new tag, bulk re-tag affected transactions, and delete the old one. Identify the tag by UUID, short ID, or slug.

​
Parameters

​
id
string
required
Tag UUID, short ID, or slug.
​
display_name
string
New display name.
​
description
string
New description.
​
color
string
New color. Pass empty string to clear.
​
icon
string
New icon. Pass empty string to clear.
​
session_id
string
required
​
reason
string
required

​
Example input

{
  "session_id": "s9Xm2pQk",
  "reason": "updating color to match household convention",
  "id": "subscription:monthly",
  "color": "#4f46e5"
}

​
Example output

{
  "id": "t2Yn0qR3",
  "slug": "subscription:monthly",
  "display_name": "Monthly Subscription",
  "description": "Recurring monthly charge.",
  "color": "#4f46e5",
  "icon": "refresh-cw"
}

​
delete_tag

Delete a tag. Cascades to transaction_tags — the tag is removed from every transaction it was attached to. Annotations that reference the tag keep their rows with tag_id=NULL, preserving the audit trail.

​
Parameters

​
id
string
required
Tag UUID, short ID, or slug.
​
session_id
string
required
​
reason
string
required

​
Example input

{
  "session_id": "s9Xm2pQk",
  "reason": "retiring deprecated workflow tag",
  "id": "old-workflow-tag"
}

​
Example output

{
  "deleted": true,
  "id": "old-workflow-tag"
}