CHouseUI
Automation

MCP tool catalog

Every MCP tool with its access level, default state, required permissions and parameters — generated from the server.

Source
Generated from the MCP tool registry in packages/server/src/mcp, so it always matches the code.

All 136 tools the MCP server offers. 121 are on by default: the read-only tools that don't spend LLM budget. Writes, destructive tools and tools that call the AI stay off until an administrator turns them on in AI Governance › MCP, one tool or one category at a time.

An agent only sees a tool in tools/list when it is on and the agent's token holds one of the listed permissions. The underlying API still checks the permission and the user's data access rules on every call.

AccessMeaningMCP annotations
ReadReads data or state; changes nothingreadOnlyHint, idempotentHint
WriteCreates something or starts work: saves a query, runs a job or check, proposes a fix, acknowledges an incident—
DestructiveRuns DDL/DML, deletes CHouse UI objects or kills a querydestructiveHint

All tools

ToolAccessOn by defaultNeeds any of
whoamiReadYesany token
list_connectionsReadYesconnections:view
connection_runs_asReadYesconnections:view
use_connectionReadYesconnections:view
list_databasesReadYesdatabase:view, table:view
list_tablesReadYesdatabase:view, table:view
describe_tableReadYestable:view
sample_tableReadYestable:select
queryReadYesquery:execute, table:select
explain_queryReadYesquery:execute, table:select
list_saved_queriesReadYessaved_queries:view
get_saved_queryReadYessaved_queries:view
run_saved_queryReadYessaved_queries:view
create_saved_queryWriteNosaved_queries:create
query_rawDestructiveNoquery:execute:ddl, query:execute:dml
delete_saved_queryDestructiveNosaved_queries:delete
update_saved_queryWriteYessaved_queries:update
share_saved_queryWriteYessaved_queries:share
create_databaseWriteYesdatabase:create
create_tableWriteYestable:create
drop_tableDestructiveYestable:drop
drop_databaseDestructiveYesdatabase:drop
run_sql_changeWriteYesquery:execute:dml, query:execute:ddl, table:insert, table:update, table:delete, table:create, table:alter, table:drop, database:create, database:drop
get_dataset_healthReadYesobserve:view
get_lineageReadYesobserve:view
get_table_contextReadYesobserve:view
get_metricReadYesobserve:view
get_pipeline_statusReadYesobserve:view
list_incidentsReadYesobserve:view, data_health:view
list_remediation_actionsReadYesremediation:propose, remediation:approve, remediation:approve_high
get_remediation_actionReadYesremediation:propose, remediation:approve, remediation:approve_high
get_investigation_notebookReadYesdata_health:view, observe:view, doctor:view
propose_remediationWriteNoremediation:propose
list_health_checksReadYesdata_health:view
get_health_checkReadYesdata_health:view
health_timelineReadYesdata_health:view
run_health_checkWriteNodata_health:run
acknowledge_incidentWriteNodata_health:edit
create_health_promiseWriteYesdata_health:edit
watch_tableWriteYesdata_health:edit
update_health_promiseWriteYesdata_health:edit
pause_health_promiseWriteYesdata_health:edit
resume_health_promiseWriteYesdata_health:edit
acknowledge_health_incidentWriteYesdata_health:edit
snooze_health_incidentWriteYesdata_health:edit
delete_health_promiseWriteYesdata_health:delete
get_query_regressionsReadYesperformance:view
get_query_shape_historyReadYesperformance:view
get_capacityReadYescapacity:view
list_upgrade_assessmentsReadYesupgrades:view
get_upgrade_assessmentReadYesupgrades:view
get_upgrade_statusReadYesupgrades:view
list_dashboardsReadYesdashboards:view
get_dashboardReadYesdashboards:view
export_dashboardReadYesdashboards:view
run_dashboard_panelReadYesdashboards:view
list_dashboard_versionsReadYesdashboards:view
get_dashboard_annotationsReadYesdashboards:view
create_dashboard_snapshotWriteNodashboards:view, query:execute
apply_dashboardWriteNodashboards:edit
delete_dashboardDestructiveNodashboards:delete
create_dashboardWriteYesdashboards:edit
update_dashboardWriteYesdashboards:edit
add_panelWriteYesdashboards:edit
update_panelWriteYesdashboards:edit
remove_panelWriteYesdashboards:edit
restore_dashboard_versionWriteYesdashboards:edit
add_dashboard_noteWriteYesdashboards:edit
delete_dashboard_noteWriteYesdashboards:view
share_dashboardWriteYesdashboards:share
update_table_contextWriteYescontext:edit
upsert_metricWriteYescontext:edit
delete_metricWriteYescontext:edit
metrics_overviewReadYesmetrics:view
live_queriesReadYeslive_queries:view
fleet_snapshotsReadYesfleet:view
list_alertsReadYesalerting:view
audit_listReadYesaudit:view
get_collector_statusReadYesobserve:view
get_collector_scheduleReadYesconnections:view
test_alert_channelWriteNoalerting:edit
kill_queryDestructiveNolive_queries:kill, live_queries:kill_all
create_alert_ruleWriteYesalerting:edit
update_alert_ruleWriteYesalerting:edit
mute_alert_ruleWriteYesalerting:edit
post_alert_messageWriteYesalerting:edit
clear_alert_eventsWriteYesalerting:delete
acknowledge_observe_incidentWriteYesobserve:edit
dismiss_suggestionWriteYesobserve:edit
pin_table_criticalityWriteYesobserve:edit
add_notebook_cellWriteYesnotebooks:edit
update_cost_ratesWriteYessettings:update
update_collector_scheduleWriteYesconnections:edit
start_codec_trialWriteYesupgrades:run
run_doctor_scanWriteYesdoctor:run
update_doctor_scheduleWriteYesdoctor:run
update_fleet_alert_configWriteYessettings:update
run_upgrade_assessmentWriteYesupgrades:run
list_scheduled_jobsReadYesscheduled_queries:view
get_scheduled_jobReadYesscheduled_queries:view
list_scheduled_runsReadYesscheduled_queries:view
run_scheduled_jobWriteNoscheduled_queries:run
delete_scheduled_jobDestructiveNoscheduled_queries:delete
create_scheduled_queryWriteYesscheduled_queries:edit
update_scheduled_jobWriteYesscheduled_queries:edit
pause_scheduled_jobWriteYesscheduled_queries:edit
resume_scheduled_jobWriteYesscheduled_queries:edit
ai_optimizeRead · LLMNoai:optimize
doctor_scanWrite · LLMNodoctor:run
doctor_reportsReadYesdoctor:view
get_doctor_reportReadYesdoctor:view
get_action_statusWriteYesany token
undo_actionWriteYesany token
get_ai_usageReadYesai_usage:view, ai:chat, ai:optimize
get_ai_data_egressReadYesai_usage:view, ai:chat, ai:optimize
list_ai_requestsReadYesai_usage:view, ai:chat, ai:optimize
get_ai_requestReadYesai_usage:view, ai:chat, ai:optimize
list_ai_agentsReadYesai_agents:view
list_ai_guardrailsReadYesai_guardrails:view
list_ai_guardrail_triggersReadYesai_guardrails:view
draft_ai_agentWriteYesai_agents:manage
run_ai_evalWriteYesai_agents:manage
publish_ai_agentDestructiveYesai_agents:manage
create_userDestructiveYesusers:create
update_userDestructiveYesusers:update
deactivate_userDestructiveYesusers:update
assign_roleDestructiveYesroles:assign
create_roleDestructiveYesroles:create
update_roleDestructiveYesroles:update
delete_roleDestructiveYesroles:delete
create_data_access_policyDestructiveYesdata_access:create
update_data_access_policyDestructiveYesdata_access:update
delete_data_access_policyDestructiveYesdata_access:delete
set_role_policiesDestructiveYesdata_access:assign
create_clickhouse_roleDestructiveYesclickhouse:roles:create
update_clickhouse_roleDestructiveYesclickhouse:roles:update

