The Databricks toolkit lets agents browse Unity Catalog (catalogs, schemas, tables), run SQL on a warehouse, fetch statement results, list warehouses and workspace objects, export notebooks, inspect table lineage, and review query history. Authentication uses a saved connection with either a personal access token (PAT) or an OAuth M2M service principal (client ID + secret).
Add it on the agent Toolkits tab and create or select a Databricks connection.
Prerequisites
- A Databricks workspace and SQL warehouse the agent should use
- Either a PAT, or a service principal client ID and secret, with access to the catalogs and warehouses you need
- An agent you can edit
Setup
- Open the agent → Toolkits → add Databricks.
- Create a connection with:
- Workspace host (required) — for example
https://dbc-xxxx.cloud.databricks.com
- SQL warehouse ID (required)
- Either a personal access token, or client ID + client secret for a service principal
- Save the agent.
@-mention Databricks tools in the personality prompt for catalog and SQL tasks.
Unity Catalog & SQL
| Tool | Description |
|---|
| List Catalogs | Lists Unity Catalog catalogs (paginated). |
| List Schemas | Lists schemas in a catalog. |
| List Tables | Lists tables in a catalog.schema. |
| Get Table | Returns table metadata and column schema. |
| Run SQL | Runs SQL on the configured warehouse. Read-only by default unless writes are explicitly allowed in config. |
| Get Statement Result | Fetches or polls statement result chunks. |
| List Warehouses | Lists SQL warehouses. |
| Query History | Lists recent SQL queries. |
| Get Table Lineage | Returns upstream/downstream table lineage. |
Workspace & API
| Tool | Description |
|---|
| List Workspace Objects | Lists notebooks and folders (bounded recursion). |
| Export Notebook | Exports notebook source. |
| Custom API Call | Calls a Databricks workspace REST endpoint on the same host. |
Use cases
- Discover catalogs and table schemas before writing a query
- Run analytical SQL and summarize results in chat
- Inspect lineage for a table before changing a pipeline
- Export a notebook for review or troubleshooting
Tips
- Access is limited to what the PAT or service principal can see (Unity Catalog grants and warehouse permissions).
- Notebook access can differ from UC table grants — exporting a notebook needs workspace ACLs (
CAN_READ or higher).
- Prefer bounded SQL (
LIMIT, filters) for interactive exploration.
- Store tokens and secrets in a saved connection — do not put them in the personality prompt.
Troubleshooting
| Symptom | What to check |
|---|
| Auth failed | Host URL, token or client credentials, and warehouse ID |
| Table or catalog not found | UC grants for the identity; correct catalog.schema names |
| SQL permission / write errors | Warehouse access; writes may be disabled unless allow_writes is enabled |
| Notebook export fails | Workspace path and CAN_READ (or higher) on the notebook |
| Empty warehouse list | Identity lacks warehouse permissions in the workspace |