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

Run one read-only SELECT against the Organization'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 children of another Organization: all selected children must independently grant sql:query and enable SQL; omitted workspaceIds selects all eligible children (maximum 100). Explicit IDs are all validated. Only a single SELECT over the curated views is accepted, results are capped at 10,000 rows and 8 MiB.

Scopes: orgAnalytics:read, sql:query

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

### Input schema (personal API key)

```json
{
  "type": "object",
  "properties": {
    "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"
    },
    "workspaceIds": {
      "type": "array",
      "items": {
        "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"
      },
      "minItems": 1,
      "maxItems": 100
    },
    "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": [
    "organizationId"
  ],
  "patternProperties": {
    "^(?!(?:organizationId|workspaceIds|parameters|query)$)[\\s\\S]*$": false
  },
  "additionalProperties": true,
  "propertyNames": {
    "type": "string",
    "enum": [
      "organizationId",
      "workspaceIds",
      "parameters",
      "query"
    ]
  }
}
```

### Input schema (OAuth / delegated agent)

```json
{
  "type": "object",
  "properties": {
    "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"
    },
    "workspaceIds": {
      "type": "array",
      "items": {
        "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"
      },
      "minItems": 1,
      "maxItems": 100
    },
    "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": [
    "organizationId"
  ],
  "patternProperties": {
    "^(?!(?:organizationId|workspaceIds|parameters|query)$)[\\s\\S]*$": false
  },
  "additionalProperties": true,
  "propertyNames": {
    "type": "string",
    "enum": [
      "organizationId",
      "workspaceIds",
      "parameters",
      "query"
    ]
  }
}
```

### Output schema (structuredContent)

```json
{
  "$defs": {
    "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": [
            {
              "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"
                    ]
                  }
                },
                "workspaces": {
                  "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"
                      },
                      "name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "id",
                      "name"
                    ],
                    "patternProperties": {
                      "^(?!(?:id|name)$)[\\s\\S]*$": false
                    },
                    "additionalProperties": true,
                    "propertyNames": {
                      "type": "string",
                      "enum": [
                        "id",
                        "name"
                      ]
                    }
                  }
                }
              },
              "required": [
                "tables",
                "limits",
                "workspaces"
              ],
              "patternProperties": {
                "^(?!(?:tables|limits|workspaces)$)[\\s\\S]*$": false
              },
              "additionalProperties": true,
              "propertyNames": {
                "type": "string",
                "enum": [
                  "tables",
                  "limits",
                  "workspaces"
                ]
              }
            },
            {
              "$ref": "#/$defs/SqlQueryResult"
            }
          ]
        },
        {
          "type": "object"
        }
      ]
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "allOf": [
            {
              "anyOf": [
                {
                  "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"
                        ]
                      }
                    },
                    "workspaces": {
                      "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"
                          },
                          "name": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "name"
                        ],
                        "patternProperties": {
                          "^(?!(?:id|name)$)[\\s\\S]*$": false
                        },
                        "additionalProperties": true,
                        "propertyNames": {
                          "type": "string",
                          "enum": [
                            "id",
                            "name"
                          ]
                        }
                      }
                    }
                  },
                  "required": [
                    "tables",
                    "limits",
                    "workspaces"
                  ],
                  "patternProperties": {
                    "^(?!(?:tables|limits|workspaces)$)[\\s\\S]*$": false
                  },
                  "additionalProperties": true,
                  "propertyNames": {
                    "type": "string",
                    "enum": [
                      "tables",
                      "limits",
                      "workspaces"
                    ]
                  }
                },
                {
                  "$ref": "#/$defs/SqlQueryResult"
                }
              ]
            },
            {
              "not": {
                "type": "object"
              }
            }
          ]
        }
      },
      "required": [
        "data"
      ],
      "additionalProperties": false
    }
  ]
}
```

### Underlying API operations

- `organizationSql.query`: `POST /v1/organizations/:organizationId/sql/query`
- `organizationSql.schema`: `GET /v1/organizations/:organizationId/sql/schema`