Tools Reference

Tools Reference

The CorralData MCP Server provides 40 tools organized into eleven 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_customers 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

---

Board & Widget Utilities

Additional tools for layout control and visual QA.

reorder_board

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

• board_id (integer, required): ID of the board to reorder

• widget_ids (array of integer, required): Full ordered list of visible widget IDs

screenshot_widget

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

• widget_id (integer, required): ID of the widget to capture

Data Apps

Custom HTML/JS widgets that run SQL only through named, pre-registered queries. Each query must select from a data model via use_dataset(N) — not a raw schema.table — and can opt into board filters with a commented WHERE clause keyed to the filter's param_name (substituted server-side, the same mechanism native widgets use). Requires widget.edit.

create_data_app

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

• board_id (integer, required): ID of the board to add the widget to

• title (string, required): Widget title

• body_html (string, required): HTML/JS body rendered in the sandboxed iframe

• queries (array of {name, sql}, required): Named SQL queries the app can run via runNamedQuery

• preview_only (boolean, default false): Preview without saving

update_data_app

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

• widget_id (integer, required): ID of the data app widget

• body_html / body_edits (string / array, optional): Full body, or targeted find/replace patches for small tweaks

• queries (array, optional): Declarative — the submitted list replaces the full query registry

Connected Services

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

list_services

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

search_service_tools

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

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

call_service_tool

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

• name (string, required): Exact service tool name (use search_service_tools first)

• arguments (object, optional): Arguments to pass to the tool

• confirmed (boolean, default false): Set by the client after the user approves a write action

AI Configuration

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

list_prompts

List all available prompt templates with metadata.

get_prompt

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

• name (string, required): Prompt name

• arguments (object, optional): Arguments for the prompt

set_customer_prompt

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

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

Account Management

list_customers

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

• name_filter (string, optional): Keyword filter by name

• include_demo (boolean, default false): Include demo customer accounts

---

Permissions Summary

Role	Tools
All authenticated users	All read-only tools: list/get boards, widgets, filters, datasets, all schema tools, execute_sql, lint_sql, get_query_context, get_relationships, list_customers, list_services, search_service_tools, list_prompts, get_prompt, call_service_tool (write actions require confirmation), screenshot_widget
board.edit	create_board, duplicate_board, update_board, create_board_filter, update_board_filter, delete_board_filter, reorder_board
widget.edit	create_widget, update_widget, bulk_update_widgets, validate_widget_query, create_dataset, update_dataset, create_data_app, update_data_app
ai_metadata.edit	set_customer_prompt