delete_tag_definition
Permanently remove a tag definition from an entity type's tag namespace, deleting it from all records. Use to clean up stray or test tags. Requires confirm=true.
Instructions
DESTRUCTIVE & TENANT-WIDE: permanently delete a tag DEFINITION from an entity type's tag namespace (parties / opportunities / projects). Unlike remove_tag_by_id — which detaches a tag from ONE record and leaves the definition intact for others — this removes the definition itself, so the tag disappears from EVERY record that shared it. Use it to clean up stray / mistyped / test tag definitions polluting the tenant-global list. Requires confirm=true. Always read the affected tag first via list_tags and confirm with the user; if you only want to untag one record, use remove_tag_by_id instead. Irreversible (re-creating by name via add_tag mints a brand-new id). Idempotent on retry: {deleted: true, alreadyDeleted: false, entity, tagId} on a fresh delete, or {deleted: true, alreadyDeleted: true, entity, tagId} if the definition was already gone (Capsule's 404 is caught). Endpoint verified empirically (DELETE //tags/{id} → 204).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tagId | No | The tag definition's id (from list_tags, or embed='tags' on a record). NOT an entity id. | |
| entity | Yes | Which entity type. | |
| confirm | Yes | Must be set to true. DESTRUCTIVE & tenant-wide: permanently deletes the tag DEFINITION from this entity type's tag namespace, removing it from EVERY record that shares it — not just one. To detach a tag from a single record while keeping the definition, use remove_tag_by_id instead. Irreversible (the definition is gone; re-creating by name via add_tag mints a new id). Idempotent on retry. |