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