CHouseUI
Using CHouse UIAI agents

AI tool catalog

Every read-only tool agents can use, the DeepAgents built-in tools each harness keeps, and the built-in skills — generated from the server.

Source
Generated from packages/server/src/services/ai/registry (catalog, harness) and seeds, so it always matches the code.

Everything an agent in AI Governance › Assistant is built from that is defined in code: the 142 catalog tools, the built-in DeepAgents tools a harness can hide, and the 14 skills CHouse ships. How to use them is in AI agents, Harnesses and Skills.

Catalog tools only read, except the action tools, which wait for a person to approve each call. Context is what the run must provide — a tool whose context a feature doesn't provide is left out of that feature's runs (see contexts). Needs any of applies to the CHouse tools: the chat user must hold one of the permissions or the tool isn't offered, and the API behind it still checks every call as that user. Results of CHouse tools are capped at 100 rows, 2 KB per cell and 60 KB in all, and secrets are redacted.

ClickHouse tools

ToolTitleContextNeeds any ofWhat it doesBuilt-in agents
list_databasesList databasesClickHouse session—List all available database names. Results are filtered by user permissions.6
list_tablesList tablesClickHouse session—List all tables in a specific database. Results are filtered by user permissions.6
get_table_schemaTable schemaClickHouse session—Get column names and types for a specific table.9
get_table_ddlTable DDLClickHouse session—Get the CREATE TABLE statement (DDL) for a specific table. Use this to understand table engines, sorting keys, partition keys, and index settings.9
get_table_sizeTable sizeClickHouse session—Get row count and disk size for a specific table.4
get_table_sampleSample rowsClickHouse session—Get first 5 rows of a table to preview the data.4
run_select_queryRun SELECTClickHouse session—Execute a read-only SELECT query. Only SELECT and WITH queries are allowed. LIMIT 100 is added automatically if the query has no LIMIT. Results limited to 100 rows. NEVER include a FORMAT clause — the application handles formatting internally.4
explain_queryEXPLAIN a queryClickHouse session—Get the EXPLAIN plan for a query to understand how ClickHouse will execute it. Useful for understanding index usage, partition pruning, and join strategies. NEVER include a FORMAT clause in the sql parameter.5
get_database_infoDatabase overviewClickHouse session—Get table count and total size for a specific database.4
get_running_queriesRunning queriesClickHouse session—List currently running queries on the ClickHouse server.4
get_server_infoServer infoClickHouse session—Get ClickHouse server version and uptime.4
search_columnsSearch columnsClickHouse session—Search for columns by name pattern across all accessible tables.4
analyze_queryAnalyze a queryClickHouse session—Analyze a SQL query for complexity, performance characteristics, and get optimization recommendations.7
validate_sqlValidate SQLClickHouse session—Check if a SQL string is valid syntax. Does not execute the query. Use when the user wants to check syntax or validate a query before running.6
export_query_resultExport a resultClickHouse session—Run a read-only SELECT query and return the result as a CSV or JSON string. Use when the user explicitly asks to export, download, or get data as CSV/JSON. Limited to 1000 rows. NEVER include a FORMAT clause in the sql — the format parameter controls output format instead.4
get_slow_queriesSlow queriesClickHouse session—List recently executed queries that were slow (by duration). Useful for troubleshooting and finding heavy queries. Non-admin users see only their own queries.4
render_chartRender a chartClickHouse session—MANDATORY: Use this whenever the user asks to visualize, chart, plot, graph, or show trends. Execute a SELECT query and return an interactive chart specification. Available chartType values: bar, horizontal_bar, grouped_bar, stacked_bar, line, multi_line, area, stacked_area, pie, donut, scatter, radar, treemap, funnel, histogram, heatmap. xAxis and yAxis can be omitted — they will be inferred from the query result columns.2
generate_queryDraft SQL from a description——Generate a SQL query based on a natural language description. Use this after gathering schema information from other tools. After calling this, you MUST output the generated query in a sql code block. If the user wants the query executed, call run_select_query with that SQL.2
optimize_queryOptimize a query (runs the optimize-query feature)ClickHouse session—Get AI-powered optimization suggestions for a SQL query.2
run_bounded_aggregateRun a bounded aggregateClickHouse session—Run one read-only aggregate SELECT for a health recommendation. Raw-row SELECTs and SELECT * are rejected.1
query_nodeQuery a node's system tablesFleet nodes—Run ONE read-only SQL SELECT against a node's system.* tables to investigate (processes, replicas, merges, mutations, query_log, parts, asynchronous_metrics, …). Read-only: writes/DDL/KILL are rejected. Returns up to 100 rows.6

