> 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

This page lists the CorralData MCP Server's tools by category. Most tools also accept a `customer_name` parameter, which isn't listed in the tables below. If you can reach more than one customer account, use it to pick the account. `list_customers` returns the names you can use.

## Before you start

* **Permissions.** You only see the tools your role allows. Each tool lists the permission it needs; see the [Permissions Summary](#permissions-summary) for how permissions map to CorralData roles.
* **Confirmation.** Tools marked *Makes changes* run when your AI client calls them. Your client's own tool-approval prompt is the safeguard. Writes to connected services (`call_service_tool`) always ask you to confirm.
* **Filtering results.** Many read tools take a `jq_filter` parameter: a [jq](https://jqlang.org/) expression that trims the response before it is returned.

## Schema Discovery

Explore the tables and columns in your data warehouse. `describe_table`, `describe_tables` and `get_column_values` read warehouse data, so they need `sql.execute`.

### list\_schemas

List all available database schemas with table counts.

**Access:** Read-only.

| Parameter  | Type   | Required | Default | Description                                                 |
| ---------- | ------ | -------- | ------- | ----------------------------------------------------------- |
| jq\_filter | string | No       | —       | Optional jq filter applied to `{schemas: [...], count: N}`. |

### list\_tables

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

**Access:** Read-only.

| Parameter    | Type   | Required | Default | Description                                                |
| ------------ | ------ | -------- | ------- | ---------------------------------------------------------- |
| schema\_name | string | No       | —       | Schema name (e.g., 'public', 'analytics')                  |
| jq\_filter   | string | No       | —       | Optional jq filter applied to `{tables: [...], count: N}`. |

### search\_tables

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

**Access:** Read-only.

| Parameter    | Type    | Required | Default | Description                                          |
| ------------ | ------- | -------- | ------- | ---------------------------------------------------- |
| query        | string  | Yes      | —       | Natural language query to search for relevant tables |
| max\_results | integer | No       | `5`     | Maximum number of results (default 5, max 10)        |

### describe\_table

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

**Access:** Requires the `sql.execute` permission. Read-only.

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

### describe\_tables

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

**Access:** Requires the `sql.execute` permission. Read-only.

| Parameter               | Type            | Required | Default | Description                                                                  |
| ----------------------- | --------------- | -------- | ------- | ---------------------------------------------------------------------------- |
| tables                  | array of object | Yes      | —       | List of tables to describe. Each needs schema\_name and table\_name. Max 10. |
| include\_sample\_values | boolean         | No       | `false` | Include up to 3 sample values per column                                     |
| include\_enums          | boolean         | No       | `true`  | Include enum/category values for categorical columns                         |
| jq\_filter              | string          | No       | —       | Optional jq filter to transform the response.                                |

### get\_relationships

Get foreign key relationships between tables as a join graph.

**Access:** Read-only.

| Parameter    | Type    | Required | Default | Description                                   |
| ------------ | ------- | -------- | ------- | --------------------------------------------- |
| schema\_name | string  | No       | —       | Schema name (e.g., 'public', 'analytics')     |
| table\_name  | string  | No       | —       | Table name (e.g., 'orders', 'customers')      |
| max\_results | integer | No       | `500`   | Maximum number of relationships to return.    |
| jq\_filter   | string  | No       | —       | Optional jq filter to transform the response. |

### get\_column\_values

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

**Access:** Requires the `sql.execute` permission. Read-only.

| Parameter    | Type    | Required | Default | Description                                                 |
| ------------ | ------- | -------- | ------- | ----------------------------------------------------------- |
| schema\_name | string  | Yes      | —       | Schema name (e.g., 'public', 'analytics')                   |
| table\_name  | string  | Yes      | —       | Table name (e.g., 'orders', 'customers')                    |
| column\_name | string  | Yes      | —       | Column name to get values for                               |
| limit        | integer | No       | `50`    | Maximum number of distinct values (default 50, max 100)     |
| search       | string  | No       | —       | Optional search pattern to filter values (case-insensitive) |

### get\_query\_context

All-in-one context package for a data question. Given a question, returns existing widgets, data models, and relevant tables with pruned columns, join graph, and query hints. On accounts with the semantic layer it also returns matching metrics.

**Access:** Read-only.

| Parameter     | Type    | Required | Default | Description                                                                           |
| ------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------- |
| question      | string  | Yes      | —       | Natural language question about the data                                              |
| max\_tables   | integer | No       | `5`     | Maximum number of tables to include (default 5)                                       |
| max\_datasets | integer | No       | `3`     | Max curated data models to return (semantic ranked).                                  |
| max\_widgets  | integer | No       | `3`     | Max existing widgets to return (semantic ranked).                                     |
| max\_metrics  | integer | No       | `5`     | Max metrics to return, on accounts with the semantic layer. Set to 0 to skip metrics. |

## SQL Execution

Run, lint and check SQL queries.

### execute\_sql

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

**Access:** Requires the `sql.execute` permission. Read-only.

| Parameter   | Type                       | Required | Default | Description                                                                       |
| ----------- | -------------------------- | -------- | ------- | --------------------------------------------------------------------------------- |
| sql\_query  | string                     | Yes      | —       | The SQL query to execute.                                                         |
| mode        | string (`sql`, `semantic`) | No       | —       | `sql` for a SQL query. `semantic` works only on accounts with the semantic layer. |
| date\_range | object                     | No       | —       | Optional date range to filter query results.                                      |
| max\_rows   | integer                    | No       | `1000`  | Maximum number of rows to return.                                                 |

### lint\_sql

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

**Access:** Read-only.

| Parameter | Type    | Required | Default        | Description                                    |
| --------- | ------- | -------- | -------------- | ---------------------------------------------- |
| query     | string  | Yes      | —              | The SQL query to lint and optionally auto-fix  |
| dialect   | string  | No       | `"PostgreSQL"` | SQL dialect for parsing.                       |
| auto\_fix | boolean | No       | `true`         | Whether to automatically fix formatting issues |

### validate\_widget\_query

Validate whether a SQL query result shape is compatible with a widget type.

**Access:** Requires the `widget.edit` permission. Read-only.

| Parameter    | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Required | Default | Description                                                                                                   |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| widget\_type | string (`fuel-gauge`, `fuel-gauge-wo-comparison`, `comparison-bar`, `number-wo-comparison`, `line-chart`, `date-series-table`, `n-series-line-chart`, `clustered-column-chart`, `stacked-area-line-chart`, `stacked-column`, `column-vs-line-series`, `wide-bar-chart`, `wide-bar-chart-wo-comparison`, `double-wide-bar-chart`, `double-wide-bar-chart-wo-comparison`, `donut`, `donut-wo-comparison`, `pie`, `vertical-funnel`, `horizontal-funnel`, `us-map`, `us-map-regional`, `uni-table`, `uni-table-wo-comparison`, `pivot-table`, `heat-map`, `scatterplot-chart`, `sunburst`, `grouping-separator`, `rich-text`) | Yes      | —       | Target widget type to validate against.                                                                       |
| columns      | array of object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Yes      | —       | List of columns in the query result. Each needs 'name' and 'type' ('date', 'numeric', 'string' or 'unknown'). |
| row\_count   | integer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Yes      | —       | Expected number of rows the query will return.                                                                |
| query        | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No       | —       | The SQL query to validate.                                                                                    |
| query\_mode  | string (`sql`, `semantic`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | No       | —       | How `query` is read: `sql`, or `semantic` on accounts with the semantic layer.                                |

## Boards

Find, create and arrange boards.

### list\_boards

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

**Access:** Read-only.

| Parameter     | Type             | Required | Default | Description                                                                                                               |
| ------------- | ---------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| show\_details | boolean          | No       | `false` | If true, includes board filters and a simple list of widgets (id, title, type, format\_type) alongside the board summary. |
| board\_ids    | array of integer | No       | —       | Optional list of board IDs to filter results.                                                                             |
| jq\_filter    | string           | No       | —       | Optional jq filter to transform the response.                                                                             |

### get\_board

Get detailed information about a single board.

**Access:** Read-only.

| Parameter                | Type    | Required | Default | Description                                         |
| ------------------------ | ------- | -------- | ------- | --------------------------------------------------- |
| board\_id                | integer | Yes      | —       | The board ID obtained from list\_boards             |
| include\_widgets         | boolean | No       | `false` | Include widget details (id, title, type, settings). |
| include\_widget\_queries | boolean | No       | `false` | Include SQL queries in widget details.              |
| jq\_filter               | string  | No       | —       | Optional jq filter to transform the response.       |

### create\_board

Create a new board.

**Access:** Requires the `board.edit` permission. Makes changes.

| Parameter | Type                           | Required | Default   | Description                                                                              |
| --------- | ------------------------------ | -------- | --------- | ---------------------------------------------------------------------------------------- |
| name      | string                         | Yes      | —         | Name for the new board (must be unique)                                                  |
| kind      | string (`classic`, `data-app`) | No       | `classic` | Board display mode: `classic` (widget grid) or `data-app` (full-page Data App).          |
| icon      | string                         | No       | —         | Sidebar icon: one of the allowed icon names listed in the `set_board_icons` tool schema. |

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

**Access:** Requires the `board.edit` permission. Makes changes.

| Parameter            | Type    | Required | Default | Description                                                           |
| -------------------- | ------- | -------- | ------- | --------------------------------------------------------------------- |
| board\_id            | integer | Yes      | —       | ID of the board to duplicate (from list\_boards)                      |
| display\_name        | string  | No       | —       | New name for the board                                                |
| target\_customer\_id | integer | No       | —       | Numeric ID of the target customer (not the customer name).            |
| nav\_only            | boolean | No       | —       | If true, board is navigation-only (used for grouping, has no widgets) |
| parent\_board\_id    | integer | No       | —       | ID of parent board for hierarchy.                                     |

### update\_board

Update an existing board. Only provide fields you want to change.

**Access:** Requires the `board.edit` permission. Makes changes.

| Parameter           | Type                           | Required | Default | Description                                                                                                                           |
| ------------------- | ------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| board\_id           | integer                        | Yes      | —       | ID of the board to update (from list\_boards)                                                                                         |
| display\_name       | string                         | No       | —       | New name for the board                                                                                                                |
| position\_after\_id | integer                        | No       | —       | Moves this board to sit immediately after the given sibling board, reordering it among boards that share the same parent\_board\_id.  |
| move\_to\_front     | boolean                        | No       | `false` | If true, moves this board to the first position among its siblings (boards sharing the same parent\_board\_id), ahead of all of them. |
| nav\_only           | boolean                        | No       | —       | If true, board is navigation-only (used for grouping, has no widgets)                                                                 |
| parent\_board\_id   | integer                        | No       | —       | ID of parent board for hierarchy.                                                                                                     |
| icon                | string                         | No       | —       | Sidebar icon: one of the allowed icon names. Pass an empty string to clear it.                                                        |
| kind                | string (`classic`, `data-app`) | No       | —       | Board display mode. On a `data-app` board the first visible Data App widget fills the page.                                           |
| hide\_date\_ranges  | boolean                        | No       | —       | Hide the date range and comparison pickers on a full-page Data App board. Only applies when `kind` is `data-app`.                     |

### set\_board\_icons

Set or clear the sidebar icon on many boards in one call. Boards not listed keep their current icon, and the response reports success or failure for each board.

**Access:** Requires the `board.edit` permission. Makes changes.

| Parameter | Type            | Required | Default | Description                                                                                            |
| --------- | --------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------ |
| updates   | array of object | Yes      | —       | 1 to 100 entries, each with `board_id` and `icon` (an allowed icon name, or an empty string to clear). |

### reorder\_board

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

**Access:** Requires the `board.edit` permission. Makes changes.

| Parameter   | Type             | Required | Default | Description                                                                                         |
| ----------- | ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------- |
| board\_id   | integer          | Yes      | —       | ID of the board whose widgets to reorder                                                            |
| widget\_ids | array of integer | Yes      | —       | Full ordered list of visible widget IDs (1-indexed semantics: the first ID lands at sort\_order=1). |

## Widgets

Find, create, change and check widgets.

### list\_widgets

List all widgets, optionally filtered to a specific board.

**Access:** Read-only.

| Parameter        | Type    | Required | Default | Description                                                 |
| ---------------- | ------- | -------- | ------- | ----------------------------------------------------------- |
| board\_id        | integer | No       | —       | Optional board ID to filter widgets to a single board.      |
| include\_queries | boolean | No       | `false` | Include SQL queries in response.                            |
| jq\_filter       | string  | No       | —       | Optional jq filter applied to `{widgets: [...], count: N}`. |

### get\_widget

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

**Access:** Read-only.

| Parameter  | Type    | Required | Default | Description                                   |
| ---------- | ------- | -------- | ------- | --------------------------------------------- |
| widget\_id | integer | Yes      | —       | ID of the widget to retrieve                  |
| jq\_filter | string  | No       | —       | Optional jq filter to transform the response. |

### create\_widget

Create a new widget on a board.

**Access:** Requires the `widget.edit` permission. Makes changes.

| Parameter                  | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Required | Default | Description                                                                                                                                         |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| title                      | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Yes      | —       | Title displayed on the widget.                                                                                                                      |
| widget\_type               | string (`fuel-gauge`, `comparison-bar`, `number-wo-comparison`, `line-chart`, `wide-bar-chart`, `wide-bar-chart-wo-comparison`, `double-wide-bar-chart`, `double-wide-bar-chart-wo-comparison`, `donut`, `donut-wo-comparison`, `vertical-funnel`, `horizontal-funnel`, `us-map-regional`, `us-map`, `n-series-line-chart`, `clustered-column-chart`, `stacked-area-line-chart`, `scatterplot-chart`, `sunburst`, `uni-table`, `uni-table-wo-comparison`, `grouping-separator`, `rich-text`, `data-app`, `heat-map`, `date-series-table`, `pivot-table`, `pie`, `fuel-gauge-wo-comparison`) | Yes      | —       | Type of widget.                                                                                                                                     |
| board\_id                  | integer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No       | —       | ID of the board to add the widget to. Required when saving; omit it when previewing (preview\_only=true).                                           |
| query                      | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | No       | —       | SQL query for the widget data. Required for all types except 'grouping-separator' and 'rich-text'.                                                  |
| query\_mode                | string (`sql`, `semantic`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | No       | —       | How `query` is read: `sql`, or `semantic` on accounts with the semantic layer.                                                                      |
| format\_type               | string (`money`, `percentage`, `time`, `value`, `text`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No       | —       | How to format values: 'money' (currency), 'percentage', 'time', 'value' (plain number), 'text'                                                      |
| tooltip\_text              | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | No       | —       | Tooltip text explaining the metric                                                                                                                  |
| is\_reverse\_indicator     | boolean                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No       | —       | If true, lower values are better (e.g., for costs).                                                                                                 |
| grid\_width                | string (`1`, `2`, `3`, `4`, `4-full`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | No       | —       | Widget width: '1' (quarter), '2' (half), '3', '4' (full), '4-full'.                                                                                 |
| grid\_height               | string (`1`, `2`, `auto`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | No       | —       | Widget height: '1' (standard), '2' (tall), 'auto' (rich-text only; tile grows to fit content, ideal for long-form text and Claude-style artifacts). |
| show\_values               | boolean                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No       | —       | Show data values on chart                                                                                                                           |
| x\_axis\_grouping          | string (`auto`, `daily`, `weekly`, `every_two_weeks`, `monthly`, `quarterly`, `yearly`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No       | —       | Time grouping for date-based charts: 'auto', 'daily', 'weekly', 'every\_two\_weeks', 'monthly', 'quarterly', 'yearly'                               |
| top\_line\_value\_mode     | string (`sum`, `hidden`, `correlation`, `average`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | No       | —       | Top line value display: 'sum', 'hidden', 'correlation', 'average'                                                                                   |
| truncate\_top\_line\_value | boolean                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No       | —       | Truncate large values (e.g., 1.2M instead of 1,234,567)                                                                                             |
| locked\_interval           | object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | No       | —       | Lock widget to specific date interval, ignoring board filters                                                                                       |
| locked\_compare\_interval  | object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | No       | —       | Lock comparison period for this widget                                                                                                              |
| text\_content              | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | No       | —       | HTML content for 'rich-text' widget type                                                                                                            |
| column\_definitions        | array of object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | No       | —       | Desired final column set for this widget (declarative — describe the end state, not the diff).                                                      |
| preview\_only              | boolean                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No       | `false` | If true, returns widget data for inline preview without persisting.                                                                                 |

### update\_widget

Update an existing widget. Only provide fields you want to change.

**Access:** Requires the `widget.edit` permission. Makes changes.

| Parameter                  | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Required | Default | Description                                                                                                                                                                                                                |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| widget\_id                 | integer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Yes      | —       | ID of the widget to update (from list\_widgets)                                                                                                                                                                            |
| title                      | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | No       | —       | New title for the widget.                                                                                                                                                                                                  |
| widget\_type               | string (`fuel-gauge`, `comparison-bar`, `number-wo-comparison`, `line-chart`, `wide-bar-chart`, `wide-bar-chart-wo-comparison`, `double-wide-bar-chart`, `double-wide-bar-chart-wo-comparison`, `donut`, `donut-wo-comparison`, `vertical-funnel`, `horizontal-funnel`, `us-map-regional`, `us-map`, `n-series-line-chart`, `clustered-column-chart`, `stacked-area-line-chart`, `scatterplot-chart`, `sunburst`, `uni-table`, `uni-table-wo-comparison`, `grouping-separator`, `rich-text`, `data-app`, `heat-map`, `date-series-table`, `pivot-table`, `pie`, `fuel-gauge-wo-comparison`) | No       | —       | Change widget visualization type                                                                                                                                                                                           |
| board\_id                  | integer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No       | —       | Move widget to a different board                                                                                                                                                                                           |
| hidden                     | boolean                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No       | —       | Permanently soft-deletes the widget.                                                                                                                                                                                       |
| sort\_order                | integer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No       | —       | Single-widget drag-drop equivalent: move THIS widget to position N (1-indexed; 1 = top of board).                                                                                                                          |
| grid\_width                | string (`1`, `2`, `3`, `4`, `4-full`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | No       | —       | Widget width: '1' (quarter), '2' (half), '3', '4' (full), '4-full'.                                                                                                                                                        |
| grid\_height               | string (`1`, `2`, `auto`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | No       | —       | Widget height: '1' (standard), '2' (tall), 'auto' (rich-text only; tile grows to fit content, ideal for long-form text and Claude-style artifacts).                                                                        |
| show\_values               | boolean                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No       | —       | Show data values on chart                                                                                                                                                                                                  |
| x\_axis\_grouping          | string (`auto`, `daily`, `weekly`, `every_two_weeks`, `monthly`, `quarterly`, `yearly`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No       | —       | Time grouping for date-based charts: 'auto', 'daily', 'weekly', 'every\_two\_weeks', 'monthly', 'quarterly', 'yearly'                                                                                                      |
| top\_line\_value\_mode     | string (`sum`, `hidden`, `correlation`, `average`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | No       | —       | Top line value display: 'sum', 'hidden', 'correlation', 'average'                                                                                                                                                          |
| truncate\_top\_line\_value | boolean                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No       | —       | Truncate large values (e.g., 1.2M instead of 1,234,567)                                                                                                                                                                    |
| widget\_query              | object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | No       | —       | Update widget query settings (SQL, format, tooltip)                                                                                                                                                                        |
| locked\_interval           | object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | No       | —       | Update or remove locked date interval.                                                                                                                                                                                     |
| locked\_compare\_interval  | object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | No       | —       | Update or remove locked comparison interval. interval\_period values for comparison: previousPeriod, mom (month-over-month), weekly, yoy (year-over-year), noComparison, or 'custom' (requires start\_date and end\_date). |
| text\_content              | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | No       | —       | HTML content for 'rich-text' widget type                                                                                                                                                                                   |
| column\_definitions        | array of object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | No       | —       | Desired final column set for this widget (declarative — describe the end state, not the diff).                                                                                                                             |

### bulk\_update\_widgets

Update multiple widgets in parallel (up to 100).

**Access:** Requires the `widget.edit` permission. Makes changes.

| Parameter | Type            | Required | Default | Description                                                                                            |
| --------- | --------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------ |
| updates   | array of object | Yes      | —       | List of widget updates to apply. Each update must include widget\_id and at least one field to change. |

### screenshot\_widget

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

**Access:** Read-only.

| Parameter  | Type    | Required | Default | Description                  |
| ---------- | ------- | -------- | ------- | ---------------------------- |
| widget\_id | integer | Yes      | —       | ID of the widget to retrieve |

## Board Filters

Manage the filters on a board.

### list\_board\_filters

List all board filters with pagination.

**Access:** Read-only.

| Parameter  | Type    | Required | Default | Description                                                 |
| ---------- | ------- | -------- | ------- | ----------------------------------------------------------- |
| page       | integer | No       | `1`     | Page number (1-indexed)                                     |
| per\_page  | integer | No       | `50`    | Results per page (max 250)                                  |
| jq\_filter | string  | No       | —       | Optional jq filter applied to `{filters: [...], count: N}`. |

### get\_board\_filter

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

**Access:** Read-only.

| Parameter  | Type    | Required | Default | Description                                   |
| ---------- | ------- | -------- | ------- | --------------------------------------------- |
| filter\_id | integer | Yes      | —       | ID of the board filter to retrieve            |
| jq\_filter | string  | No       | —       | Optional jq filter to transform the response. |

### create\_board\_filter

Create a new board filter.

**Access:** Requires the `board.edit` permission. Makes changes.

| Parameter                | Type                                                   | Required | Default | Description                                                                                                                                                                      |
| ------------------------ | ------------------------------------------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                     | string                                                 | Yes      | —       | Display name for the filter                                                                                                                                                      |
| filter\_type             | string (`single_select`, `multi_select`, `date_range`) | Yes      | —       | Filter type: 'single\_select' (one option), 'multi\_select' (multiple options), or 'date\_range' (date picker)                                                                   |
| param\_name              | string                                                 | No       | —       | URL parameter name (e.g., 'region').                                                                                                                                             |
| board\_ids               | array of integer                                       | No       | —       | IDs of boards to attach this filter to                                                                                                                                           |
| options                  | array of object                                        | No       | —       | Static filter options. Each option needs a name (display text) and a condition (the text substituted for the filter in a widget's query), and optionally a value and a position. |
| query                    | object                                                 | No       | —       | Dynamic query for filter options.                                                                                                                                                |
| conflicting\_filter\_ids | array of integer                                       | No       | —       | IDs of filters that conflict with this one (only one can be active at a time)                                                                                                    |

### update\_board\_filter

Update an existing board filter.

**Access:** Requires the `board.edit` permission. Makes changes.

| Parameter                | Type                                                   | Required | Default | Description                                                  |
| ------------------------ | ------------------------------------------------------ | -------- | ------- | ------------------------------------------------------------ |
| filter\_id               | integer                                                | Yes      | —       | ID of the board filter to update                             |
| name                     | string                                                 | No       | —       | New display name for the filter                              |
| filter\_type             | string (`single_select`, `multi_select`, `date_range`) | No       | —       | New filter type (single\_select, multi\_select, date\_range) |
| param\_name              | string                                                 | No       | —       | New URL parameter name                                       |
| board\_ids               | array of integer                                       | No       | —       | New list of board IDs to attach this filter to               |
| options                  | array of object                                        | No       | —       | Update filter options.                                       |
| query                    | object                                                 | No       | —       | New dynamic query for filter options                         |
| conflicting\_filter\_ids | array of integer                                       | No       | —       | New list of conflicting filter IDs                           |

### delete\_board\_filter

Permanently delete a board filter.

**Access:** Requires the `board.edit` permission. Makes changes.

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

## Data Models

Data models (called datasets in the tools) are reusable SQL queries that widgets and Data Apps select from.

### list\_datasets

List all datasets for a customer.

**Access:** Read-only.

| Parameter     | Type            | Required | Default | Description                                                  |
| ------------- | --------------- | -------- | ------- | ------------------------------------------------------------ |
| limit         | integer         | No       | `100`   | Maximum number of datasets to return                         |
| schema\_names | array of string | No       | —       | Optional list of schema names to filter by                   |
| include\_sql  | boolean         | No       | `false` | Include SQL query for each data model.                       |
| jq\_filter    | string          | No       | —       | Optional jq filter applied to `{datasets: [...], count: N}`. |

### get\_dataset

Get one data model by ID, including its SQL query, materialization, verified flag and columns.

**Access:** Read-only.

| Parameter   | Type    | Required | Default | Description                                |
| ----------- | ------- | -------- | ------- | ------------------------------------------ |
| dataset\_id | integer | Yes      | —       | ID of the data model (from list\_datasets) |

### create\_dataset

Create a new dataset.

**Access:** Requires the `widget.edit` permission. Makes changes.

| Parameter             | Type                                                 | Required | Default              | Description                                                                                             |
| --------------------- | ---------------------------------------------------- | -------- | -------------------- | ------------------------------------------------------------------------------------------------------- |
| name                  | string                                               | Yes      | —                    | Name for the new data model (must be unique)                                                            |
| description           | string                                               | Yes      | —                    | What the data model contains and its purpose (max 500 characters)                                       |
| query                 | string                                               | Yes      | —                    | SQL query that defines the data model                                                                   |
| materialization\_type | string (`not_materialized`, `materialized_as_table`) | No       | `"not_materialized"` | How to materialize: 'not\_materialized' (fresh each time), 'materialized\_as\_table' (best performance) |

### update\_dataset

Update an existing dataset.

**Access:** Requires the `widget.edit` permission. Makes changes.

| Parameter                | Type                                                                                           | Required | Default | Description                                                                                    |
| ------------------------ | ---------------------------------------------------------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------- |
| dataset\_id              | integer                                                                                        | Yes      | —       | ID of the data model to update (from list\_datasets)                                           |
| name                     | string                                                                                         | No       | —       | New name for the data model                                                                    |
| description              | string                                                                                         | No       | —       | New description (max 500 characters)                                                           |
| query                    | string                                                                                         | No       | —       | New SQL query.                                                                                 |
| materialization\_type    | string (`not_materialized`, `materialized_as_table`)                                           | No       | —       | New materialization type: 'not\_materialized' or 'materialized\_as\_table'                     |
| column\_tags             | array of object                                                                                | No       | —       | Tags for the data model's columns: role, default time dimension, time granularities and grain. |
| rls\_access\_mode        | string (`materialize_for_each_user`, `rls_policy_permissions`, `customer_access`, `no_access`) | No       | —       | How row-level security applies to the data model's materialized table.                         |
| rls\_access\_mapping\_id | integer                                                                                        | No       | —       | Access mapping that filters rows (from list\_rls\_access\_mappings).                           |
| rls\_column\_name        | string                                                                                         | No       | —       | Data model column matched against the access mapping values.                                   |

## Data Apps

Data Apps are custom HTML and JavaScript widgets. They run SQL only through named queries saved with the app. Each query selects from a data model with `use_dataset(N)`, not from a raw `schema.table`. A query can follow board filters through a commented `WHERE` clause keyed to the filter's `param_name`.

### create\_data\_app

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

**Access:** Requires the `widget.edit` permission. Makes changes.

| Parameter        | Type                                  | Required | Default | Description                                                                                                           |
| ---------------- | ------------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| board\_id        | integer                               | Yes      | —       | ID of the board to add the widget to.                                                                                 |
| title            | string                                | Yes      | —       | Title displayed on the widget.                                                                                        |
| body\_html       | string                                | Yes      | —       | HTML/JS body rendered inside a sandboxed iframe (sandbox='allow-scripts' only).                                       |
| queries          | array of object                       | Yes      | —       | Named SQL queries — the ONLY way a Data App can run SQL.                                                              |
| toolkit\_version | string                                | No       | —       | Data Apps Toolkit release the app loads: `2.0.0` (current look; the default for new apps) or `1.0.0` (original look). |
| grid\_width      | string (`1`, `2`, `3`, `4`, `4-full`) | No       | —       | Tile width: '1' (quarter), '2' (half), '3', '4' (full), '4-full'.                                                     |
| grid\_height     | string (`1`, `2`, `auto`)             | No       | —       | Tile height: '1' (standard), '2' (tall), 'auto'.                                                                      |
| preview\_only    | boolean                               | No       | `false` | If true, returns widget data for inline preview without persisting.                                                   |

### update\_data\_app

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

**Access:** Requires the `widget.edit` permission. Makes changes.

| Parameter                 | Type                                  | Required | Default | Description                                                                                                                                                                               |
| ------------------------- | ------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| widget\_id                | integer                               | Yes      | —       | ID of the widget to update (from list\_widgets)                                                                                                                                           |
| title                     | string                                | No       | —       | New title for the widget.                                                                                                                                                                 |
| body\_html                | string                                | No       | —       | HTML/JS body rendered inside a sandboxed iframe (sandbox='allow-scripts' only).                                                                                                           |
| body\_edits               | array of object                       | No       | —       | Targeted find/replace edits to the EXISTING body\_html — use this instead of body\_html to patch a Data App without resending the whole document (ideal for small tweaks to a large app). |
| toolkit\_version          | string                                | No       | —       | Data Apps Toolkit release the app loads: `2.0.0` (current look; the default for new apps) or `1.0.0` (original look).                                                                     |
| queries                   | array of object                       | No       | —       | Named SQL queries — the ONLY way a Data App can run SQL.                                                                                                                                  |
| grid\_width               | string (`1`, `2`, `3`, `4`, `4-full`) | No       | —       | Tile width: '1' (quarter), '2' (half), '3', '4' (full), '4-full'.                                                                                                                         |
| grid\_height              | string (`1`, `2`, `auto`)             | No       | —       | Tile height: '1' (standard), '2' (tall), 'auto'.                                                                                                                                          |
| data\_app\_state\_enabled | boolean                               | No       | —       | Enable or disable saved state for this Data App.                                                                                                                                          |

### get\_data\_app\_state

Read a Data App's saved state: the small key/value map an app keeps between visits (for example checklist ticks or saved filters). An app that has never saved state returns an empty map.

**Access:** Read-only.

| Parameter  | Type    | Required | Default | Description                                                                                |
| ---------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------ |
| widget\_id | integer | Yes      | —       | ID of the Data App widget whose state to read or write (from list\_widgets or get\_board). |

### set\_data\_app\_state

Write or remove keys in a Data App's saved state. Pass `set` (keys to values) and/or `remove` (keys to delete); at least one must be non-empty.

**Access:** Requires the `widget.edit` permission. Makes changes.

| Parameter  | Type            | Required | Default | Description                                                                                |
| ---------- | --------------- | -------- | ------- | ------------------------------------------------------------------------------------------ |
| widget\_id | integer         | Yes      | —       | ID of the Data App widget whose state to read or write (from list\_widgets or get\_board). |
| set        | object          | No       | —       | Mapping of state keys to JSON values to write. Keys are max 200 chars.                     |
| remove     | array of string | No       | —       | List of state keys to delete. Each key is max 200 chars.                                   |

## Row-Level Security

Control which warehouse rows each person can see. An **identity** is a warehouse login; you link CorralData users and groups to it in the CorralData app. A **secured table** limits who can read a table. An **access mapping** is a lookup table of identity-to-value pairs used to filter rows.

All of these tools need the `security.admin` permission. No default role includes it. To manage row-level security, ask the CorralData team to set it up for you.

### list\_rls\_identities

List the account's RLS identities, with their state and how many tables and mapping values each is granted.

**Access:** Requires the `security.admin` permission. Read-only.

| Parameter | Type   | Required | Default | Description                  |
| --------- | ------ | -------- | ------- | ---------------------------- |
| search    | string | No       | —       | Case-insensitive name filter |

### get\_rls\_identity

Get one RLS identity and everything it can see: granted tables and the values it may see through each access mapping.

**Access:** Requires the `security.admin` permission. Read-only.

| Parameter    | Type    | Required | Default | Description                                         |
| ------------ | ------- | -------- | ------- | --------------------------------------------------- |
| identity\_id | integer | Yes      | —       | ID of the RLS identity (from list\_rls\_identities) |

### create\_rls\_identity

Create an RLS identity: a warehouse login that row-level security grants access to. Link it to CorralData users or groups in the CorralData app.

**Access:** Requires the `security.admin` permission. Makes changes.

| Parameter | Type   | Required | Default | Description                                |
| --------- | ------ | -------- | ------- | ------------------------------------------ |
| name      | string | Yes      | —       | Name of the identity. Unique per customer. |

### delete\_rls\_identity

Permanently delete an RLS identity, its warehouse login and all of its grants. Users and groups linked to it lose that access.

**Access:** Requires the `security.admin` permission. Makes changes.

| Parameter    | Type    | Required | Default | Description                                         |
| ------------ | ------- | -------- | ------- | --------------------------------------------------- |
| identity\_id | integer | Yes      | —       | ID of the RLS identity (from list\_rls\_identities) |

### list\_rls\_secured\_tables

List the account's secured tables with their mode, filter column, access mapping and state.

**Access:** Requires the `security.admin` permission. Read-only.

| Parameter    | Type                                                          | Required | Default | Description                             |
| ------------ | ------------------------------------------------------------- | -------- | ------- | --------------------------------------- |
| mode         | string (`full_access`, `specific_users`, `value_permissions`) | No       | —       | Only list secured tables in this mode   |
| schema\_name | string                                                        | No       | —       | Only list secured tables in this schema |
| search       | string                                                        | No       | —       | Case-insensitive name filter            |

### get\_rls\_secured\_table

Get one secured table and who can see it.

**Access:** Requires the `security.admin` permission. Read-only.

| Parameter | Type    | Required | Default | Description                                               |
| --------- | ------- | -------- | ------- | --------------------------------------------------------- |
| table\_id | integer | Yes      | —       | ID of the secured table (from list\_rls\_secured\_tables) |

### create\_rls\_secured\_tables

Secure one or more tables in a schema, or a whole schema, with row-level security. The `mode` sets who can read rows: everyone (`full_access`), only granted identities (`specific_users`), or rows filtered by a column through an access mapping (`value_permissions`).

**Access:** Requires the `security.admin` permission. Makes changes.

| Parameter                 | Type                                                          | Required | Default            | Description                                                                                                                                                                                   |
| ------------------------- | ------------------------------------------------------------- | -------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| schema\_name              | string                                                        | Yes      | —                  | Warehouse schema of the tables to secure                                                                                                                                                      |
| mode                      | string (`full_access`, `specific_users`, `value_permissions`) | Yes      | —                  | full\_access (everyone sees every row), specific\_users (only granted identities can read the table) or value\_permissions (rows filtered by column values granted through an access mapping) |
| table\_names              | array of string                                               | No       | —                  | Tables in the schema to secure. Omit to secure the whole schema (full\_access and specific\_users only).                                                                                      |
| column\_name              | string                                                        | No       | —                  | Column of the secured tables matched against the access mapping values (value\_permissions only)                                                                                              |
| access\_mapping\_id       | integer                                                       | No       | —                  | ID of the access mapping (from list\_rls\_access\_mappings)                                                                                                                                   |
| identity\_ids             | array of integer                                              | No       | —                  | Identities to grant access right away (specific\_users only)                                                                                                                                  |
| ensure\_permissions\_mode | string (`on_schema_sync`, `every_hour`, `once`)               | No       | `"on_schema_sync"` | When grants are re-applied to the tables: on\_schema\_sync (after every data sync, default), every\_hour, or once right after creating                                                        |

### delete\_rls\_secured\_table

Permanently remove row-level security from a table or schema, including every grant on it.

**Access:** Requires the `security.admin` permission. Makes changes.

| Parameter | Type    | Required | Default | Description                                               |
| --------- | ------- | -------- | ------- | --------------------------------------------------------- |
| table\_id | integer | Yes      | —       | ID of the secured table (from list\_rls\_secured\_tables) |

### list\_rls\_access\_mappings

List the account's access mappings: lookup tables that map identities to the values they may see.

**Access:** Requires the `security.admin` permission. Read-only.

| Parameter | Type   | Required | Default | Description                  |
| --------- | ------ | -------- | ------- | ---------------------------- |
| search    | string | No       | —       | Case-insensitive name filter |

### get\_rls\_access\_mapping

Get one access mapping, with every value granted through it and the identity each value belongs to.

**Access:** Requires the `security.admin` permission. Read-only.

| Parameter   | Type    | Required | Default | Description                                                 |
| ----------- | ------- | -------- | ------- | ----------------------------------------------------------- |
| mapping\_id | integer | Yes      | —       | ID of the access mapping (from list\_rls\_access\_mappings) |

### create\_rls\_access\_mapping

Create an access mapping. Only a name and a value type are needed; the lookup table is named automatically.

**Access:** Requires the `security.admin` permission. Makes changes.

| Parameter    | Type                         | Required | Default | Description                                                     |
| ------------ | ---------------------------- | -------- | ------- | --------------------------------------------------------------- |
| name         | string                       | Yes      | —       | Display name, e.g. 'Locations'. Unique per customer.            |
| column\_type | string (`VARCHAR`, `BIGINT`) | Yes      | —       | Type of the values: VARCHAR for text, BIGINT for whole numbers. |

### delete\_rls\_access\_mapping

Permanently delete an access mapping, its lookup table and every value granted through it. Fails while a secured table still uses it.

**Access:** Requires the `security.admin` permission. Makes changes.

| Parameter   | Type    | Required | Default | Description                                                 |
| ----------- | ------- | -------- | ------- | ----------------------------------------------------------- |
| mapping\_id | integer | Yes      | —       | ID of the access mapping (from list\_rls\_access\_mappings) |

### grant\_rls\_table\_access

Let an identity read one or more `specific_users` secured tables. Tables already granted are reported as unchanged.

**Access:** Requires the `security.admin` permission. Makes changes.

| Parameter    | Type             | Required | Default | Description                                                             |
| ------------ | ---------------- | -------- | ------- | ----------------------------------------------------------------------- |
| identity\_id | integer          | Yes      | —       | ID of the RLS identity (from list\_rls\_identities)                     |
| table\_ids   | array of integer | Yes      | —       | IDs of specific\_users secured tables (from list\_rls\_secured\_tables) |

### revoke\_rls\_table\_access

Stop an identity reading one or more `specific_users` secured tables.

**Access:** Requires the `security.admin` permission. Makes changes.

| Parameter    | Type             | Required | Default | Description                                                             |
| ------------ | ---------------- | -------- | ------- | ----------------------------------------------------------------------- |
| identity\_id | integer          | Yes      | —       | ID of the RLS identity (from list\_rls\_identities)                     |
| table\_ids   | array of integer | Yes      | —       | IDs of specific\_users secured tables (from list\_rls\_secured\_tables) |

### grant\_rls\_mapping\_values

Let an identity see rows matching the given values in every table filtered through an access mapping.

**Access:** Requires the `security.admin` permission. Makes changes.

| Parameter    | Type            | Required | Default | Description                                                 |
| ------------ | --------------- | -------- | ------- | ----------------------------------------------------------- |
| identity\_id | integer         | Yes      | —       | ID of the RLS identity (from list\_rls\_identities)         |
| mapping\_id  | integer         | Yes      | —       | ID of the access mapping (from list\_rls\_access\_mappings) |
| values       | array of string | Yes      | —       | Values of the mapping column, e.g. location IDs, as strings |

### revoke\_rls\_mapping\_values

Stop an identity seeing rows matching the given values of an access mapping.

**Access:** Requires the `security.admin` permission. Makes changes.

| Parameter    | Type            | Required | Default | Description                                                 |
| ------------ | --------------- | -------- | ------- | ----------------------------------------------------------- |
| identity\_id | integer         | Yes      | —       | ID of the RLS identity (from list\_rls\_identities)         |
| mapping\_id  | integer         | Yes      | —       | ID of the access mapping (from list\_rls\_access\_mappings) |
| values       | array of string | Yes      | —       | Values of the mapping column, e.g. location IDs, as strings |

## Connected Services

Work with the services connected to your account, such as ad platforms, EMRs and CRMs. Their tools aren't listed directly: find them with `search_service_tools` and run them with `call_service_tool`. You only see tools for services your account has connected.

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

**Access:** Read-only.

No parameters.

### search\_service\_tools

Search the tools provided by the account's connected services, in plain language. Returns matching tool definitions, ranked by relevance. Only services the account has connected are searched.

**Access:** Read-only.

| Parameter | Type   | Required | Default | Description                                            |
| --------- | ------ | -------- | ------- | ------------------------------------------------------ |
| query     | string | Yes      | —       | Natural language query for a connected service's tools |

### call\_service\_tool

Run a connected service's tool by its exact name. Use `search_service_tools` first to find the name and its parameters. Actions that write to the service ask the user to confirm before they run.

**Access:** Read-only for read actions. Write actions need the user's confirmation.

| Parameter | Type    | Required | Default | Description                                               |
| --------- | ------- | -------- | ------- | --------------------------------------------------------- |
| name      | string  | Yes      | —       | Exact service tool name, from `search_service_tools`      |
| arguments | object  | No       | —       | Arguments to pass to the tool                             |
| confirmed | boolean | No       | `false` | Set by the client after the user approves a write action. |

## AI Configuration

Read prompt templates and set the custom instructions AskCorral follows, for the whole account or just for you.

### list\_prompts

List all available prompt templates with metadata.

**Access:** Read-only.

No parameters.

### get\_prompt

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

**Access:** Read-only.

| Parameter | Type   | Required | Default | Description                                 |
| --------- | ------ | -------- | ------- | ------------------------------------------- |
| name      | string | Yes      | —       | Prompt name from list\_prompts              |
| arguments | object | No       | —       | Arguments for the prompt, as name to value. |

### set\_customer\_prompt

Create or update the customer's organization-wide AI custom instructions, which steer AskCorral for every user of the account. Passing an empty string removes the prompt entirely.

**Access:** Requires the `company.edit` permission. Makes changes.

| Parameter | Type   | Required | Default | Description               |
| --------- | ------ | -------- | ------- | ------------------------- |
| content   | string | Yes      | —       | Full prompt text to save. |

### set\_my\_custom\_instructions

Create or update your own personal AI custom instructions. They steer AskCorral for you only and never change the organization's instructions; when the two conflict, the organization's win. Passing an empty string removes them.

**Access:** Makes changes. Saved on your user account in the customer, so you need a user account there.

| Parameter | Type   | Required | Default | Description                                     |
| --------- | ------ | -------- | ------- | ----------------------------------------------- |
| content   | string | Yes      | —       | Full text of the personal instructions 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.

**Access:** Read-only.

| Parameter     | Type    | Required | Default | Description                                                      |
| ------------- | ------- | -------- | ------- | ---------------------------------------------------------------- |
| include\_demo | boolean | No       | `false` | Include demo customer accounts in results.                       |
| name\_filter  | string  | No       | —       | Optional keyword to filter customers by name (case-insensitive). |
| jq\_filter    | string  | No       | —       | Optional jq filter to transform the response.                    |

## Permissions Summary

Permissions come from your CorralData role. These are the default roles. CorralData can set up custom roles for your account.

| Permission       | What it unlocks                                                                                                                                                                                                                                                  | Default roles that include it                                                                        |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| *(none)*         | Browse boards, widgets, filters, data models and Data Apps; read Data App state; list schemas and tables; `lint_sql`; `get_query_context`; `get_relationships`; `screenshot_widget`; connected services; prompts; `set_my_custom_instructions`; `list_customers` | Every role                                                                                           |
| `sql.execute`    | `execute_sql`, `describe_table`, `describe_tables`, `get_column_values`                                                                                                                                                                                          | Editor, Admin                                                                                        |
| `board.edit`     | Create, duplicate, change and reorder boards; manage board filters                                                                                                                                                                                               | Editor, Admin                                                                                        |
| `widget.edit`    | Create and change widgets, data models and Data Apps; `validate_widget_query`; write Data App state                                                                                                                                                              | Editor, Admin                                                                                        |
| `company.edit`   | `set_customer_prompt`                                                                                                                                                                                                                                            | Admin                                                                                                |
| `security.admin` | All Row-Level Security tools                                                                                                                                                                                                                                     | Not in any default role. To manage row-level security, ask the CorralData team to set it up for you. |

Viewer and Reports Only roles can't run SQL through the MCP server. To run SQL, a user needs the Editor or Admin role, or a custom role from CorralData that includes `sql.execute`.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
