# Tools Reference

## Tools Reference

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

### Schema Discovery

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

#### list\_schemas

List all available database schemas with table counts.

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

#### list\_tables

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

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

#### describe\_table

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

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

#### describe\_tables

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

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

#### get\_relationships

Get foreign key relationships between tables as a join graph.

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

#### search\_tables

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

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

#### get\_column\_values

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

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

#### get\_query\_context

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

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

***

### SQL Execution

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

#### execute\_sql

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

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

#### lint\_sql

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

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

#### validate\_widget\_query

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

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

***

### Boards

Tools for managing dashboards.

#### list\_boards

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

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

#### get\_board

Get detailed information about a single board.

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

#### create\_board

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

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

#### duplicate\_board

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

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

#### update\_board

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

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

***

### Widgets

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

#### list\_widgets

List all widgets, optionally filtered to a specific board.

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

#### get\_widget

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

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

#### create\_widget

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

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

#### update\_widget

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

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

#### bulk\_update\_widgets

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

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

***

### Board Filters

Tools for managing interactive filters on boards.

#### list\_board\_filters

List all board filters with pagination.

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

#### get\_board\_filter

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

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

#### create\_board\_filter

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

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

#### update\_board\_filter

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

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

#### delete\_board\_filter

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

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

***

### Datasets

Tools for managing reusable SQL query definitions.

#### list\_datasets

List all datasets for a customer.

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

#### create\_dataset

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

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

#### update\_dataset

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

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

***

### Permissions Summary

| Role                      | Tools                                                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| *All authenticated users* | All read-only tools: list/get boards, widgets, filters, datasets, all schema tools, execute\_sql, lint\_sql         |
| `board.edit`              | create\_board, duplicate\_board, update\_board, create\_board\_filter, update\_board\_filter, delete\_board\_filter |
| `widget.edit`             | create\_widget, update\_widget, bulk\_update\_widgets, validate\_widget\_query, create\_dataset, update\_dataset    |


---

# Agent Instructions: Querying This Documentation

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

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

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

The question should be specific, self-contained, and written in natural language.
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.