CHouse tools

ToolTitleContextNeeds any ofWhat it doesBuilt-in agents
whoamiWho am IYour CHouse access—The signed-in CHouse user: id, email, username, roles and effective permissions.3
list_usersList usersYour CHouse accessusers:viewList CHouse users with their roles and status. Optional search text and role filter.1
get_userGet a userYour CHouse accessusers:viewOne CHouse user by id, with roles and permissions.1
list_rolesList rolesYour CHouse accessroles:viewList CHouse roles with their permissions and user counts.1
get_roleGet a roleYour CHouse accessroles:viewOne CHouse role by id with its permission list.1
list_permissionsPermission catalogYour CHouse accessroles:viewEvery CHouse permission grouped by category, with display names.1
list_data_access_policiesData access policiesYour CHouse accessdata_access:viewData access policies (which roles may read/write which databases and tables, per connection).1
list_my_access_tokensMy access tokensYour CHouse access—Your personal access tokens: name, scopes, expiry and last use (never the secret).1
list_clickhouse_usersClickHouse usersYour CHouse accessclickhouse:users:viewUsers defined in ClickHouse itself on the active connection.1
list_clickhouse_rolesClickHouse rolesYour CHouse accessclickhouse:roles:viewRoles defined in ClickHouse itself on the active connection.1
get_sso_settingsSSO settingsYour CHouse accesssso:viewSingle sign-on settings and configured identity providers (secrets redacted).1
list_connectionsConnectionsYour CHouse accessconnections:viewClickHouse connections registered in CHouse (host, port, status; never passwords).1
list_ai_modelsAI modelsYour CHouse accessai_models:viewConfigured AI models and providers, which one is the default, and their runtime parameters (API keys redacted).1
audit_logAudit logYour CHouse accessaudit:viewRecent audit log entries, newest first. Filter by action (e.g. user.update), username or status.1
list_scheduled_jobsScheduled jobsYour CHouse accessscheduled_queries:viewScheduled queries you can see: schedule, owner, last run status and next run.1
get_scheduled_jobScheduled jobYour CHouse accessscheduled_queries:viewOne scheduled query by id with its definition.1
list_scheduled_runsScheduled runsYour CHouse accessscheduled_queries:viewRecent runs of one scheduled query: status, duration, rows, error.1
list_health_checksData health promisesYour CHouse accessdata_health:viewData Health promises you can see with their current status.1
get_health_checkData health promiseYour CHouse accessdata_health:viewOne Data Health promise by id with its checks.1
list_health_incidentsData health incidentsYour CHouse accessdata_health:viewOpen and recent Data Health incidents you can see.1
list_alertingAlertingYour CHouse accessalerting:viewAlerting: channels (with delivery health and what uses each; secrets redacted), fleet rules, sources (everything that sends alerts, as far as you can see), overview (what fires, sent and failed in 24h), or events (history; filter with q, source, severity, channelId, failed, from, to, and page with cursor).1
list_observe_incidentsObservability incidentsYour CHouse accessobserve:viewData observability incidents with their root-cause summaries.1
list_doctor_reportsDoctor reportsYour CHouse accessdoctor:viewRecent fleet Doctor reports: verdict, summary, model and when they ran.1
fleet_snapshotsFleet snapshotYour CHouse accessfleet:viewLatest health snapshot of every ClickHouse node (memory, CPU, queries, replication).1
list_agent_sessionsAgent sessionsYour CHouse accessagents:viewExternal agents (MCP / access tokens) active in the last N days: queries, bytes read, warnings, blocks.1
get_agent_governanceAgent governanceYour CHouse accessagents:viewAgent budget policies or the MCP endpoint settings and enabled tools.1
get_ai_usageAI usageYour CHouse accessai_usage:view, ai:chat, ai:optimizeCHouse's own AI usage in a window: the summary (requests, tokens, estimated cost, split by origin: UI, MCP agents, tokens, background), usage by model, or the data sent to LLM providers by source. scope says whether it covers everyone or only the user's own requests.1
list_ai_requestsAI requestsYour CHouse accessai_usage:view, ai:chat, ai:optimizeRecent AI requests, newest first: user, origin (UI, MCP agent, token, background), token and client, agent, tokens, cost, ClickHouse read, rows sent and status.1
get_ai_requestAI requestYour CHouse accessai_usage:view, ai:chat, ai:optimizeOne AI request step by step: each LLM call with tokens and cost, each tool call with its ClickHouse queries and the data it sent to the model.1
list_ai_agentsAI agentsYour CHouse accessai_agents:viewHow CHouse's AI is set up: which agent each AI feature runs, and each agent's model config, harness, tools, skills, subagents and tuning, whether it is built in or customized and has an update. Prompts and skill files are left out.1
list_ai_guardrailsAI guardrailsYour CHouse accessai_guardrails:viewThe guardrails every CHouse AI run (and, where enabled, every MCP tool result) passes through: kind, settings, stages, action, shadow or enforce mode, scope, order, whether it is on, and its triggers in the last 24 hours.1
list_ai_guardrail_triggersAI guardrail triggersYour CHouse accessai_guardrails:viewRecent 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.1
get_query_regressionsQuery regressionsYour CHouse accessperformance:viewQuery shapes slower or heavier than their own baseline on a connection, with the upgrades, DDL and setting changes around their onset.1
get_capacityCapacityYour CHouse accesscapacity:viewDisk forecasts per node (days until the threshold), fastest-growing and cold tables, codec trials, and cost by consumer with cost:view.1
list_upgrade_assessmentsUpgrade assessmentsYour CHouse accessupgrades:viewUpgrade checks of a connection: target version, mode and counts by severity.1
get_upgrade_statusUpgrade statusYour CHouse accessupgrades:viewA connection's ClickHouse version, whether it is still supported, whether a newer patch exists, and the upgrade targets on offer (recommended LTS first).1
get_upgrade_assessmentUpgrade checkYour CHouse accessupgrades:viewOne 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.1
get_collector_statusCollector statusYour CHouse accessobserve:viewEach observability collector of a connection: state, last run and success, last error, missing grants, paused, and what its last run read.1
get_collector_scheduleCollection scheduleYour CHouse accessconnections:viewHow often each observability collector runs and whether it is paused: the defaults, or one connection's effective schedule with its overrides and bytes read per day.1
list_remediation_actionsRemediation actionsYour CHouse accessremediation:propose, remediation:approve, remediation:approve_highProposed and past fixes on a connection: type, parameters, who proposed it and why, approvals, status and incident.1
get_investigation_notebookInvestigation notebookYour CHouse accessdata_health:view, observe:view, doctor:viewThe notebook of an incident or Doctor report: Chouse AI findings, query snapshots, notes and actions, in order.1
list_dashboardsDashboardsYour CHouse accessdashboards:viewCustom dashboards the user may view: title, owner, panel count, the connections it is assigned to, the roles it is shared with, and whether the user pinned it.1
get_dashboardDashboardYour CHouse accessdashboards:viewOne custom dashboard: the connections it is assigned to, its variables and default range, and each panel's kind and title, with SQL, chart type and unit for charts, Markdown for text panels and the description for headings.1
get_dashboard_annotationsDashboard annotationsYour CHouse accessdashboards:viewWhat changed around a dashboard's charts on the active connection over a recent range: DDL, upgrades, settings changes, new writers, panel alerts, incidents, fixes and notes, newest first. Each kind says if it could not be read and why.1
load_toolkitLoad a toolkit——Load a toolkit's write tools before using them. Toolkits: data (Data & Query), scheduling (Scheduling), health (Data Health), observe (Observe & Ops), dashboards (Dashboards & Context), access (Access), platform (Platform & Audit). Data & Query and the page's toolkit are loaded already. The tools appear on your next step.1
navigateOpen a page——Open a CHouse page in the user's browser, e.g. /data/incidents or /dashboards. Only CHouse pages (/fleet, /overview, /monitoring, /dashboards, /data, /ai, /explorer, /admin, /preferences, /doctor). Use it when the user asks to go somewhere or to see something you found.1
open_entityOpen an item——Open one thing in the user's browser: an incident (source + id), a scheduled job, a dashboard, a dataset (database + table), a Doctor report, or the promise, incident or approval lists.1
fill_formFill a form——Put SQL into the user's SQL editor (form "sql_editor") in a new tab, without running or saving it — for "write that in my editor" or when they should review a query first.1