Identity & connections

whoami

Who am I — Read · on by default · any token

Report the authenticated user's identity, roles, permissions, and active connection context. Use this first to learn what the agent is allowed to do.

No parameters.

list_connections

List connections — Read · on by default · needs any of connections:view

List the ClickHouse connections visible to this token.

No parameters.

connection_runs_as

What my statements run as — Read · on by default · needs any of connections:view

For each connection this token can use, report which ClickHouse identity its statements run with (the connection's login, a ClickHouse role, or the account's own linked ClickHouse user), whether that is usable now, and the statement forms the connection refuses. 'ready' means the identity is in place; ClickHouse grants and CHouse permissions still decide each statement. Call it before querying a connection, and when a statement is refused for identity reasons. A state other than 'ready' cannot be fixed with any tool: tell the user, who needs a super admin or a ClickHouse administrator.

No parameters.

use_connection

Check a connection — Read · on by default · needs any of connections:view

Validate a connection id and return its details. To operate on that connection, pass the id as the connection_id argument on other tools (or set the X-Connection-Id request header). Never mutates state.

ParameterTypeRequiredDescription
connection_idstringYesConnection id to validate and adopt

Explore

list_databases

List databases — Read · on by default · needs any of database:view, table:view

List the databases and tables visible to this token (respects data-access policies). Returns the filtered database tree.

No parameters.

list_tables

List tables — Read · on by default · needs any of database:view, table:view

List the tables inside one database (respects data-access policies).

ParameterTypeRequiredDescription
databasestringYesDatabase name
connection_idstringNoConnection id (defaults to the request/header connection)

describe_table

Describe a table — Read · on by default · needs any of table:view

Describe a table: columns, types, engine, and other metadata.

ParameterTypeRequiredDescription
databasestringYesDatabase name
tablestringYesTable name
connection_idstringNoConnection id (defaults to the request/header connection)

sample_table

Sample rows — Read · on by default · needs any of table:select

Preview up to 20 rows of a table (bounded sample).

ParameterTypeRequiredDescription
databasestringYesDatabase name
tablestringYesTable name
limitnumberNoRows to sample (max 20)
connection_idstringNoConnection id (defaults to the request/header connection)

Query

query

Run a read-only query — Read · on by default · needs any of query:execute, table:select

Run a single read-only SELECT/WITH/SHOW/DESCRIBE/EXPLAIN query against ClickHouse. Writes and multi-statement input are rejected. Results are capped (100 rows default, max 500).

ParameterTypeRequiredDescription
sqlstringYesThe SELECT/WITH/SHOW/DESCRIBE/EXPLAIN statement
limitnumberNoMaximum rows to return
connection_idstringNoConnection id (defaults to the request/header connection)

explain_query

Explain a query — Read · on by default · needs any of query:execute, table:select

Return the EXPLAIN plan for a SELECT/WITH query without executing it.

ParameterTypeRequiredDescription
sqlstringYesThe SELECT/WITH statement to explain
connection_idstringNoConnection id (defaults to the request/header connection)

list_saved_queries

List saved queries — Read · on by default · needs any of saved_queries:view

List saved queries visible to this token.

No parameters.

get_saved_query

Get a saved query — Read · on by default · needs any of saved_queries:view

Get one saved query definition by id.

ParameterTypeRequiredDescription
idstringYesSaved query id

run_saved_query

Run a saved query — Read · on by default · needs any of saved_queries:view

Execute a saved query through the safe SELECT-only path. Saved queries that write are refused — use the UI for those.

ParameterTypeRequiredDescription
idstringYesSaved query id
connection_idstringNoConnection id (defaults to the request/header connection)

create_saved_query

Save a query — Write · off by default · needs any of saved_queries:create

Save a query definition for reuse.

ParameterTypeRequiredDescription
namestringYesDisplay name
querystringYesThe SQL to save
descriptionstringNoOptional description

query_raw

Run any SQL — Destructive · off by default · needs any of query:execute:ddl, query:execute:dml

Execute an arbitrary SQL statement (DDL/DML); prefer the read-only 'query' tool for SELECTs. Destructive — enabled by an administrator and limited by your token's scopes; the human approves via the client's permission prompt before the call.

ParameterTypeRequiredDescription
sqlstringYesThe SQL statement to execute
connection_idstringNoConnection id (defaults to the request/header connection)

delete_saved_query

Delete a saved query — Destructive · off by default · needs any of saved_queries:delete

Delete a saved query by id. Destructive — enabled by an administrator and limited by your token's scopes; the human approves via the client's permission prompt before the call.

ParameterTypeRequiredDescription
idstringYesSaved query id

update_saved_query

Edit a saved query — Write · on by default · needs any of saved_queries:update

Change a saved query's name, SQL or description (from list_saved_queries). Only the fields given change. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesSaved query id
namestringNo
querystringNo
descriptionstringNo

