# 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_unibox_threads

Find conversations in a Workspace and obtain their local UUIDs for subsequent tools. Returns a bounded page of thread metadata, default 20 and maximum 100 items, with an opaque nextCursor.

Use before list_thread_label_history. Select a conversation using search or folder. showAllEmails defaults to false (managed inbox conversations); set true to include other inbound inbox mail, including manually labeled conversations. Other folders retain their usual rules. Then pass its id as threadId and its organizationId as workspaceId. Pass nextCursor unchanged for another page.

Does not return message bodies or label history. Folder defaults to inbox; choose archived, sent, starred, trash, or warmup when appropriate. Never use providerThreadId as the local threadId.

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"
    },
    "cursor": {
      "$ref": "#/$defs/Cursor"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "search": {
      "$ref": "#/$defs/ShortText"
    },
    "folder": {
      "type": "string",
      "enum": [
        "inbox",
        "sent",
        "archived",
        "starred",
        "warmup",
        "trash"
      ]
    },
    "showAllEmails": {
      "type": "boolean"
    }
  },
  "required": [
    "workspaceId"
  ],
  "patternProperties": {
    "^(?!(?:workspaceId|cursor|limit|search|folder|showAllEmails)$)[\\s\\S]*$": false
  },
  "additionalProperties": true,
  "propertyNames": {
    "type": "string",
    "enum": [
      "workspaceId",
      "cursor",
      "limit",
      "search",
      "folder",
      "showAllEmails"
    ]
  },
  "$defs": {
    "Cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    },
    "ShortText": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    }
  }
}
```

### 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"
    },
    "cursor": {
      "$ref": "#/$defs/Cursor"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "search": {
      "$ref": "#/$defs/ShortText"
    },
    "folder": {
      "type": "string",
      "enum": [
        "inbox",
        "sent",
        "archived",
        "starred",
        "warmup",
        "trash"
      ]
    },
    "showAllEmails": {
      "type": "boolean"
    }
  },
  "required": [
    "workspaceId"
  ],
  "patternProperties": {
    "^(?!(?:workspaceId|cursor|limit|search|folder|showAllEmails)$)[\\s\\S]*$": false
  },
  "additionalProperties": true,
  "propertyNames": {
    "type": "string",
    "enum": [
      "workspaceId",
      "cursor",
      "limit",
      "search",
      "folder",
      "showAllEmails"
    ]
  },
  "$defs": {
    "Cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    },
    "ShortText": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    }
  }
}
```

### Output schema (structuredContent)

