Tag Tools

Tags define structured field schemas that can be applied to thogits. These tools let you manage the full tag lifecycle.

add_tag

Create a new tag with typed fields. Tag names must be unique.

Parameters

Name	Type	Required	Description
name	string	Yes	Tag name (must be unique)
description	string	No	Optional description
fields	object	Yes	Map of field names to Schema type definitions

Schema Types

Type	Format	Example
String	"String"	"title": "String"
Number	"Number"	"priority": "Number"
Boolean	"Boolean"	"completed": "Boolean"
Date	"Date"	"due": "Date"
Reference	"Reference"	"assignee": "Reference"
Select	{"type": "Select", "variants": [...]}	See below
MultiSelect	{"type": "MultiSelect", "variants": [...]}	See below

Select variants can have optional sub-fields:

{
  "type": "Select",
  "variants": [
    "todo",
    "in_progress",
    { "name": "blocked", "fields": { "reason": "String" } },
    "done"
  ]
}

MultiSelect uses a flat array of variant names:

{
  "type": "MultiSelect",
  "variants": ["Low", "Medium", "High", "Critical"]
}

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_tag",
    "arguments": {
      "name": "Task",
      "description": "A work item with status tracking",
      "fields": {
        "status": {
          "type": "Select",
          "variants": [
            "todo",
            "in_progress",
            { "name": "blocked", "fields": { "reason": "String" } },
            "done"
          ]
        },
        "priority": "Number",
        "due": "Date",
        "labels": {
          "type": "MultiSelect",
          "variants": ["bug", "feature", "docs"]
        }
      }
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"id\": \"01JEXAMPLE00000000000TAGID\",\n  \"name\": \"Task\",\n  \"description\": \"A work item with status tracking\",\n  \"fields\": { \"status\": { \"type\": \"Select\", \"variants\": [...] }, \"priority\": \"Number\", \"due\": \"Date\", \"labels\": { \"type\": \"MultiSelect\", \"variants\": [\"bug\", \"feature\", \"docs\"] } },\n  \"schema_version\": 1,\n  \"created_at\": \"2025-01-15T10:00:00Z\",\n  \"updated_at\": \"2025-01-15T10:00:00Z\"\n}"
      }
    ]
  }
}

---

get_tag

Get a tag by its ID.

Parameters

Name	Type	Required	Description
tag_id	string	Yes	Tag ULID

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_tag",
    "arguments": {
      "tag_id": "01JEXAMPLE00000000000TAGID"
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"id\": \"01JEXAMPLE00000000000TAGID\",\n  \"name\": \"Task\",\n  \"description\": \"A work item with status tracking\",\n  \"fields\": { ... },\n  \"schema_version\": 1,\n  \"created_at\": \"2025-01-15T10:00:00Z\",\n  \"updated_at\": \"2025-01-15T10:00:00Z\"\n}"
      }
    ]
  }
}

---

edit_tag

Update a tag’s name, description, and/or field schema. Changing fields increments the tag’s schema_version. Thogits using this tag retain their old schema version until their field values are updated.

Parameters

Name	Type	Required	Description
tag_id	string	Yes	Tag ULID
name	string	No	New tag name
description	string	No	New description
fields	object	No	New field definitions (triggers schema version increment)

Caution

Changing fields increments schema_version. Use get_outdated_thogit_tags to find thogits that need migration after a schema change.

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "edit_tag",
    "arguments": {
      "tag_id": "01JEXAMPLE00000000000TAGID",
      "fields": {
        "status": {
          "type": "Select",
          "variants": [
            "todo",
            "in_progress",
            "in_review",
            { "name": "blocked", "fields": { "reason": "String" } },
            "done"
          ]
        },
        "priority": "Number",
        "due": "Date",
        "labels": {
          "type": "MultiSelect",
          "variants": ["bug", "feature", "docs", "chore"]
        }
      }
    }
  }
}

// Response — note schema_version incremented to 2
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"id\": \"01JEXAMPLE00000000000TAGID\",\n  \"name\": \"Task\",\n  \"schema_version\": 2,\n  ...\n}"
      }
    ]
  }
}

---

delete_tag

Delete a tag by ID. Fails if the tag is currently applied to any thogit.

Parameters

Name	Type	Required	Description
tag_id	string	Yes	Tag ULID

Caution

You must remove the tag from all thogits before deleting it. Use bulk_remove_tag to remove it from all thogits at once.

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "delete_tag",
    "arguments": {
      "tag_id": "01JEXAMPLE00000000000TAGID"
    }
  }
}

// Response — returns the deleted tag
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"id\": \"01JEXAMPLE00000000000TAGID\",\n  \"name\": \"Task\",\n  ...\n}"
      }
    ]
  }
}

---

get_tags

List all tags, or search with an optional filter. Omit filter to get all tags.

Parameters

Name	Type	Required	Description
filter	TagFilter	No	Optional filter. Omit to list all tags.

TagFilter Format

Filter	Example
Full-text search	{"search": "task"}
Name contains	{"name": {"contains": "pri"}}
Exact name match	{"name": {"equals": "Task"}}
Logical AND	{"and": [{"search": "work"}, {"name": {"contains": "T"}}]}
Logical OR	{"or": [{"name": {"equals": "Task"}}, {"name": {"equals": "Bug"}}]}
Logical NOT	{"not": {"name": {"contains": "test"}}}

Example

// Request — search for tags with "task" in name or description
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_tags",
    "arguments": {
      "filter": { "search": "task" }
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[\n  {\n    \"id\": \"01JEXAMPLE00000000000TAGID\",\n    \"name\": \"Task\",\n    \"description\": \"A work item with status tracking\",\n    \"fields\": { ... },\n    \"schema_version\": 1\n  }\n]"
      }
    ]
  }
}