share_saved_query

Share a saved query — Write · on by default · needs any of saved_queries:share

Make a saved query visible to everyone who can see saved queries, or private again. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesSaved query id
sharedbooleanYestrue to share with everyone, false to make it private

create_database

Create a database — Write · on by default · needs any of database:create

Create a ClickHouse database on the active connection. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
namestringYes
enginestringNoDatabase engine, default Atomic
clusterstringNoON CLUSTER name

create_table

Create a table — Write · on by default · needs any of table:create

Create a ClickHouse table on the active connection from columns, an engine and keys; CHouse validates every type and key expression. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
databasestringYes
namestringYes
columnsarrayYes
enginestringNoDefault MergeTree()
orderBystringNo
partitionBystringNo
primaryKeystringNo
clusterstringNo

drop_table

Drop a table — Destructive · on by default · needs any of table:drop

Drop a ClickHouse table on the active connection. Irreversible: a second person approves it. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
databasestringYes
tablestringYes

drop_database

Drop a database — Destructive · on by default · needs any of database:drop

Drop a ClickHouse database and every table in it, on the active connection. Irreversible: a second person approves it. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
namestringYes

run_sql_change

Change data or schema with SQL — Write · on by default · needs any of query:execute:dml, query:execute:ddl, table:insert, table:update, table:delete, table:create, table:alter, table:drop, database:create, database:drop

Run one INSERT, UPDATE, DELETE, CREATE, DROP, ALTER or TRUNCATE statement on the active connection. INSERT and CREATE ask once; anything that alters, removes or rewrites data needs a second person's approval. Prefer create_table, drop_table and create_database when they fit. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
sqlstringYesExactly one statement

Data observability

get_dataset_health

Dataset health — Read · on by default · needs any of observe:view

Health of one table: trust state, freshness, volume baseline, open incidents, owners and recent writers. Check this before relying on a table's data.