Action tools

These tools change something, so nothing runs until a person says so. In a chat the run pauses on each low-risk call and the user approves, edits or rejects it; running it needs ai:act. In a run with nobody there, the call is saved for approval in AI Governance › Approvals. High-risk changes only file a proposal in Fixes, where the remediation approval rules decide.

ToolTitleRiskNeeds any ofWhat it doesBuilt-in agents
kill_queryKill a querylowlive_queries:kill, live_queries:kill_allStop a running ClickHouse query by its query_id (from get_running_queries). How it is checked depends on the call (whose query, which connection).2
create_saved_querySave a querylowsaved_queries:createSave a SQL query to the user's saved queries on the active connection. It runs at once and the user can undo it from Activity.1
update_saved_queryEdit a saved querylowsaved_queries:updateChange a saved query's name, SQL or description (from list_saved_queries). Only the fields given change. It runs at once and the user can undo it from Activity.1
delete_saved_queryDelete a saved querylowsaved_queries:deleteDelete one of the user's saved queries. Undo saves it again (with a new id). It runs at once and the user can undo it from Activity.1
share_saved_queryShare a saved querylowsaved_queries:shareMake a saved query visible to everyone who can see saved queries, or private again. The user confirms it before it runs; say what you are about to do and why.1
create_databaseCreate a databaselowdatabase:createCreate a ClickHouse database on the active connection. The user confirms it before it runs; say what you are about to do and why.1
create_tableCreate a tablelowtable:createCreate a ClickHouse table on the active connection from columns, an engine and keys; CHouse validates every type and key expression. The user confirms it before it runs; say what you are about to do and why.1
drop_tableDrop a tablelowtable:dropDrop a ClickHouse table on the active connection. Irreversible: a second person approves it. It needs a second person's approval: calling it files the request and returns at once.1
drop_databaseDrop a databaselowdatabase:dropDrop a ClickHouse database and every table in it, on the active connection. Irreversible: a second person approves it. It needs a second person's approval: calling it files the request and returns at once.1
run_sql_changeChange data or schema with SQLlowquery:execute:dml, query:execute:ddl, table:insert, table:update, table:delete, table:create, table:alter, table:drop, database:create, database:dropRun 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. How it is checked depends on the call (whose query, which connection).1
create_scheduled_querySchedule a querylowscheduled_queries:editCreate a scheduled report query (read-only SELECT, no materialization) on the active connection. It runs at once and the user can undo it from Activity.1
update_scheduled_jobEdit a scheduled querylowscheduled_queries:editChange a scheduled query's name, description, SQL, schedule, row limit or timeout. Only the fields given change; its connection and output never do. It runs at once and the user can undo it from Activity.1
pause_scheduled_jobPause a scheduled querylowscheduled_queries:editStop a scheduled query from running until it is resumed. It runs at once and the user can undo it from Activity.1
resume_scheduled_jobResume a scheduled querylowscheduled_queries:editLet a paused scheduled query run on its schedule again. It runs at once and the user can undo it from Activity.1
run_scheduled_jobRun a scheduled query nowlowscheduled_queries:runRun a scheduled query once, now, outside its schedule (it may write to its destination and notify its channels). The user confirms it before it runs; say what you are about to do and why.1
delete_scheduled_jobDelete a scheduled querylowscheduled_queries:deleteDelete a scheduled query and its run history. The user confirms it before it runs; say what you are about to do and why.1
create_health_promiseCreate a data health promiselowdata_health:editCreate 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. It runs at once and the user can undo it from Activity.1
watch_tableKeep an eye on a tablelowdata_health:editWatch 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). It runs at once and the user can undo it from Activity.1
update_health_promiseEdit a data health promiselowdata_health:editChange a promise's name, description, criticality, schedule, thresholds (grace, breach/recover after) or its whole list of checks. Only the fields given change. It runs at once and the user can undo it from Activity.1
pause_health_promisePause a data health promiselowdata_health:editStop a promise's checks from running until it is resumed. It runs at once and the user can undo it from Activity.1
resume_health_promiseResume a data health promiselowdata_health:editLet a paused promise's checks run on their schedule again. It runs at once and the user can undo it from Activity.1
run_health_checkRun a data health promise nowlowdata_health:runEvaluate a promise's checks once, now. It runs at once and the user can undo it from Activity.1
acknowledge_health_incidentAcknowledge a data health incidentlowdata_health:editMark a data health incident as acknowledged (someone is on it). It runs at once and the user can undo it from Activity.1
snooze_health_incidentSnooze a data health incidentlowdata_health:editSilence a data health incident's notifications for a number of hours. It runs at once and the user can undo it from Activity.1
delete_health_promiseDelete a data health promiselowdata_health:deleteDelete a promise with its checks, samples and incident history. The user confirms it before it runs; say what you are about to do and why.1
propose_remediationPropose a fixlowremediation:proposeFile a remediation proposal for approvers, under the remediation approval rules. params.type is one of: kill_query, pause_scheduled_job, resume_scheduled_job, delay_scheduled_job, set_profile_setting, optimize_partition, restart_replica, add_skip_index, modify_ttl, modify_column_codec, restart_engine_table, reload_dictionary, refresh_view, flush_distributed. It changes nothing by itself; approvers decide in Fixes.2
create_alert_ruleCreate an alert rulelowalerting:editCreate 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. It runs at once and the user can undo it from Activity.1
update_alert_ruleEdit an alert rulelowalerting:editChange an alert rule's name, severity, thresholds (config), channels or whether it is on. Only the fields given change. It runs at once and the user can undo it from Activity.1
mute_alert_ruleMute an alert rulelowalerting:editTurn an alert rule off so it stops notifying; undo (or update_alert_rule with enabled true) turns it back on. It runs at once and the user can undo it from Activity.1
test_alert_channelSend a test alertlowalerting:editSend a test notification to an alert channel (Slack, email…) to check it works. It reaches real people. The user confirms it before it runs; say what you are about to do and why.1
post_alert_messagePost to an alert channellowalerting:editPost 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. The user confirms it before it runs; say what you are about to do and why.1
clear_alert_eventsClear recent alertslowalerting:deleteDelete fired alert events: all of them, or those older than a number of hours. The user confirms it before it runs; say what you are about to do and why.1
acknowledge_observe_incidentAcknowledge an observability incidentlowobserve:editMark an observability incident (from list_observe_incidents) as acknowledged. It runs at once and the user can undo it from Activity.1
dismiss_suggestionDismiss an Observe suggestionlowobserve:editHide an Observe suggestion (by its key) so it is not offered again. It runs at once and the user can undo it from Activity.1
pin_table_criticalitySet a table's criticalitylowobserve:editPin how critical a table is (critical, important, standard), or clear the pin with null so Observe infers it. It runs at once and the user can undo it from Activity.1
add_notebook_cellAdd to an investigation notebooklownotebooks:editAdd 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. It runs at once and the user can undo it from Activity.1
update_cost_ratesSet cost rateslowsettings:updateSet the prices Observe uses to estimate query cost: per TiB read and per CPU hour, in a currency. The user confirms it before it runs; say what you are about to do and why.1
update_collector_scheduleChange the collection schedulelowconnections:editChange 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. The user confirms it before it runs; say what you are about to do and why.1
start_codec_trialTry a column codeclowupgrades:runMeasure how a different compression codec would do on one column, by writing a sample to a scratch table on the active connection. The user confirms it before it runs; say what you are about to do and why.1
run_doctor_scanRun a Doctor scanlowdoctor:runRun the fleet Doctor now over the last hours of metrics (it uses the AI model and takes a while). The user confirms it before it runs; say what you are about to do and why.1
update_doctor_scheduleSchedule the Doctorlowdoctor:runTurn the scheduled Doctor scan on or off and set when it runs. The user confirms it before it runs; say what you are about to do and why.1
update_fleet_alert_configChange fleet alert thresholdslowsettings:updateTurn fleet threshold alerts on or off and set their thresholds. Notification channels and their secrets are left as they are. The user confirms it before it runs; say what you are about to do and why.1
run_upgrade_assessmentAssess an upgradelowupgrades:runCheck 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. The user confirms it before it runs; say what you are about to do and why.1
create_dashboardCreate a dashboardlowdashboards:editCreate a dashboard on the active connection from panels (title, SQL, chart type and columns). It runs at once and the user can undo it from Activity.1
update_dashboardEdit a dashboardlowdashboards:editChange a dashboard's title, description, default time range or auto-refresh. Only the fields given change. It runs at once and the user can undo it from Activity.1
add_panelAdd a dashboard panellowdashboards:editAdd a chart panel (title, read-only SQL, chart type, x and y columns) at the bottom of a dashboard. It runs at once and the user can undo it from Activity.1
update_panelEdit a dashboard panellowdashboards:editChange a chart panel's title, SQL, chart type or columns. Only the fields given change; its place on the canvas stays. It runs at once and the user can undo it from Activity.1
remove_panelRemove a dashboard panellowdashboards:editRemove a panel from a dashboard (its alerts go with it). It runs at once and the user can undo it from Activity.1
restore_dashboard_versionRestore a dashboard versionlowdashboards:editSave an older version of a dashboard (from its version history) as the newest one. It runs at once and the user can undo it from Activity.1
delete_dashboardDelete a dashboardlowdashboards:deleteDelete a dashboard (with its alerts). Undo creates it again from its last document, with a new id. It runs at once and the user can undo it from Activity.1
add_dashboard_noteAdd a dashboard notelowdashboards:editPin a note to a moment on a dashboard's timeline (e.g. a deploy), on the active connection. It runs at once and the user can undo it from Activity.1
delete_dashboard_noteDelete a dashboard notelowdashboards:viewDelete a note from a dashboard's timeline (yours, or any if you can edit the dashboard). It runs at once and the user can undo it from Activity.1
share_dashboardShare a dashboardlowdashboards:shareSet which roles can see a dashboard, and which of them can edit it. Replaces the current shares. The user confirms it before it runs; say what you are about to do and why.1
update_table_contextUpdate table contextlowcontext:editSet a table's curated context (description, grain, owner, tags) that every agent and person reads. Only the fields given change. It runs at once and the user can undo it from Activity.1
upsert_metricDefine a metriclowcontext:editDefine (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). It runs at once and the user can undo it from Activity.1
delete_metricDelete a metriclowcontext:editDelete a table's business metric by name. It runs at once and the user can undo it from Activity.1
create_userCreate a userlowusers:createCreate 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. It needs a second person's approval: calling it files the request and returns at once.1
update_userEdit a userlowusers:updateChange a user's email, username or display name. Use assign_role to change their role, deactivate_user to block them. It needs a second person's approval: calling it files the request and returns at once.1
deactivate_userDeactivate a userlowusers:updateBlock a user from signing in (their sessions end); activate them again with active true. It needs a second person's approval: calling it files the request and returns at once.1
assign_roleAssign a rolelowroles:assignGive a user a role (a user has exactly one; this replaces it). You can only grant roles whose permissions you hold. It needs a second person's approval: calling it files the request and returns at once.1
create_roleCreate a rolelowroles:createCreate 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. It needs a second person's approval: calling it files the request and returns at once.1
update_roleEdit a rolelowroles:updateChange a role's name, description, permissions or data access policies. Lists replace what the role has. It needs a second person's approval: calling it files the request and returns at once.1
delete_roleDelete a rolelowroles:deleteDelete a custom role (system roles and roles still assigned to users cannot be deleted). It needs a second person's approval: calling it files the request and returns at once.1
create_data_access_policyCreate a data access policylowdata_access:createCreate a data access policy: rules allowing or denying database/table patterns, on one connection or all. It needs a second person's approval: calling it files the request and returns at once.1
update_data_access_policyEdit a data access policylowdata_access:updateChange a data access policy's name, description or rules (the rules list replaces the current one). It needs a second person's approval: calling it files the request and returns at once.1
delete_data_access_policyDelete a data access policylowdata_access:deleteDelete a data access policy (system policies cannot be deleted). It needs a second person's approval: calling it files the request and returns at once.1
set_role_policiesSet a role's data access policieslowdata_access:assignReplace the data access policies attached to a role — which connections, databases and tables its users can reach. It needs a second person's approval: calling it files the request and returns at once.1
create_clickhouse_roleCreate a ClickHouse rolelowclickhouse:roles:createCreate a role in ClickHouse itself (on the active connection) with structured grants. It needs a second person's approval: calling it files the request and returns at once.1
update_clickhouse_roleChange a ClickHouse role's grantslowclickhouse:roles:updateReplace the grants of a ClickHouse role on the active connection. It needs a second person's approval: calling it files the request and returns at once.1
draft_ai_agentDraft an AI agentlowai_agents:manageSave 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. It runs at once and the user can undo it from Activity.1
run_ai_evalRun an agent's evalslowai_agents:manageRun an agent's eval cases and score them (it calls the AI model once per case). The user confirms it before it runs; say what you are about to do and why.1
publish_ai_agentPublish an AI agentlowai_agents:manageTurn a drafted (disabled) custom agent on so people can chat with it. If the agent has an eval threshold, its evals must pass first. It needs a second person's approval: calling it files the request and returns at once.1
update_my_preferencesChange my preferenceslow—Change the user's own Explorer preferences (sort order, view mode, favorites only). It runs at once and the user can undo it from Activity.1

