Tags
Tags tools exposed over the SuperBooks MCP API.
The tags domain exposes 3 tools, 1 of which is destructive.
Destructive tools are hidden from tools/list unless the credential holds
apis.all and the team has enabled destructive AI tools. See
Authentication.
Tools
tags_create
Scope tier: write
Create a new tag for the current team. Names are unique per team — creating a tag whose name already exists throws a clear error (the caller should reuse the existing tag id from tags_list). Tags are minimal: only a name is stored (no color, no description). Returns {id, name}.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | Tag name (e.g., 'urgent', 'project-acme'). Must be unique within the team. |
tags_delete
Scope tier: destructive · Destructive — requires the two-gate check
Permanently delete a tag. DESTRUCTIVE: also removes this tag from every customer, transaction, and tracker project it is attached to. Those customers, transactions, and tracker projects themselves are NOT affected, only their tag links. There is no soft-delete/archive for tags. Returns {id, deleted: true, name} on success, or {id, deleted: false} if the tag was not found for this team. Confirm with the user before calling.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Tag id (UUID) to delete. This action is permanent. |
tags_list
Scope tier: read
List all tags for the current team, ordered by name ascending. Tags are simple {id, name} labels that can be attached to customers, transactions, and tracker projects via their respective tools. No pagination — the tag catalog is typically small.
No parameters.