# MCP tool reference

1 callable tools.

Use tools/call at https://mcp.schedulerzero.com/mcp with the exact tool name and arguments below. The /tools/ paths in this view are documentation identifiers, not HTTP endpoints. Request execution is disabled for this reference.

Inputs are shown for personal API keys (bound) and for OAuth/delegated agents. Output schemas describe MCP structuredContent: native objects pass through; arrays, scalars and null use a data wrapper. Text content retains the native JSON result.

[Connect a client](/mcp/connect) · [Authentication and authorization](/authentication) · [Generated auth guide](/auth.md) · [Download tool catalog](/mcp-catalog.json) · [Agent documentation](/llms.txt)

## list_thread_label_history

Read a conversation's reply-label history, newest first (default 50 events, limit up to 100). Returns added/removed events with snapshotted label names/colors, source, actor and time; multiple labels may coexist, so this is not an atomic from/to status change. Pass nextCursor unchanged for the next page.

Use to audit which labels were added or removed on one conversation. Call list_unibox_threads first, then use the selected item's id as threadId and organizationId as workspaceId (not providerThreadId). The native REST thread list returns the same IDs.

Do not infer unrecorded history or a complete historical label set: events before tracking began were not backfilled. This is conversation history, not a single-valued lead status.

Scopes: unibox:read

Risk: read; confirmation: none; idempotency: none.

### Input schema (personal API key)

```json
{
  "type": "object",
  "properties": {
    "workspaceId": {
      "type": "string",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
      "format": "uuid"
    },
    "threadId": {
      "type": "string",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
      "format": "uuid"
    },
    "cursor": {
      "$ref": "#/$defs/Cursor"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "workspaceId",
    "threadId"
  ],
  "patternProperties": {
    "^(?!(?:workspaceId|threadId|cursor|limit)$)[\\s\\S]*$": false
  },
  "additionalProperties": true,
  "propertyNames": {
    "type": "string",
    "enum": [
      "workspaceId",
      "threadId",
      "cursor",
      "limit"
    ]
  },
  "$defs": {
    "Cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    }
  }
}
```

### Input schema (OAuth / delegated agent)

```json
{
  "type": "object",
  "properties": {
    "workspaceId": {
      "type": "string",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
      "format": "uuid"
    },
    "threadId": {
      "type": "string",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
      "format": "uuid"
    },
    "cursor": {
      "$ref": "#/$defs/Cursor"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "workspaceId",
    "threadId"
  ],
  "patternProperties": {
    "^(?!(?:workspaceId|threadId|cursor|limit)$)[\\s\\S]*$": false
  },
  "additionalProperties": true,
  "propertyNames": {
    "type": "string",
    "enum": [
      "workspaceId",
      "threadId",
      "cursor",
      "limit"
    ]
  },
  "$defs": {
    "Cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    }
  }
}
```

### Output schema (structuredContent)

```json
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/$defs/OpaqueId"
          },
          "threadId": {
            "type": "string",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
            "format": "uuid"
          },
          "labelId": {
            "$ref": "#/$defs/ThreadLabelId"
          },
          "labelType": {
            "type": "string",
            "enum": [
              "custom",
              "default"
            ]
          },
          "labelName": {
            "$ref": "#/$defs/ShortText"
          },
          "hexColor": {
            "$ref": "#/$defs/ShortText"
          },
          "action": {
            "type": "string",
            "enum": [
              "added",
              "removed"
            ]
          },
          "source": {
            "$ref": "#/$defs/ShortText"
          },
          "actorUserId": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "actorName": {
            "anyOf": [
              {
                "$ref": "#/$defs/ShortText"
              },
              {
                "type": "null"
              }
            ]
          },
          "occurredAt": {
            "$ref": "#/$defs/UtcDateTimeEncoded"
          }
        },
        "required": [
          "id",
          "threadId",
          "labelId",
          "labelType",
          "labelName",
          "hexColor",
          "action",
          "source",
          "actorUserId",
          "actorName",
          "occurredAt"
        ],
        "patternProperties": {
          "^(?!(?:id|threadId|labelId|labelType|labelName|hexColor|action|source|actorUserId|actorName|occurredAt)$)[\\s\\S]*$": false
        },
        "additionalProperties": true,
        "propertyNames": {
          "type": "string",
          "enum": [
            "id",
            "threadId",
            "labelId",
            "labelType",
            "labelName",
            "hexColor",
            "action",
            "source",
            "actorUserId",
            "actorName",
            "occurredAt"
          ]
        }
      }
    },
    "nextCursor": {
      "anyOf": [
        {
          "$ref": "#/$defs/Cursor"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "items",
    "nextCursor"
  ],
  "patternProperties": {
    "^(?!(?:items|nextCursor)$)[\\s\\S]*$": false
  },
  "additionalProperties": true,
  "propertyNames": {
    "type": "string",
    "enum": [
      "items",
      "nextCursor"
    ]
  },
  "$defs": {
    "OpaqueId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512
    },
    "ThreadLabelId": {
      "type": "string",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
      "format": "uuid"
    },
    "ShortText": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "UtcDateTimeEncoded": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
    },
    "Cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    }
  }
}
```

### Underlying API operations

- `uniboxThreads.listLabelHistory`: `GET /v1/workspaces/:workspaceId/unibox/threads/:threadId/label-history`