Built-in DeepAgents tools

DeepAgents gives every agent these tools on top of its catalog tools. A harness hides the ones its agents should not see — here is what each built-in harness keeps:

Built-in toolWhat it doesFocusedDelegatingAssistantRouter
taskDelegate work to a subagent. Required for agents with subagents.hidden✓✓✓
write_todosPlan multi-step work as a todo list.hiddenhidden✓hidden
lsList files in the agent's virtual filesystem (skills live under /skills/).hiddenhiddenhiddenhidden
read_fileRead a file — how the agent opens a skill's SKILL.md and reference files.✓✓✓hidden
globFind files by pattern.hiddenhiddenhiddenhidden
grepSearch file contents.hiddenhiddenhiddenhidden
write_fileWrite a scratch file in the run's in-memory filesystem (never to disk; skills stay read-only).hiddenhiddenhiddenhidden
edit_fileEdit a scratch file in the run's in-memory filesystem.hiddenhiddenhiddenhidden
deleteDelete a scratch file or folder in the run's in-memory filesystem (skills stay read-only).hiddenhiddenhiddenhidden
executeRun a shell command — only available with a sandbox backend; CHouse never provides one.hiddenhiddenhiddenhidden
start_async_taskStart a remote async subagent (not used by CHouse).hiddenhiddenhiddenhidden
check_async_taskCheck a remote async subagent (not used by CHouse).hiddenhiddenhiddenhidden
update_async_taskUpdate a remote async subagent (not used by CHouse).hiddenhiddenhiddenhidden
cancel_async_taskCancel a remote async subagent (not used by CHouse).hiddenhiddenhiddenhidden
list_async_tasksList remote async subagents (not used by CHouse).hiddenhiddenhiddenhidden

