> For the complete documentation index, see [llms.txt](https://docs.corraldata.com/kb/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.corraldata.com/kb/mcp/tools-reference.md).

# Tools Reference

## Tools Reference

The CorralData MCP Server provides 40 tools organized into ten categories. All tools accept a `customer_name` parameter for multi-tenant environments.

### Schema Discovery

Tools for exploring your database structure. No special roles required.

#### list\_schemas

List all available database schemas with table counts.

| Parameter  | Type   | Required | Default | Description                             |
| ---------- | ------ | -------- | ------- | --------------------------------------- |
| jq\_filter | string | No       | —       | jq expression to transform the response |

#### list\_tables

List tables with brief metadata (description, row count, column count).

| Parameter    | Type   | Required | Default | Description                             |
| ------------ | ------ | -------- | ------- | --------------------------------------- |
| schema\_name | string | No       | —       | Filter tables by schema                 |
| jq\_filter   | string | No       | —       | jq expression to transform the response |

#### describe\_table

Get full column-level detail for a single table including types, keys, and descriptions.

| Parameter               | Type    | Required | Default | Description                              |
| ----------------------- | ------- | -------- | ------- | ---------------------------------------- |
| schema\_name            | string  | Yes      | —       | Schema name (e.g., `public`)             |
| table\_name             | string  | Yes      | —       | Table name (e.g., `orders`)              |
| include\_enums          | boolean | No       | true    | Include enum/category values             |
| include\_sample\_values | boolean | No       | false   | Include up to 3 sample values per column |
| jq\_filter              | string  | No       | —       | jq expression to transform the response  |

#### describe\_tables

Batch describe up to 10 tables in one call. More efficient than calling `describe_table` multiple times.

| Parameter      | Type                                 | Required | Default | Description                             |
| -------------- | ------------------------------------ | -------- | ------- | --------------------------------------- |
| tables         | array of {schema\_name, table\_name} | Yes      | —       | Tables to describe (max 10)             |
| include\_enums | boolean                              | No       | true    | Include enum/category values            |
| jq\_filter     | string                               | No       | —       | jq expression to transform the response |

#### get\_relationships

Get foreign key relationships between tables as a join graph.

| Parameter    | Type    | Required | Default | Description                              |
| ------------ | ------- | -------- | ------- | ---------------------------------------- |
| schema\_name | string  | No       | —       | Filter by schema                         |
| table\_name  | string  | No       | —       | Filter by table (requires schema\_name)  |
| max\_results | integer | No       | 500     | Maximum relationships to return (1–1000) |
| jq\_filter   | string  | No       | —       | jq expression to transform the response  |

#### search\_tables

Search for tables relevant to a natural language query using semantic search.

| Parameter    | Type    | Required | Default | Description            |
| ------------ | ------- | -------- | ------- | ---------------------- |
| query        | string  | Yes      | —       | Natural language query |
| max\_results | integer | No       | 5       | Maximum results (1–10) |

#### get\_column\_values

Get distinct values for a specific column. Useful for building WHERE clauses.

| Parameter    | Type    | Required | Default | Description                                 |
| ------------ | ------- | -------- | ------- | ------------------------------------------- |
| schema\_name | string  | Yes      | —       | Schema name                                 |
| table\_name  | string  | Yes      | —       | Table name                                  |
| column\_name | string  | Yes      | —       | Column name                                 |
| limit        | integer | No       | 50      | Max distinct values (1–100)                 |
| search       | string  | No       | —       | Filter values by pattern (case-insensitive) |

#### get\_query\_context

All-in-one context package for writing SQL. Given a question, returns relevant tables with pruned columns, join graph, and query hints.

| Parameter   | Type    | Required | Default | Description                              |
| ----------- | ------- | -------- | ------- | ---------------------------------------- |
| question    | string  | Yes      | —       | Natural language question about the data |
| max\_tables | integer | No       | 5       | Max tables to include (1–10)             |

***

### SQL Execution

Tools for running and validating SQL queries. No special roles required.

#### execute\_sql

Execute a read-only SQL query against the data warehouse.

| Parameter   | Type    | Required | Default | Description                                                          |
| ----------- | ------- | -------- | ------- | -------------------------------------------------------------------- |
| sql\_query  | string  | Yes      | —       | The SQL query to execute                                             |
| date\_range | object  | No       | —       | Optional `{start, end}` in YYYY-MM-DD format                         |
| max\_rows   | integer | No       | 1000    | Max rows to return (1–10,000). Results exceeding this are truncated. |

#### lint\_sql

Lint a SQL query and optionally auto-fix formatting issues.

| Parameter | Type    | Required | Default    | Description                                                                       |
| --------- | ------- | -------- | ---------- | --------------------------------------------------------------------------------- |
| query     | string  | Yes      | —          | The SQL query to lint                                                             |
| dialect   | string  | No       | PostgreSQL | SQL dialect (PostgreSQL, Snowflake, Redshift, Databricks, MSSQL, MySQL, BigQuery) |
| auto\_fix | boolean | No       | true       | Auto-fix formatting issues                                                        |

#### validate\_widget\_query

Validate whether a SQL query result shape is compatible with a widget type. **Requires `widget.edit` role.**

| Parameter    | Type                  | Required | Default | Description                                                                |
| ------------ | --------------------- | -------- | ------- | -------------------------------------------------------------------------- |
| widget\_type | string                | Yes      | —       | Target widget type (e.g., `line-chart`, `number-wo-comparison`)            |
| columns      | array of {name, type} | Yes      | —       | Columns in the query result. Types: `date`, `numeric`, `string`, `unknown` |
| row\_count   | integer               | Yes      | —       | Expected number of rows                                                    |
| query        | string                | No       | —       | SQL query to check for date filter placeholders                            |

***

### Boards

Tools for managing dashboards.

#### list\_boards

List all boards for a customer. Returns summaries by default.

| Parameter     | Type         | Required | Default | Description                             |
| ------------- | ------------ | -------- | ------- | --------------------------------------- |
| show\_details | boolean      | No       | false   | Include board filters and widget list   |
| board\_ids    | array of int | No       | —       | Fetch specific boards by ID             |
| jq\_filter    | string       | No       | —       | jq expression to transform the response |

#### get\_board

Get detailed information about a single board.

| Parameter                | Type    | Required | Default | Description                             |
| ------------------------ | ------- | -------- | ------- | --------------------------------------- |
| board\_id                | integer | Yes      | —       | Board ID                                |
| include\_widgets         | boolean | No       | false   | Include widget details                  |
| include\_widget\_queries | boolean | No       | false   | Include SQL queries in widget details   |
| jq\_filter               | string  | No       | —       | jq expression to transform the response |

#### create\_board

Create a new board. **Requires `board.edit` role.**

| Parameter | Type   | Required | Default | Description                 |
| --------- | ------ | -------- | ------- | --------------------------- |
| name      | string | Yes      | —       | Board name (must be unique) |

#### duplicate\_board

Duplicate a board, optionally to a different customer. Clones the board including all widgets, queries, and settings. Datasets are NOT copied — widget queries keep their original dataset references. Board filters are NOT copied. **Requires `board.edit` role.**

| Parameter            | Type    | Required | Default | Description                                                                                       |
| -------------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------- |
| board\_id            | integer | Yes      | —       | ID of the board to duplicate                                                                      |
| display\_name        | string  | No       | —       | Name for the new board (auto-generated if omitted)                                                |
| target\_customer\_id | integer | No       | —       | Numeric customer ID for cross-customer duplication (use `list_companies` resource to find the ID) |
| nav\_only            | boolean | No       | —       | If true, the duplicated board is navigation-only                                                  |
| parent\_board\_id    | integer | No       | —       | Parent board ID for nested hierarchy                                                              |

#### update\_board

Update an existing board. Only provide fields you want to change. **Requires `board.edit` role.**

| Parameter         | Type    | Required | Default | Description                        |
| ----------------- | ------- | -------- | ------- | ---------------------------------- |
| board\_id         | integer | Yes      | —       | Board ID                           |
| display\_name     | string  | No       | —       | New board name                     |
| position          | integer | No       | —       | Position in navigation             |
| nav\_only         | boolean | No       | —       | Navigation-only board (no widgets) |
| parent\_board\_id | integer | No       | —       | Parent board for hierarchy         |

***

### Widgets

Tools for managing charts, tables, and other visualizations on boards.

#### list\_widgets

List all widgets, optionally filtered to a specific board.

| Parameter        | Type    | Required | Default | Description                             |
| ---------------- | ------- | -------- | ------- | --------------------------------------- |
| board\_id        | integer | No       | —       | Filter to a specific board              |
| include\_queries | boolean | No       | false   | Include SQL queries                     |
| jq\_filter       | string  | No       | —       | jq expression to transform the response |

#### get\_widget

Get full details of a single widget including its SQL query.

| Parameter  | Type    | Required | Default | Description                             |
| ---------- | ------- | -------- | ------- | --------------------------------------- |
| widget\_id | integer | Yes      | —       | Widget ID                               |
| jq\_filter | string  | No       | —       | jq expression to transform the response |

#### create\_widget

Create a new widget on a board. **Requires `widget.edit` role.**

| Parameter     | Type    | Required | Default | Description                                                                                                                         |
| ------------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| board\_id     | integer | Yes      | —       | Board to add the widget to                                                                                                          |
| title         | string  | Yes      | —       | Widget title                                                                                                                        |
| widget\_type  | string  | Yes      | —       | Visualization type (e.g., `number-wo-comparison`, `wide-bar-chart-wo-comparison`, `n-series-line-chart`, `uni-table-wo-comparison`) |
| query         | string  | No       | —       | SQL query (required for data widgets)                                                                                               |
| metric\_name  | string  | No       | —       | Metric name (e.g., "Revenue")                                                                                                       |
| format\_type  | string  | No       | —       | Value format: `money`, `percentage`, `time`, `value`, `text`                                                                        |
| tooltip\_text | string  | No       | —       | Tooltip explaining the metric                                                                                                       |
| sort\_order   | integer | No       | —       | Position on board (0 = first)                                                                                                       |
| grid\_width   | string  | No       | —       | Width: `1` (quarter), `2` (half), `4` (full)                                                                                        |
| grid\_height  | string  | No       | —       | Height: `1` (short) to `4` (tall)                                                                                                   |
| preview\_only | boolean | No       | false   | Preview without saving                                                                                                              |
| *...and more* |         |          |         | See full parameter list in API                                                                                                      |

#### update\_widget

Update an existing widget. Only provide fields you want to change. **Requires `widget.edit` role.**

| Parameter     | Type    | Required | Default | Description                                  |
| ------------- | ------- | -------- | ------- | -------------------------------------------- |
| widget\_id    | integer | Yes      | —       | Widget ID                                    |
| title         | string  | No       | —       | New title                                    |
| widget\_type  | string  | No       | —       | Change visualization type                    |
| board\_id     | integer | No       | —       | Move to different board                      |
| sort\_order   | integer | No       | —       | New position on board                        |
| widget\_query | object  | No       | —       | Update query settings (SQL, format, tooltip) |
| *...and more* |         |          |         | See full parameter list in API               |

#### bulk\_update\_widgets

Update multiple widgets in parallel (up to 100). **Requires `widget.edit` role.**

| Parameter | Type                    | Required | Default | Description                                                                                  |
| --------- | ----------------------- | -------- | ------- | -------------------------------------------------------------------------------------------- |
| updates   | array of widget updates | Yes      | —       | List of widget updates (1–100). Each update supports the same parameters as `update_widget`. |

***

### Board Filters

Tools for managing interactive filters on boards.

#### list\_board\_filters

List all board filters with pagination.

| Parameter  | Type    | Required | Default | Description                             |
| ---------- | ------- | -------- | ------- | --------------------------------------- |
| page       | integer | No       | 1       | Page number                             |
| per\_page  | integer | No       | 50      | Results per page (1–250)                |
| jq\_filter | string  | No       | —       | jq expression to transform the response |

#### get\_board\_filter

Get full details of a single board filter including its options.

| Parameter  | Type    | Required | Default | Description                             |
| ---------- | ------- | -------- | ------- | --------------------------------------- |
| filter\_id | integer | Yes      | —       | Filter ID                               |
| jq\_filter | string  | No       | —       | jq expression to transform the response |

#### create\_board\_filter

Create a new board filter. **Requires `board.edit` role.**

| Parameter    | Type         | Required | Default | Description                   |
| ------------ | ------------ | -------- | ------- | ----------------------------- |
| name         | string       | Yes      | —       | Filter name                   |
| filter\_type | string       | Yes      | —       | Filter type                   |
| param\_name  | string       | No       | —       | URL parameter name            |
| board\_ids   | array of int | No       | —       | Boards this filter applies to |
| options      | array        | No       | —       | Static filter options         |
| query        | object       | No       | —       | Dynamic filter query          |

#### update\_board\_filter

Update an existing board filter. **Requires `board.edit` role.**

| Parameter    | Type         | Required | Default | Description               |
| ------------ | ------------ | -------- | ------- | ------------------------- |
| filter\_id   | integer      | Yes      | —       | Filter ID                 |
| name         | string       | No       | —       | New name                  |
| filter\_type | string       | No       | —       | New filter type           |
| board\_ids   | array of int | No       | —       | Update board associations |
| options      | array        | No       | —       | Update filter options     |
| query        | object       | No       | —       | Update dynamic query      |

#### delete\_board\_filter

Permanently delete a board filter. **Requires `board.edit` role.**

| Parameter  | Type    | Required | Default | Description         |
| ---------- | ------- | -------- | ------- | ------------------- |
| filter\_id | integer | Yes      | —       | Filter ID to delete |

***

### Datasets

Tools for managing reusable SQL query definitions.

#### list\_datasets

List all datasets for a customer.

| Parameter     | Type            | Required | Default | Description                             |
| ------------- | --------------- | -------- | ------- | --------------------------------------- |
| limit         | integer         | No       | 100     | Max datasets to return (1–1000)         |
| schema\_names | array of string | No       | —       | Filter by schema names                  |
| include\_sql  | boolean         | No       | false   | Include SQL queries                     |
| jq\_filter    | string          | No       | —       | jq expression to transform the response |

#### create\_dataset

Create a new dataset. **Requires `widget.edit` role.**

| Parameter             | Type   | Required | Default           | Description                                                            |
| --------------------- | ------ | -------- | ----------------- | ---------------------------------------------------------------------- |
| name                  | string | Yes      | —                 | Dataset name (must be unique)                                          |
| description           | string | Yes      | —                 | Description of the dataset                                             |
| query                 | string | Yes      | —                 | SQL query that defines the dataset                                     |
| materialization\_type | string | No       | not\_materialized | `not_materialized`, `materialized_as_view`, or `materialized_as_table` |

#### update\_dataset

Update an existing dataset. **Requires `widget.edit` role.**

| Parameter             | Type    | Required | Default | Description              |
| --------------------- | ------- | -------- | ------- | ------------------------ |
| dataset\_id           | integer | Yes      | —       | Dataset ID               |
| name                  | string  | No       | —       | New name                 |
| description           | string  | No       | —       | New description          |
| query                 | string  | No       | —       | New SQL query            |
| materialization\_type | string  | No       | —       | New materialization type |

***

### Permissions Summary

| Role                      | Tools                                                                                                                                                                                                                                                                                               |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *All authenticated users* | All read-only tools: list/get boards, widgets, filters, datasets, all schema tools, execute\_sql, lint\_sql, get\_query\_context, get\_relationships, list\_customers, list\_services, search\_service\_tools, list\_prompts, get\_prompt, call\_service\_tool (write actions require confirmation) |
| `board.edit`              | create\_board, duplicate\_board, update\_board, create\_board\_filter, update\_board\_filter, delete\_board\_filter, reorder\_board                                                                                                                                                                 |
| `widget.edit`             | create\_widget, update\_widget, bulk\_update\_widgets, validate\_widget\_query, create\_dataset, update\_dataset, create\_data\_app, update\_data\_app, screenshot\_widget                                                                                                                          |
| ai\_metadata.edit         | set\_customer\_prompt                                                                                                                                                                                                                                                                               |

### Board & Widget Utilities

Additional tools for layout control and visual QA.

#### reorder\_board

Set the widget order on a board atomically. Pass the complete ordered list of visible widget IDs. Requires board.edit.

* board\_id (integer, required): ID of the board to reorder
* widget\_ids (array of integer, required): Full ordered list of visible widget IDs

#### screenshot\_widget

Render a widget as an image, useful for visual QA after creating or updating it. No special roles required.

* widget\_id (integer, required): ID of the widget to capture

### Data Apps

Custom HTML/JS widgets that run SQL only through named, pre-registered queries. Requires widget.edit and the customer's data\_apps\_enabled flag.

#### create\_data\_app

Create a Data App widget rendered in a sandboxed iframe. Always preview first, fix warnings, then get user confirmation before persisting.

* board\_id (integer, required): ID of the board to add the widget to
* title (string, required): Widget title
* body\_html (string, required): HTML/JS body rendered in the sandboxed iframe
* queries (array of {name, sql}, required): Named SQL queries the app can run via runNamedQuery
* preview\_only (boolean, default false): Preview without saving

#### update\_data\_app

Update a Data App's content, queries, or sizing. Requires widget.edit.

* widget\_id (integer, required): ID of the data app widget
* body\_html / body\_edits (string / array, optional): Full body, or targeted find/replace patches for small tweaks
* queries (array, optional): Declarative — the submitted list replaces the full query registry

### Connected Services

Tools for working with upstream services connected to the customer's data warehouse (ad platforms, EMRs, CRMs, etc). No special roles required to read; write actions require confirmation.

#### list\_services

List the upstream services connected for this customer — the source of truth for what has live data, and whether write-back access is authenticated.

#### search\_service\_tools

Search tools provided by connected third-party services by natural language query.

* query (string, required): Natural language search for a connected service's tools

#### call\_service\_tool

Execute a connected-service tool by its exact name. Write actions require user confirmation — the first call returns a confirmation\_required result and only runs after approval.

* name (string, required): Exact service tool name (use search\_service\_tools first)
* arguments (object, optional): Arguments to pass to the tool
* confirmed (boolean, default false): Set by the client after the user approves a write action

### AI Configuration

Tools for reading prompt templates and steering AskCorral's behavior for a customer.

#### list\_prompts

List all available prompt templates with metadata.

#### get\_prompt

Get a prompt by name with optional arguments, returned as a rendered messages array.

* name (string, required): Prompt name
* arguments (object, optional): Arguments for the prompt

#### set\_customer\_prompt

Create or update the customer's AI custom-instructions prompt that steers AskCorral. Requires ai\_metadata.edit. Passing an empty string removes the prompt entirely.

* content (string, required): Full prompt text to save

### Account Management

#### list\_customers

List the customer accounts the authenticated user has access to. Single-company users see one row; multi-company users and administrators see their full set. Use this to find the slug to pass as customer\_name on other tools.

* name\_filter (string, optional): Keyword filter by name
* include\_demo (boolean, default false): Include demo customer accounts


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.corraldata.com/kb/mcp/tools-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.