Agent capabilities

The agent exposes a small set of powerful primitives (18 tools, plus 3 env-gated control tools). Anything without a dedicated tool is done by writing SQL with the query tool, guided by a skill recipe. You never call tools directly — the agent picks and chains them automatically.

Tools

Category	What it covers	Tools
Schema & exploration	Databases, tables, columns, ad-hoc SQL	query, list_databases, list_tables, get_table_schema, explore_table_schema
Query analysis	Running, slow, failed queries; EXPLAIN	get_running_queries, get_slow_queries, get_failed_queries, explain_query
Health, storage, replication, merges	Metrics, disks, parts, replication, merges	get_metrics, get_disk_usage, get_table_parts, get_replication_status, get_merge_status
Plan & verify	A visible, adaptive step-by-step plan	update_plan
Knowledge & interaction	Load expert guides; ask the user	load_skill, ask_user
Charts & visualization	Run SQL and return an interactive chart	query_and_visualize
Control actions (env-gated)	Kill query/mutation, optimize table	kill_query, kill_mutation, optimize_table

Everything else (expensive-query rankings, query patterns, anomalies, table-design advice, capacity forecasts, settings, logs, replication queue, ZooKeeper, users…) is done with query plus the relevant skill recipe — so the agent keeps full reach with a much smaller, more reliable tool surface.

Control tools (kill_query, kill_mutation, optimize_table) are disabled unless AGENT_ENABLE_CONTROL_TOOLS=true. The agent always confirms before using them.

Tool reference

Tool	Description	Notes
query	Execute a read-only SQL query on ClickHouse.	SELECT / WITH / DESCRIBE / EXPLAIN only. Write statements are rejected.
list_databases	List all databases with engine and comment metadata.
list_tables	List tables in a database with row counts and size.
get_table_schema	Get column definitions for a specific table.
explore_table_schema	Three-mode exploration: no args → databases; database only → tables; database + table → full schema with indexes and keys.
get_running_queries	Currently running queries ordered by elapsed time.	Reads system.processes.
get_slow_queries	Slowest completed queries from the query log.	Reads system.query_log.
get_failed_queries	Recent failed queries with error details.	Reads system.query_log.
explain_query	EXPLAIN PLAN / PIPELINE / PLAN with indexes for a query.
get_metrics	Server health: version, uptime, active connections, memory.	Reads system.metrics.
get_disk_usage	Per-disk free and total space.	Reads system.disks.
get_table_parts	Part-level info for a table: rows, size, compression ratio.	Reads system.parts.
get_replication_status	Per-table replication delay, queue size, and replica counts.	Reads system.replicas.
get_merge_status	Currently running merges with progress and elapsed time.	Reads system.merges.
update_plan	Create or update a step-by-step workflow plan for the current investigation.	Rendered as a live checklist in the UI.
load_skill	Load an expert guide (skill) with SQL recipes for a specific domain.
ask_user	Ask the user a question to gather information before proceeding.
query_and_visualize	Run a SQL query and return an interactive chart config.	Chart type is auto-detected from result columns.
kill_query	Kill a running query by query_id.	DESTRUCTIVE. Env-gated: requires AGENT_ENABLE_CONTROL_TOOLS=true. Agent always confirms first.
kill_mutation	Cancel a running mutation on a table.	DESTRUCTIVE. Env-gated: requires AGENT_ENABLE_CONTROL_TOOLS=true. Agent always confirms first.
optimize_table	Trigger an OPTIMIZE on a table to force merges.	DESTRUCTIVE. Env-gated: requires AGENT_ENABLE_CONTROL_TOOLS=true. Agent always confirms first.

Skills

Skills are expert guides — with copy-pasteable SQL recipes against system.* — that the agent loads on demand. Because the toolset is lean, skills are how the agent stays powerful. Eighteen skills are included:

Skill	Covers
system-tables-reference	Exact columns of key system tables; recipes; tools vs raw SQL
data-analysis	Aggregation & time-series recipes (largest scan, expensive queries, patterns, period comparison)
anomaly-detection	Recent-vs-baseline comparisons (error spikes, p95 regressions, part explosions)
query-tuning-advisor	Diagnose a slow query and propose concrete rewrites & better joins
query-optimization	PREWHERE, JOIN patterns, materialized views, EXPLAIN, indexes
schema-design-advisor	ORDER BY/partition keys, codecs, skip indexes, column type right-sizing
storage-optimization	Compression codecs, TTL, tiered storage, part management
version-upgrade-advisor	Whether/how to upgrade ClickHouse and what is gained
hardware-tuning	Size settings to the box’s cores/RAM/disk
concept-explainer	Teach core ClickHouse concepts
replication-guide	ReplicatedMergeTree, failover, lag diagnosis, Keeper
cluster-operations	Distributed tables, resharding, node management, topology
migration-patterns	ALTER patterns, zero-downtime schema changes
security-hardening	RBAC, row policies, quotas, audit logging
clickhouse-best-practices	Schema design, query tuning, operational guidelines
troubleshooting	OOM, slow merges, stuck mutations, error-code diagnosis
incident-response	Structured triage recipes (disk full, errors, replication lag, health sweep)
plan-and-verify	Decompose with update_plan and verify each result before concluding

List available skills: GET /api/v1/agent/skills.

Plan and verify

For multi-step tasks the agent authors a live checklist with update_plan, keeps exactly one step in progress, and adapts the plan as results come in. Crucially, it verifies each result before stating it — re-querying or cross-checking a second system table for a finding, running explain_query on both versions before claiming a rewrite is faster, and separating what is verified from what is a hypothesis. The plan-and-verify and incident-response skills encode the recipes. Simple one-step questions skip the plan entirely.

Example questions

Ask in plain English:

• “Which queries are running right now and how long have they been executing?” — lists query id, user, elapsed time, and memory, sorted by duration.

• “What were the 10 slowest queries in the last 24 hours?” — fetches from the query log and offers to EXPLAIN any of them.

• “What’s the largest data scan ever performed on this cluster?” — loads data-analysis and runs the system.query_log recipe.

• “Anything abnormal in the last hour versus baseline?” — loads anomaly-detection and compares recent activity to the preceding window.

• “Show me query volume per hour over the last day as a chart.” — runs the aggregation and renders a line chart inline.

• “Suggest a better ORDER BY and which columns should be LowCardinality for analytics.events.” — loads schema-design-advisor, inspects the schema and parts, and recommends changes.