Agents run with an in-memory scratch filesystem that is discarded after the run; skills are mounted read-only under /skills/. Nothing an agent writes reaches disk.

Built-in skills

SkillPathFilesUse it for
data-exploration/skills/ai-chat/data-exploration/SKILL.mdRules and strategies for exploring databases, tables, schemas, and searching metadata.
data-visualization/skills/ai-chat/data-visualization/SKILL.mdComplex rules for calling render_chart, inferring axes, and choosing chart types based on user intent.
error-diagnosis/skills/ai-chat/error-diagnosis/SKILL.mdDiagnose a ClickHouse server error (code/name/exception) and give a concrete, actionable fix.
parts-diagnosis/skills/ai-chat/parts-diagnosis/SKILL.mdDiagnose part/partition health of a MergeTree table — too many parts, slow/stuck merges, bad partition key.
query-optimization/skills/ai-chat/query-optimization/SKILL.mdRules for using explain/analyze/optimize tools to help the user tune their queries.
schema-diagnosis/skills/ai-chat/schema-diagnosis/SKILL.mdDiagnose a column/table schema issue — Nullable overhead, oversized integer, or weak compression — and propose an ALTER.
sql-generation/skills/ai-chat/sql-generation/SKILL.mdStrict rules on outputting ClickHouse syntax, limiting rows, and rendering SQL in markdown.
system-troubleshooting/skills/ai-chat/system-troubleshooting/SKILL.mdDiagnose server-state issues using running queries, slow-query history, and server info.
query-debugger/skills/ai-optimizer/debugger/SKILL.mdDetailed instructions and rules for debugging and fixing failed ClickHouse SQL queries. Focuses on diagnosing syntax errors, type mismatches, and ClickHouse-specific issues using all available schema and query tools.
query-evaluator/skills/ai-optimizer/evaluator/SKILL.mdLightweight rules for determining if a ClickHouse SQL query has obvious inefficiencies or if it is already optimal and should be skipped for optimization.
query-optimizer/skills/ai-optimizer/optimizer/SKILL.mdDetailed instructions and rules for optimizing ClickHouse SQL queries. Focuses on performance tuning, data pruning, and ClickHouse-specific strategies using all available schema and query tools.
clickhouse-playbook/skills/references/clickhouse-playbook/SKILL.md, reference.mdClickHouse optimization and operational playbook with concrete patterns for query rewrites, MergeTree design, joins, PREWHERE, argMax, mutations, merges, and memory pressure.
system-table-reference/skills/references/system-table-reference/SKILL.md, reference.mdExact ClickHouse system table and column reference for safe system.* diagnostics.
types-codecs-compression/skills/references/types-codecs-compression/SKILL.md, reference.mdClickHouse type sizing, Nullable, LowCardinality, codec, compression, and column storage guidance.