```json
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "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"
          },
          "inboxId": {
            "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"
              }
            ]
          },
          "organizationId": {
            "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"
          },
          "subject": {
            "anyOf": [
              {
                "$ref": "#/$defs/LeadStoredText"
              },
              {
                "type": "null"
              }
            ]
          },
          "snippet": {
            "anyOf": [
              {
                "$ref": "#/$defs/LeadStoredText"
              },
              {
                "type": "null"
              }
            ]
          },
          "contact": {
            "type": "object",
            "properties": {
              "emailAddress": {
                "$ref": "#/$defs/EmailAddress"
              },
              "name": {
                "anyOf": [
                  {
                    "$ref": "#/$defs/LeadStoredText"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "leadId": {
                "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"
                  }
                ]
              }
            },
            "required": [
              "emailAddress",
              "name",
              "leadId"
            ],
            "patternProperties": {
              "^(?!(?:emailAddress|name|leadId)$)[\\s\\S]*$": false
            },
            "additionalProperties": true,
            "propertyNames": {
              "type": "string",
              "enum": [
                "emailAddress",
                "name",
                "leadId"
              ]
            }
          },
          "providerThreadId": {
            "$ref": "#/$defs/OpaqueId"
          },
          "provider": {
            "type": "string",
            "enum": [
              "google_workspace",
              "microsoft_365",
              "other"
            ]
          },
          "lastMessageAt": {
            "anyOf": [
              {
                "$ref": "#/$defs/UtcDateTimeEncoded"
              },
              {
                "type": "null"
              }
            ]
          },
          "messageCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "labels": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "$ref": "#/$defs/ThreadLabelId"
                },
                "name": {
                  "$ref": "#/$defs/ShortText"
                },
                "hexColor": {
                  "$ref": "#/$defs/ShortText"
                },
                "sentiment": {
                  "anyOf": [
                    {
                      "type": "string",
                      "enum": [
                        "positive",
                        "negative",
                        "neutral"
                      ]
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "custom",
                    "default"
                  ]
                }
              },
              "required": [
                "id",
                "name",
                "hexColor",
                "sentiment",
                "type"
              ],
              "patternProperties": {
                "^(?!(?:id|name|hexColor|sentiment|type)$)[\\s\\S]*$": false
              },
              "additionalProperties": true,
              "propertyNames": {
                "type": "string",
                "enum": [
                  "id",
                  "name",
                  "hexColor",
                  "sentiment",
                  "type"
                ]
              }
            }
          },
          "assignees": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "userId": {
                  "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"
                },
                "name": {
                  "anyOf": [
                    {
                      "$ref": "#/$defs/LeadStoredText"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "email": {
                  "$ref": "#/$defs/EmailAddress"
                },
                "image": {
                  "anyOf": [
                    {
                      "$ref": "#/$defs/HttpUrl"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "isFormerMember": {
                  "type": "boolean"
                }
              },
              "required": [
                "userId",
                "name",
                "email",
                "image",
                "isFormerMember"
              ],
              "patternProperties": {
                "^(?!(?:userId|name|email|image|isFormerMember)$)[\\s\\S]*$": false
              },
              "additionalProperties": true,
              "propertyNames": {
                "type": "string",
                "enum": [
                  "userId",
                  "name",
                  "email",
                  "image",
                  "isFormerMember"
                ]
              }
            }
          },
          "campaignId": {
            "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"
              }
            ]
          },
          "campaignContactId": {
            "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"
              }
            ]
          },
          "isRead": {
            "type": "boolean"
          },
          "starredAt": {
            "anyOf": [
              {
                "$ref": "#/$defs/UtcDateTimeEncoded"
              },
              {
                "type": "null"
              }
            ]
          },
          "archivedAt": {
            "anyOf": [
              {
                "$ref": "#/$defs/UtcDateTimeEncoded"
              },
              {
                "type": "null"
              }
            ]
          },
          "deletedAt": {
            "anyOf": [
              {
                "$ref": "#/$defs/UtcDateTimeEncoded"
              },
              {
                "type": "null"
              }
            ]
          },
          "folders": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "inbox",
                "sent",
                "archived",
                "starred",
                "warmup",
                "trash"
              ]
            }
          },
          "recentMessages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "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"
                },
                "providerInternalMessageId": {
                  "$ref": "#/$defs/OpaqueId"
                },
                "from": {
                  "$ref": "#/$defs/NonEmptyString"
                },
                "to": {
                  "type": "array",
                  "items": {
                    "$ref": "#/$defs/NonEmptyString"
                  }
                },
                "cc": {
                  "type": "array",
                  "items": {
                    "$ref": "#/$defs/NonEmptyString"
                  }
                },
                "subject": {
                  "anyOf": [
                    {
                      "$ref": "#/$defs/LeadStoredText"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "snippet": {
                  "anyOf": [
                    {
                      "$ref": "#/$defs/LeadStoredText"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "receivedAt": {
                  "$ref": "#/$defs/UtcDateTimeEncoded"
                },
                "isRead": {
                  "type": "boolean"
                },
                "isFromInboxSender": {
                  "type": "boolean"
                }
              },
              "required": [
                "id",
                "providerInternalMessageId",
                "from",
                "to",
                "cc",
                "subject",
                "snippet",
                "receivedAt",
                "isRead",
                "isFromInboxSender"
              ],
              "patternProperties": {
                "^(?!(?:id|providerInternalMessageId|from|to|cc|subject|snippet|receivedAt|isRead|isFromInboxSender)$)[\\s\\S]*$": false
              },
              "additionalProperties": true,
              "propertyNames": {
                "type": "string",
                "enum": [
                  "id",
                  "providerInternalMessageId",
                  "from",
                  "to",
                  "cc",
                  "subject",
                  "snippet",
                  "receivedAt",
                  "isRead",
                  "isFromInboxSender"
                ]
              }
            },
            "maxItems": 20
          }
        },
        "required": [
          "id",
          "inboxId",
          "organizationId",
          "subject",
          "snippet",
          "contact",
          "providerThreadId",
          "provider",
          "lastMessageAt",
          "messageCount",
          "labels",
          "assignees",
          "campaignId",
          "campaignContactId",
          "isRead",
          "starredAt",
          "archivedAt",
          "deletedAt",
          "folders"
        ],
        "patternProperties": {
          "^(?!(?:id|inboxId|organizationId|subject|snippet|contact|providerThreadId|provider|lastMessageAt|messageCount|labels|assignees|campaignId|campaignContactId|isRead|starredAt|archivedAt|deletedAt|folders|recentMessages)$)[\\s\\S]*$": false
        },
        "additionalProperties": true,
        "propertyNames": {
          "type": "string",
          "enum": [
            "id",
            "inboxId",
            "organizationId",
            "subject",
            "snippet",
            "contact",
            "providerThreadId",
            "provider",
            "lastMessageAt",
            "messageCount",
            "labels",
            "assignees",
            "campaignId",
            "campaignContactId",
            "isRead",
            "starredAt",
            "archivedAt",
            "deletedAt",
            "folders",
            "recentMessages"
          ]
        }
      }
    },
    "nextCursor": {
      "anyOf": [
        {
          "$ref": "#/$defs/Cursor"
        },
        {
          "type": "null"
        }
      ]
    },
    "total": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "items",
    "nextCursor"
  ],
  "patternProperties": {
    "^(?!(?:items|nextCursor|total)$)[\\s\\S]*$": false
  },
  "additionalProperties": true,
  "propertyNames": {
    "type": "string",
    "enum": [
      "items",
      "nextCursor",
      "total"
    ]
  },
  "$defs": {
    "LeadStoredText": {
      "type": "string",
      "maxLength": 65536
    },
    "EmailAddress": {
      "type": "string",
      "minLength": 3,
      "maxLength": 320,
      "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
    },
    "OpaqueId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512
    },
    "UtcDateTimeEncoded": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
    },
    "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
    },
    "HttpUrl": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "pattern": "^https?:\\/\\/[^\\s/$.?#][^\\s]*$"
    },
    "NonEmptyString": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "Cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    }
  }
}
```

### Underlying API operations

- `uniboxThreads.list`: `GET /v1/workspaces/:workspaceId/unibox/threads`