ParameterTypeRequiredDescription
databasestringYesDatabase name
tablestringYesTable name
connection_idstringNoConnection id (defaults to the request's connection)

get_lineage

Table lineage — Read · on by default · needs any of observe:view

Column-free table lineage around one table: sources, materialized views, dictionaries, scheduled jobs and downstream tables.

ParameterTypeRequiredDescription
databasestringYesDatabase name
tablestringYesTable name
direction`updownboth`
depthnumberNoHops to follow
connection_idstringNoConnection id (defaults to the request's connection)

get_table_context

Table context — Read · on by default · needs any of observe:view

Curated context for a table: description, owner, column meanings, caveats and defined metrics.

ParameterTypeRequiredDescription
databasestringYesDatabase name
tablestringYesTable name
connection_idstringNoConnection id (defaults to the request's connection)

get_metric

Metric definitions — Read · on by default · needs any of observe:view

Defined business metrics (name, SQL expression, table, filters). Use these definitions instead of inventing aggregations.

ParameterTypeRequiredDescription
namestringNoMetric name to look up; omit to list all
connection_idstringNoConnection id (defaults to the request's connection)

get_pipeline_status

Pipeline status — Read · on by default · needs any of observe:view

Ingestion pipelines (Kafka, RabbitMQ, NATS, S3Queue, AzureQueue, refreshable views, scheduled jobs, ...) with one shared status vocabulary, lag and error class.

ParameterTypeRequiredDescription
status`healthylaggingstalled
kindstringNoOnly this source kind (e.g. kafka, s3queue, refreshable_view)
connection_idstringNoConnection id (defaults to the request's connection)

list_incidents

Data incidents — Read · on by default · needs any of observe:view, data_health:view

Data and pipeline incidents with severity, subject and the deterministic root-cause summary when computed.

ParameterTypeRequiredDescription
status`activeall`No
connection_idstringNoConnection id (defaults to the request's connection)

list_remediation_actions

Remediation actions — Read · on by default · needs any of remediation:propose, remediation:approve, remediation:approve_high

Proposed and past fixes on a connection: action type and parameters, who proposed it and why, approvals needed and given, status and the incident it addresses.

ParameterTypeRequiredDescription
statusarrayNoOnly actions in these statuses (e.g. proposed, approved, failed)
incident_idstringNoOnly actions proposed for this incident
connection_idstringNoConnection id (defaults to the request's connection)

get_remediation_action

Remediation action — Read · on by default · needs any of remediation:propose, remediation:approve, remediation:approve_high

One remediation action with its approvals and every execution: the statements run, verification and rollback.

ParameterTypeRequiredDescription
idstringYesRemediation action id

get_investigation_notebook

Investigation notebook — Read · on by default · needs any of data_health:view, observe:view, doctor:view

The investigation notebook of an incident or Doctor report: Chouse AI findings, query snapshots, notes and actions, in order. Needs the view permission of what it belongs to.

ParameterTypeRequiredDescription
attached_to`incident_data_healthincident_observedoctor_report`
refstringYesThe incident id (from list_incidents) or Doctor report id

propose_remediation

Propose a fix — Write · off by default · needs any of remediation:propose

Propose a fix from the closed remediation catalog. This only files a proposal: a human approves it in CHouse UI, the CLI or Slack before anything runs, and the proposer can never approve its own proposal.

ParameterTypeRequiredDescription
typestringYesCatalog action type, e.g. kill_query, optimize_partition, restart_engine_table
paramsrecordYesAction parameters as defined by the remediation catalog
rationalestringYesWhy this fix: the evidence it addresses
incident_source`data_healthobserve`No
incident_idstringNoIncident id this fixes
connection_idstringNoConnection id (defaults to the request's connection)

Data health

list_health_checks

List data health promises — Read · on by default · needs any of data_health:view

List data-health promises (checks).

No parameters.

get_health_check

Get a data health promise — Read · on by default · needs any of data_health:view

Get one data-health check by id, including its incidents.

ParameterTypeRequiredDescription
idstringYesData-health check id

health_timeline

Data health timeline — Read · on by default · needs any of data_health:view

Evaluation timeline for one data-health check.

ParameterTypeRequiredDescription
idstringYesData-health check id

run_health_check

Run a data health check — Write · off by default · needs any of data_health:run

Evaluate a data-health check now.

ParameterTypeRequiredDescription
idstringYesResource id

acknowledge_incident

Acknowledge an incident — Write · off by default · needs any of data_health:edit

Acknowledge an open data-health incident.

ParameterTypeRequiredDescription
idstringYesResource id

create_health_promise

Create a data health promise — Write · on by default · needs any of data_health:edit

Create a data health promise on a table of the active connection: checks (freshness, volume, nulls…) evaluated on a schedule. Use the check definitions recommend_health_promise or the data health docs describe. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
namestringYes
descriptionstringNo
databasestringYes
tablestringYes
eventTimeColumnstringNoColumn holding each row's event time, for freshness and slot checks
eventTimeEncoding`nativeunix_secondsunix_milliseconds
eventTimeTimezonestringNoIANA timezone of string event-time values (string only)
criticality`standardimportantcritical`
frequency`dailyweeklymonthly
hournumberNoHour of day (daily, weekly, monthly)
dayOfWeeknumberNo0 = Sunday (weekly)
dayOfMonthnumberNoDay of month (monthly)
cronExprstringNoCron expression (frequency cron)
timezonestringNoIANA timezone, default UTC
checksarrayYesCheck definitions, each with a type and its settings

watch_table

Keep an eye on a table — Write · on by default · needs any of data_health:edit

Watch a table on the active connection for a while ("keep an eye on shop.orders until tomorrow"): a personal Data Health promise, checked every 15 minutes, that says when new rows stop arriving and removes itself when the watch ends — 09:00 tomorrow by default, at most 7 days, five per connection. Needs the table's event-time column (look it up with the table's columns first). Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
databasestringYes
tablestringYes
eventTimeColumnstringYesColumn holding each row's event time: the watch checks that new rows keep arriving
eventTimeEncoding`nativeunix_secondsunix_milliseconds
maxAgeMinutesnumberNoThe newest row may be at most this old (default 60)
untilstringNoWhen the watch ends, ISO 8601 (e.g. 2026-10-25T09:00:00Z); default 09:00 tomorrow
timezonestringNoIANA timezone for the default end (09:00 tomorrow); default UTC

update_health_promise

Edit a data health promise — Write · on by default · needs any of data_health:edit

Change a promise's name, description, criticality, schedule, thresholds (grace, breach/recover after) or its whole list of checks. Only the fields given change. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesData Health promise id (from list_health_checks)
namestringNo
descriptionstringNo
criticality`standardimportantcritical`
frequency`dailyweeklymonthly
hournumberNoHour of day (daily, weekly, monthly)
dayOfWeeknumberNo0 = Sunday (weekly)
dayOfMonthnumberNoDay of month (monthly)
cronExprstringNoCron expression (frequency cron)
graceSecsnumberNo
breachAfternumberNo
recoverAfternumberNo
checksarrayNoReplaces every check

pause_health_promise

Pause a data health promise — Write · on by default · needs any of data_health:edit

Stop a promise's checks from running until it is resumed. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesData Health promise id (from list_health_checks)

resume_health_promise

Resume a data health promise — Write · on by default · needs any of data_health:edit

Let a paused promise's checks run on their schedule again. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesData Health promise id (from list_health_checks)

acknowledge_health_incident

Acknowledge a data health incident — Write · on by default · needs any of data_health:edit

Mark a data health incident as acknowledged (someone is on it). Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesData Health incident id (from list_health_incidents)

snooze_health_incident

Snooze a data health incident — Write · on by default · needs any of data_health:edit

Silence a data health incident's notifications for a number of hours. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesData Health incident id (from list_health_incidents)
hoursnumberYesHow long, in hours (up to a week)

delete_health_promise

Delete a data health promise — Write · on by default · needs any of data_health:delete

Delete a promise with its checks, samples and incident history. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesData Health promise id (from list_health_checks)

Performance, capacity & upgrades

get_query_regressions

Query regressions — Read · on by default · needs any of performance:view

Query shapes that got slower or heavier than their own baseline, with the upgrades, DDL and setting changes around their onset, plus hourly totals. Sample query text is included only with query:history:view:all.

ParameterTypeRequiredDescription
connection_idstringNoConnection id (defaults to the request's connection)

get_query_shape_history

Query shape history — Read · on by default · needs any of performance:view

Hourly runs, errors, p50/p95 latency, bytes read and server version of one query shape, per replica.

ParameterTypeRequiredDescription
fingerprintstringYesQuery shape fingerprint from get_query_regressions
connection_idstringNoConnection id (defaults to the request's connection)

get_capacity

Capacity and cost — Read · on by default · needs any of capacity:view

Disk forecasts per node (days until the threshold), the fastest-growing tables, cold tables, measured codec savings, and cost by consumer when the token also has cost:view.

ParameterTypeRequiredDescription
connection_idstringNoConnection id (defaults to the request's connection)

list_upgrade_assessments

Upgrade assessments — Read · on by default · needs any of upgrades:view

Upgrade checks of a connection: target version, mode and counts by severity.

ParameterTypeRequiredDescription
connection_idstringNoConnection id (defaults to the request's connection)

get_upgrade_assessment

Upgrade assessment — Read · on by default · needs any of upgrades:view

One upgrade check: what upgrading to the target changes for the real workload (removed functions, types and engines in use, changed defaults, obsolete settings, release notes to judge), with the evidence and sources behind each finding. A check started a moment ago may still be running; its summary.stage says how far it got.

ParameterTypeRequiredDescription
idstringYesAssessment id

get_upgrade_status

Upgrade status — Read · on by default · needs any of upgrades:view

A connection's ClickHouse version, whether it is still supported, whether a newer patch exists, and the upgrade targets on offer (recommended LTS first). Support data needs UPGRADE_CHECK_ENABLED on the server.

ParameterTypeRequiredDescription
connection_idstringNoConnection id (defaults to the request's connection)

Dashboards

list_dashboards

List dashboards — Read · on by default · needs any of dashboards:view

Dashboards this token's user may view (own, shared with their roles, or all with dashboards:manage), with panel counts and access.

No parameters.

get_dashboard

Get a dashboard — Read · on by default · needs any of dashboards:view

One dashboard: its variables, panels (SQL and chart settings), shares, lint findings and the caller's access.

ParameterTypeRequiredDescription
idstringYesDashboard id (from list_dashboards)

export_dashboard

Export a dashboard — Read · on by default · needs any of dashboards:view

A dashboard as JSON (format chouse.dashboard/v2) that apply_dashboard and the CLI take — to review or keep in git.

ParameterTypeRequiredDescription
idstringYesDashboard id (from list_dashboards)

run_dashboard_panel

Run a dashboard panel — Read · on by default · needs any of dashboards:view

Run one panel's read-only query for a time range and variable values, with the caller's own data access. Returns columns and rows (at most 10,000), or for a fleet panel one result per connection.

ParameterTypeRequiredDescription
idstringYesDashboard id
panel_idstringYesPanel id (from get_dashboard)
range`15m1h3h
valuesrecordNoVariable values by name: a string, or a list for a multi-value variable; a variable left out uses its default
connection_idstringNoConnection to run on (defaults to the request/header connection); a fleet panel runs on every connection

list_dashboard_versions

List dashboard versions — Read · on by default · needs any of dashboards:view

The last 50 saves of a dashboard, newest first: version number, who saved it, when, and how (UI, token, import, restore, rollup…).

ParameterTypeRequiredDescription
idstringYesDashboard id (from list_dashboards)

get_dashboard_annotations

Get dashboard annotations — Read · on by default · needs any of dashboards:view

What changed around a dashboard's charts in a range — DDL, upgrades, settings, new writers, panel alerts, incidents, fixes and notes — read with the caller's own access. Each kind says whether it could be read and why not.

ParameterTypeRequiredDescription
idstringYesDashboard id
range`15m1h3h
sourcesarrayNoWhich kinds of event to read (default: every kind): DDL, upgrades, settings changes, new writers, panel alerts, incidents, fixes, notes
connection_idstringNoConnection whose events to read (defaults to the request/header connection)

create_dashboard_snapshot

Snapshot a dashboard — Write · off by default · needs any of dashboards:view, query:execute

Freeze every chart panel's result for a range ending now, as the caller, so it can be shared after the data moves on (at most 10 MiB). Whoever opens it still only sees what their own access allows.

ParameterTypeRequiredDescription
idstringYesDashboard id
namestringYesSnapshot name
range`15m1h3h
valuesrecordNoVariable values by name: a string, or a list for a multi-value variable; a variable left out uses its default
role_idsarrayNoRoles (from the dashboard's shares) that may open it besides you; default none
expires_in_daysnumberNoDays until it expires (default 30)
connection_idstringNoConnection to run on (defaults to the request/header connection); a fleet panel runs on every connection

apply_dashboard

Create or update a dashboard — Write · off by default · needs any of dashboards:edit

Create a dashboard from an export, or update the one its id names to match it exactly (panels left out are removed with their alerts). Every panel is validated like a save in the UI; nothing is partly applied.

ParameterTypeRequiredDescription
dashboardrecordYesA dashboard export ({format: "chouse.dashboard/v2", id, dashboard}) as export_dashboard returns it; a chouse.dashboard/v1 export from before CHouse 3.16 is converted. With an id, that dashboard is updated in place (its panel ids are kept); with id null, a new dashboard is created.

delete_dashboard

Delete a dashboard — Destructive · off by default · needs any of dashboards:delete

Delete a dashboard with its panels, shares, pins and panel alerts. Destructive — enabled by an administrator and limited by your token's scopes; the human approves via the client's permission prompt before the call.

ParameterTypeRequiredDescription
idstringYesDashboard id (from list_dashboards)

create_dashboard

Create a dashboard — Write · on by default · needs any of dashboards:edit

Create a dashboard on the active connection from panels (title, SQL, chart type and columns). Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
titlestringYes
descriptionstringNo
timeRange`15m1h3h
panelsarrayYes

update_dashboard

Edit a dashboard — Write · on by default · needs any of dashboards:edit

Change a dashboard's title, description, default time range or auto-refresh. Only the fields given change. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesDashboard id (from list_dashboards)
titlestringNo
descriptionstringNo
timeRange`15m1h3h
refreshSecondsunionNo

add_panel

Add a dashboard panel — Write · on by default · needs any of dashboards:edit

Add a chart panel (title, read-only SQL, chart type, x and y columns) at the bottom of a dashboard. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
titlestringYes
sqlstringYesRead-only SELECT; may use {{from}} / {{to}} time-range macros
chart`barhorizontal_bargrouped_bar
xstringNox column (not for stat or table)
yarrayNoy columns (stat: exactly one; table and histogram: none)
idstringYesDashboard id (from list_dashboards)

update_panel

Edit a dashboard panel — Write · on by default · needs any of dashboards:edit

Change a chart panel's title, SQL, chart type or columns. Only the fields given change; its place on the canvas stays. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesDashboard id (from list_dashboards)
panelIdstringYesPanel id (from get_dashboard)
titlestringNo
sqlstringNo
chart`barhorizontal_bargrouped_bar
xstringNo
yarrayNo

remove_panel

Remove a dashboard panel — Write · on by default · needs any of dashboards:edit

Remove a panel from a dashboard (its alerts go with it). Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesDashboard id (from list_dashboards)
panelIdstringYesPanel id (from get_dashboard)

restore_dashboard_version

Restore a dashboard version — Write · on by default · needs any of dashboards:edit

Save an older version of a dashboard (from its version history) as the newest one. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesDashboard id (from list_dashboards)
versionnumberYes

add_dashboard_note

Add a dashboard note — Write · on by default · needs any of dashboards:edit

Pin a note to a moment on a dashboard's timeline (e.g. a deploy), on the active connection. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesDashboard id (from list_dashboards)
textstringYes
atstringNoISO time; default now

delete_dashboard_note

Delete a dashboard note — Write · on by default · needs any of dashboards:view

Delete a note from a dashboard's timeline (yours, or any if you can edit the dashboard). Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesDashboard id (from list_dashboards)
noteIdstringYes

share_dashboard

Share a dashboard — Write · on by default · needs any of dashboards:share

Set which roles can see a dashboard, and which of them can edit it. Replaces the current shares. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesDashboard id (from list_dashboards)
sharesarrayYes

update_table_context

Update table context — Write · on by default · needs any of context:edit

Set a table's curated context (description, grain, owner, tags) that every agent and person reads. Only the fields given change. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
databasestringYes
tablestringYes
descriptionstringNo
grainstringNoWhat one row is, e.g. one order line
ownerstringNo
tagsarrayNo

upsert_metric

Define a metric — Write · on by default · needs any of context:edit

Define (or redefine, by name) a business metric on a table: an aggregate SQL expression every agent and person reads, e.g. revenue = sum(price * qty). Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
databasestringYes
tablestringYes
namestringYes
expressionstringYes
descriptionstringNo
ownerstringNo

delete_metric

Delete a metric — Write · on by default · needs any of context:edit

Delete a table's business metric by name. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
databasestringYes
tablestringYes
namestringYes

Monitoring

metrics_overview

Server metrics — Read · on by default · needs any of metrics:view

Server metrics overview: cluster stats and current load.

No parameters.

live_queries

Running queries — Read · on by default · needs any of live_queries:view

List currently running ClickHouse queries.

No parameters.

fleet_snapshots

Fleet health — Read · on by default · needs any of fleet:view

Latest fleet health snapshots across connections.

No parameters.

list_alerts

Alert rules and channels — Read · on by default · needs any of alerting:view

List alerting: channels (with delivery health and what uses each; secrets redacted), rules, sources (everything that sends alerts, as far as you can see), overview, or events (history; filter with q, source, severity, channelId, failed, from, to, and page with cursor; without filters it is the newest events).

ParameterTypeRequiredDescription
kind`channelsrulessources
qstringNoevents: words in the alert
sourcestringNoevents: fleet_alert, fleet_rca, dashboard_alert, dashboard_report, scheduled_query, data_health, triage
severity`infowarningcritical`
channelIdstringNoevents: reached this channel
failedbooleanNoevents: true for ones some channel failed to get
fromnumberNoevents: fired at or after (epoch ms)
tonumberNoevents: fired before (epoch ms)
cursorstringNoevents: nextCursor from the previous page
limitnumberNoevents: page size (default 50)

audit_list

Audit log — Read · on by default · needs any of audit:view

List the caller's audit trail (global entries require audit:view).

ParameterTypeRequiredDescription
limitnumberNoEntries to return

get_collector_status

Collector status — Read · on by default · needs any of observe:view

Each observability collector of a connection: state, last run and last success, last error, missing grants, whether it is paused, and what its last run read from ClickHouse. Use it when observability data looks stale or missing.

ParameterTypeRequiredDescription
connection_idstringNoConnection id (defaults to the request's connection)

get_collector_schedule

Collection schedule — Read · on by default · needs any of connections:view

How often each observability collector runs and whether it is paused: the defaults, or one connection's effective schedule with its overrides, each collector's last run, and the bytes it reads from ClickHouse per day at that interval.

ParameterTypeRequiredDescription
connection_idstringNoA connection's effective schedule; omit for the defaults every connection inherits

test_alert_channel

Test an alert channel — Write · off by default · needs any of alerting:edit

Send a test notification through an alert channel (this pages people).

ParameterTypeRequiredDescription
idstringYesResource id

kill_query

Kill a query — Destructive · off by default · needs any of live_queries:kill, live_queries:kill_all

Terminate a running ClickHouse query by query_id. Destructive — enabled by an administrator and limited by your token's scopes; the human approves via the client's permission prompt before the call.

ParameterTypeRequiredDescription
query_idstringYesquery_id of the running query (see live_queries)
connection_idstringNoConnection id (defaults to the request/header connection)

create_alert_rule

Create an alert rule — Write · on by default · needs any of alerting:edit

Create an alert rule that notifies channels (from list_alerting) when its condition fires. Fleet threshold rules use config keys memoryPercent, queryMemoryGb, longQueryMin, partsEtaMin; only one fleet rule may be enabled. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
namestringYes
sourceType`fleet_thresholddata_quality`No
severity`infowarningcritical`
enabledbooleanNo
configrecordNo
channelIdsarrayNo

update_alert_rule

Edit an alert rule — Write · on by default · needs any of alerting:edit

Change an alert rule's name, severity, thresholds (config), channels or whether it is on. Only the fields given change. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesAlert rule id (from list_alerting with kind rules)
namestringNo
severity`infowarningcritical`
enabledbooleanNo
configrecordNoReplaces the rule's config
channelIdsarrayNo

mute_alert_rule

Mute an alert rule — Write · on by default · needs any of alerting:edit

Turn an alert rule off so it stops notifying; undo (or update_alert_rule with enabled true) turns it back on. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesAlert rule id (from list_alerting with kind rules)

post_alert_message

Post to an alert channel — Write · on by default · needs any of alerting:edit

Post a short message to an alert channel (Slack, email…) — a handoff, a status update. It reaches real people and cannot be taken back, so write it for them. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesAlert channel id (from list_alerting with kind channels)
titlestringYes
textstringYes

clear_alert_events

Clear recent alerts — Write · on by default · needs any of alerting:delete

Delete fired alert events: all of them, or those older than a number of hours. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
olderThanHoursnumberNoOnly events older than this; omit for all

acknowledge_observe_incident

Acknowledge an observability incident — Write · on by default · needs any of observe:edit

Mark an observability incident (from list_observe_incidents) as acknowledged. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYes

dismiss_suggestion

Dismiss an Observe suggestion — Write · on by default · needs any of observe:edit

Hide an Observe suggestion (by its key) so it is not offered again. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
keystringYes

pin_table_criticality

Set a table's criticality — Write · on by default · needs any of observe:edit

Pin how critical a table is (critical, important, standard), or clear the pin with null so Observe infers it. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
databasestringYes
tablestringYes
criticality`criticalimportantstandard`

add_notebook_cell

Add to an investigation notebook — Write · on by default · needs any of notebooks:edit

Add a note or a query to the investigation notebook of an incident or Doctor report (created if it has none). Query cells run once when added. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
attachedTo`incident_data_healthincident_observedoctor_report`
refstringYesThe incident or report id
kind`notequery`Yes
textstringNoNote text (kind note)
sqlstringNoRead-only SELECT (kind query)
titlestringNoQuery cell title

update_cost_rates

Set cost rates — Write · on by default · needs any of settings:update

Set the prices Observe uses to estimate query cost: per TiB read and per CPU hour, in a currency. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
currencystringYes
perTibReadnumberYes
perCpuHournumberYes

update_collector_schedule

Change the collection schedule — Write · on by default · needs any of connections:edit

Change how often Observe collectors run on the active connection, or pause them. Keys are collector names (from get_collector_schedule); a null value inherits the default. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
collectorsrecordYes

start_codec_trial

Try a column codec — Write · on by default · needs any of upgrades:run

Measure how a different compression codec would do on one column, by writing a sample to a scratch table on the active connection. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
databasestringYes
tablestringYes
columnstringYes
candidateCodecstringYes

run_doctor_scan

Run a Doctor scan — Write · on by default · needs any of doctor:run

Run the fleet Doctor now over the last hours of metrics (it uses the AI model and takes a while). Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
hoursnumberNo
connectionIdsarrayNoDefault: every connection

update_doctor_schedule

Schedule the Doctor — Write · on by default · needs any of doctor:run

Turn the scheduled Doctor scan on or off and set when it runs. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
enabledbooleanYes
frequency`dailyweeklymonthly`
hournumberYes
dayOfWeeknumberNo
dayOfMonthnumberNo
hoursnumberNoHours of metrics each scan reads
connectionIdsarrayNo
deliverbooleanNoSend each report to the alert channels

update_fleet_alert_config

Change fleet alert thresholds — Write · on by default · needs any of settings:update

Turn fleet threshold alerts on or off and set their thresholds. Notification channels and their secrets are left as they are. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
enabledbooleanYes
memoryPercentnumberYes
queryMemoryGbnumberYes
longQueryMinnumberYes
partsEtaMinnumberNo

run_upgrade_assessment

Assess an upgrade — Write · on by default · needs any of upgrades:run

Check what upgrading the active connection's ClickHouse to a version changes for its workload. With referenceConnectionId (a connection already on the target line) it compares both servers exactly; otherwise it reads the release notes. Runs in the background: read the result with get_upgrade_assessment. It also plans the workload's top query shapes on this server with the target's settings (EXPLAIN only) unless tryQueries is false. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
targetVersionstringYes
referenceConnectionIdstringNo
tryQueriesbooleanNo

Scheduled queries

list_scheduled_jobs

List scheduled jobs — Read · on by default · needs any of scheduled_queries:view

List scheduled queries.

No parameters.

get_scheduled_job

Get a scheduled job — Read · on by default · needs any of scheduled_queries:view

Get one scheduled query by id.

ParameterTypeRequiredDescription
idstringYesScheduled query id

list_scheduled_runs

Scheduled job runs — Read · on by default · needs any of scheduled_queries:view

Run history for one scheduled query.

ParameterTypeRequiredDescription
idstringYesScheduled query id

run_scheduled_job

Run a scheduled job now — Write · off by default · needs any of scheduled_queries:run

Trigger a scheduled query to run now.

ParameterTypeRequiredDescription
idstringYesResource id

delete_scheduled_job

Delete a scheduled job — Destructive · off by default · needs any of scheduled_queries:delete

Delete a scheduled query by id. Destructive — enabled by an administrator and limited by your token's scopes; the human approves via the client's permission prompt before the call.

ParameterTypeRequiredDescription
idstringYesScheduled query id

create_scheduled_query

Schedule a query — Write · on by default · needs any of scheduled_queries:edit

Create a scheduled report query (read-only SELECT, no materialization) on the active connection. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
namestringYes
descriptionstringNo
querystringYesRead-only SELECT
frequency`dailyweeklymonthly
hournumberNoHour of day (daily, weekly, monthly)
dayOfWeeknumberNo0 = Sunday (weekly)
dayOfMonthnumberNoDay of month (monthly)
cronExprstringNoCron expression (frequency cron)
timezonestringNoIANA timezone, default UTC

update_scheduled_job

Edit a scheduled query — Write · on by default · needs any of scheduled_queries:edit

Change a scheduled query's name, description, SQL, schedule, row limit or timeout. Only the fields given change; its connection and output never do. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesScheduled query id (from list_scheduled_jobs)
namestringNo
descriptionstringNo
querystringNoRead-only SELECT
frequency`dailyweeklymonthly
hournumberNoHour of day (daily, weekly, monthly)
dayOfWeeknumberNo0 = Sunday (weekly)
dayOfMonthnumberNoDay of month (monthly)
cronExprstringNoCron expression (frequency cron)
timezonestringNoIANA timezone, default UTC
maxRowsnumberNo
timeoutSecsnumberNo

pause_scheduled_job

Pause a scheduled query — Write · on by default · needs any of scheduled_queries:edit

Stop a scheduled query from running until it is resumed. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesScheduled query id (from list_scheduled_jobs)

resume_scheduled_job

Resume a scheduled query — Write · on by default · needs any of scheduled_queries:edit

Let a paused scheduled query run on its schedule again. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesScheduled query id (from list_scheduled_jobs)

Chouse AI

ai_optimize

Optimize a query with AI — Read · spends LLM budget · off by default · needs any of ai:optimize

Ask the AI optimizer to analyze a SQL query and suggest rewrites (spends LLM budget).

ParameterTypeRequiredDescription
sqlstringYesThe SQL query to optimize
connection_idstringNoConnection id (defaults to the request/header connection)

doctor_scan

Run a Doctor scan — Write · spends LLM budget · off by default · needs any of doctor:run

Run the AI fleet doctor across connections and return a structured report (spends LLM budget).

ParameterTypeRequiredDescription
hoursnumberNoLookback window in hours

doctor_reports

List Doctor reports — Read · on by default · needs any of doctor:view

List past AI doctor reports.

No parameters.

get_doctor_report

Get a Doctor report — Read · on by default · needs any of doctor:view

Get one AI doctor report by id.

ParameterTypeRequiredDescription
idstringYesDoctor report id

get_action_status

Check a write action — Write · on by default · any token

Check a write action this token started (by the actionId a write tool returned). If the user has confirmed it since, it runs now and the result comes back.

ParameterTypeRequiredDescription
action_idstringYesThe actionId a write tool returned

undo_action

Undo a write action — Write · on by default · any token

Undo an undoable action this user made (within 24 hours). Refused when the object changed since, so nobody's later change is overwritten.

ParameterTypeRequiredDescription
action_idstringYesThe actionId a write tool returned

AI governance

get_ai_usage

AI usage — Read · on by default · needs any of ai_usage:view, ai:chat, ai:optimize

What CHouse's AI chat and features used in a window: requests, tokens, estimated cost (priced models only), ClickHouse read by AI tools, rows sent to providers, the split by origin (UI, MCP agents, tokens, background) and usage by model. scope says whether it covers everyone (ai_usage:view) or only the token owner's own requests.

ParameterTypeRequiredDescription
daysnumberNoWindow in days (default 7; capped at the server's retention)

get_ai_data_egress

Data sent to AI providers — Read · on by default · needs any of ai_usage:view, ai:chat, ai:optimize

Tables, columns and CHouse record types that AI tools returned to an LLM provider, most rows first: rows, bytes, users, requests and providers per source.

ParameterTypeRequiredDescription
daysnumberNoWindow in days (default 7; capped at the server's retention)
qstringNoOnly sources whose name contains this text (a table or CHouse record type)

list_ai_requests

AI requests — Read · on by default · needs any of ai_usage:view, ai:chat, ai:optimize

Recent AI requests, newest first: who and what started each (origin, token, client), the agent, tokens, cost, ClickHouse read, rows sent and status. Prompt and response text are never stored.

ParameterTypeRequiredDescription
daysnumberNoWindow in days (default 7; capped at the server's retention)
qstringNoMatch on user, agent, feature, client, token name or a table sent to the model
origin`uimcptoken
limitnumberNoRows to return (default 50)
offsetnumberNoRows to skip, for paging

get_ai_request

AI request — Read · on by default · needs any of ai_usage:view, ai:chat, ai:optimize

One AI request step by step: each LLM call with tokens and cost, each tool call with the ClickHouse queries it ran and the data it sent to the model.

ParameterTypeRequiredDescription
idstringYesAI request id from list_ai_requests

list_ai_agents

AI agents — Read · on by default · needs any of ai_agents:view

How CHouse's AI is set up: which agent each AI feature runs, and each agent's model, harness, tools, skills, subagents and tuning, whether it is built in or customized and has an update. Prompt templates and skill files are left out.

No parameters.

list_ai_guardrails

AI guardrails — Read · on by default · needs any of ai_guardrails:view

The guardrails every CHouse AI run (and, where enabled, every MCP tool result) passes through: kind, stages, action, shadow or enforce mode, scope, order, whether it is on, and its triggers in the last 24 hours.

No parameters.

list_ai_guardrail_triggers

AI guardrail triggers — Read · on by default · needs any of ai_guardrails:view

Recent guardrail triggers, newest first: guardrail, stage, action, mode, how many values matched, agent and tool, and the AI request. Returns the total too; page with limit and offset. Matched values are never stored.

ParameterTypeRequiredDescription
daysnumberNoWindow in days (default 7; capped at the server's retention)
guardrailIdstringNoOnly this guardrail's triggers (id from list_ai_guardrails)
limitnumberNoRows to return (default 100)
offsetnumberNoRows to skip, for paging

draft_ai_agent

Draft an AI agent — Write · on by default · needs any of ai_agents:manage

Save a new custom chat agent as a disabled draft: a prompt and the catalog tools it may use. Nobody can chat with it until it is published. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
slugstringYes
namestringYes
descriptionstringYes
systemPromptstringYes
toolsarrayYesCatalog tool names
subagentsarrayNoAgent ids

run_ai_eval

Run an agent's evals — Write · on by default · needs any of ai_agents:manage

Run an agent's eval cases and score them (it calls the AI model once per case). Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
agentIdstringYes

publish_ai_agent

Publish an AI agent — Destructive · on by default · needs any of ai_agents:manage

Turn a drafted (disabled) custom agent on so people can chat with it. If the agent has an eval threshold, its evals must pass first. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYes

Access

create_user

Create a user — Destructive · on by default · needs any of users:create

Create a CHouse user with one role. CHouse generates their password and never shows it to the assistant: set it in Admin › Users, or the user signs in with SSO. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
emailstringYes
usernamestringYes
displayNamestringNo
roleIdstringNoRole id (from list_roles)

update_user

Edit a user — Destructive · on by default · needs any of users:update

Change a user's email, username or display name. Use assign_role to change their role, deactivate_user to block them. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYesUser id (from list_users)
emailstringNo
usernamestringNo
displayNamestringNo

deactivate_user

Deactivate a user — Destructive · on by default · needs any of users:update

Block a user from signing in (their sessions end); activate them again with active true. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYes
activebooleanNo

assign_role

Assign a role — Destructive · on by default · needs any of roles:assign

Give a user a role (a user has exactly one; this replaces it). You can only grant roles whose permissions you hold. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
userIdstringYes
roleIdstringYes

create_role

Create a role — Destructive · on by default · needs any of roles:create

Create a role from permission ids (list_permissions) and at least one data access policy (list_data_access_policies). You can only include permissions you hold. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
namestringYes
displayNamestringYes
descriptionstringNo
permissionIdsarrayYes
dataAccessPolicyIdsarrayYes

update_role

Edit a role — Destructive · on by default · needs any of roles:update

Change a role's name, description, permissions or data access policies. Lists replace what the role has. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYes
displayNamestringNo
descriptionstringNo
permissionIdsarrayNo
dataAccessPolicyIdsarrayNo

delete_role

Delete a role — Destructive · on by default · needs any of roles:delete

Delete a custom role (system roles and roles still assigned to users cannot be deleted). Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYes

create_data_access_policy

Create a data access policy — Destructive · on by default · needs any of data_access:create

Create a data access policy: rules allowing or denying database/table patterns, on one connection or all. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
namestringYes
descriptionstringNo
rulesarrayYes

update_data_access_policy

Edit a data access policy — Destructive · on by default · needs any of data_access:update

Change a data access policy's name, description or rules (the rules list replaces the current one). Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYes
namestringNo
descriptionstringNo
rulesarrayNo

delete_data_access_policy

Delete a data access policy — Destructive · on by default · needs any of data_access:delete

Delete a data access policy (system policies cannot be deleted). Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
idstringYes

set_role_policies

Set a role's data access policies — Destructive · on by default · needs any of data_access:assign

Replace the data access policies attached to a role — which connections, databases and tables its users can reach. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
roleIdstringYes
policyIdsarrayYes

create_clickhouse_role

Create a ClickHouse role — Destructive · on by default · needs any of clickhouse:roles:create

Create a role in ClickHouse itself (on the active connection) with structured grants. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
namestringYes
clusterstringNo
grantsarrayYes

update_clickhouse_role

Change a ClickHouse role's grants — Destructive · on by default · needs any of clickhouse:roles:update

Replace the grants of a ClickHouse role on the active connection. Write tool: CHouse decides per call how it is checked — undoable changes run at once, others wait for the user's confirmation in CHouse, and high-risk ones go to a second approver. When a call returns a pending actionId, tell the user and check it later with get_action_status.

ParameterTypeRequiredDescription
namestringYes
clusterstringNo
grantsarrayYes