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

## run_workspace_sql

Run one read-only SELECT against the workspace's curated SQL views, or list those views, their columns, and the query limits.

Use for ad-hoc reporting across campaigns, leads, inboxes, threads, and sends when no dedicated tool answers the question. Call without a query first to discover the views and columns, including current-address SEG detection/vendor/provenance on leads and frozen send-time attribution. Filter campaigns and SEG vendors with SQL; unknown detection is not confirmed no-SEG.

Never for writes, catalog introspection, or other workspaces: only a single SELECT over the curated views is accepted, results are capped at 10,000 rows and 8 MiB, and the workspace must have the SQL feature enabled.

Scopes: sql:query

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"
    },
    "parameters": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "string",
            "minLength": 0,
            "maxLength": 4096
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          },
          {
            "type": "null"
          }
        ]
      },
      "maxItems": 32
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20000
    }
  },
  "required": [
    "workspaceId"
  ],
  "patternProperties": {
    "^(?!(?:workspaceId|parameters|query)$)[\\s\\S]*$": false
  },
  "additionalProperties": true,
  "propertyNames": {
    "type": "string",
    "enum": [
      "workspaceId",
      "parameters",
      "query"
    ]
  }
}
```

### 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"
    },
    "parameters": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "string",
            "minLength": 0,
            "maxLength": 4096
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          },
          {
            "type": "null"
          }
        ]
      },
      "maxItems": 32
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20000
    }
  },
  "required": [
    "workspaceId"
  ],
  "patternProperties": {
    "^(?!(?:workspaceId|parameters|query)$)[\\s\\S]*$": false
  },
  "additionalProperties": true,
  "propertyNames": {
    "type": "string",
    "enum": [
      "workspaceId",
      "parameters",
      "query"
    ]
  }
}
```

### Output schema (structuredContent)

```json
{
  "$defs": {
    "SqlSchemaResult": {
      "type": "object",
      "properties": {
        "tables": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "description": {
                "type": "string",
                "minLength": 0,
                "maxLength": 4096
              },
              "columns": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 128
                    },
                    "type": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 128
                    },
                    "description": {
                      "type": "string",
                      "minLength": 0,
                      "maxLength": 4096
                    }
                  },
                  "required": [
                    "name",
                    "type",
                    "description"
                  ],
                  "patternProperties": {
                    "^(?!(?:name|type|description)$)[\\s\\S]*$": false
                  },
                  "additionalProperties": true,
                  "propertyNames": {
                    "type": "string",
                    "enum": [
                      "name",
                      "type",
                      "description"
                    ]
                  }
                }
              }
            },
            "required": [
              "name",
              "description",
              "columns"
            ],
            "patternProperties": {
              "^(?!(?:name|description|columns)$)[\\s\\S]*$": false
            },
            "additionalProperties": true,
            "propertyNames": {
              "type": "string",
              "enum": [
                "name",
                "description",
                "columns"
              ]
            }
          }
        },
        "limits": {
          "type": "object",
          "properties": {
            "statementTimeoutSeconds": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "tempFileLimitMb": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "maxRows": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "rateLimitPerSecond": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "maxConcurrentQueries": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            }
          },
          "required": [
            "statementTimeoutSeconds",
            "tempFileLimitMb",
            "maxRows",
            "rateLimitPerSecond",
            "maxConcurrentQueries"
          ],
          "patternProperties": {
            "^(?!(?:statementTimeoutSeconds|tempFileLimitMb|maxRows|rateLimitPerSecond|maxConcurrentQueries)$)[\\s\\S]*$": false
          },
          "additionalProperties": true,
          "propertyNames": {
            "type": "string",
            "enum": [
              "statementTimeoutSeconds",
              "tempFileLimitMb",
              "maxRows",
              "rateLimitPerSecond",
              "maxConcurrentQueries"
            ]
          }
        }
      },
      "required": [
        "tables",
        "limits"
      ],
      "patternProperties": {
        "^(?!(?:tables|limits)$)[\\s\\S]*$": false
      },
      "additionalProperties": true,
      "propertyNames": {
        "type": "string",
        "enum": [
          "tables",
          "limits"
        ]
      }
    },
    "Union_": {
      "anyOf": [
        {
          "type": "null"
        },
        {
          "type": "boolean"
        },
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Union_"
          }
        },
        {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/Union_"
          }
        }
      ]
    },
    "SqlQueryResult": {
      "type": "object",
      "properties": {
        "columns": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "type": {
                "anyOf": [
                  {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "name",
              "type"
            ],
            "patternProperties": {
              "^(?!(?:name|type)$)[\\s\\S]*$": false
            },
            "additionalProperties": true,
            "propertyNames": {
              "type": "string",
              "enum": [
                "name",
                "type"
              ]
            }
          }
        },
        "rows": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/$defs/Union_"
            }
          },
          "maxItems": 10000
        },
        "rowCount": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "truncated": {
          "type": "boolean"
        },
        "executionMs": {
          "type": "number",
          "minimum": 0
        }
      },
      "required": [
        "columns",
        "rows",
        "rowCount",
        "truncated",
        "executionMs"
      ],
      "patternProperties": {
        "^(?!(?:columns|rows|rowCount|truncated|executionMs)$)[\\s\\S]*$": false
      },
      "additionalProperties": true,
      "propertyNames": {
        "type": "string",
        "enum": [
          "columns",
          "rows",
          "rowCount",
          "truncated",
          "executionMs"
        ]
      }
    }
  },
  "type": "object",
  "anyOf": [
    {
      "allOf": [
        {
          "anyOf": [
            {
              "$ref": "#/$defs/SqlSchemaResult"
            },
            {
              "$ref": "#/$defs/SqlQueryResult"
            }
          ]
        },
        {
          "type": "object"
        }
      ]
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "allOf": [
            {
              "anyOf": [
                {
                  "$ref": "#/$defs/SqlSchemaResult"
                },
                {
                  "$ref": "#/$defs/SqlQueryResult"
                }
              ]
            },
            {
              "not": {
                "type": "object"
              }
            }
          ]
        }
      },
      "required": [
        "data"
      ],
      "additionalProperties": false
    }
  ]
}
```

### Underlying API operations

- `sql.query`: `POST /v1/workspaces/:workspaceId/sql/query`
- `sql.schema`: `GET /v1/workspaces/:workspaceId/sql/schema`