ClickStack

Permanently delete a webhook by ID. Blocked while any alert still references it — reassign or delete those alerts first. Use clickstack_get_webhook to list available webhook IDs.

clickstack_delete_webhook

Inspect ClickHouse tables that are NOT registered as sources. For a source, call clickstack_describe_source instead. Use this instead of querying system.tables / system.columns with clickstack_sql. With table set, returns: - table: engine, sorting key, primary key, partition key, approximate total rows and bytes - columns[]: name, type, default kind/expression, comment, and whether it is in the sorting/primary key - dataSkippingIndices[]: name, type, expression - sampleRows: up to 5 rows when sampleRows is set (off by default) Without table, lists the tables in the database (name, engine, approximate rows), paginated. Pass the returned `nextCursor` back unchanged to fetch the next page.

clickstack_describe_table

DRILL-DOWN: Use after clickstack_list_metrics (or after a clickstack_describe_source sample) to get attribute keys, sampled values, unit, and description for a specific (metricName, kind) pair. Attribute keys vary per metric — not per source — so always call this before clickstack_timeseries / clickstack_table for any metric you've never queried. REQUIRES `kind` — pass the gauge/sum/histogram/exponential histogram/summary value emitted alongside the metric name by clickstack_list_metrics or clickstack_describe_source. A metric name can legitimately live in more than one kind (e.g. "container.cpu.usage" appears in both gauge and sum); call this tool once per kind you care about. kind:"summary" is accepted for discovery (attribute keys, sampled values, unit, description), but summary metrics cannot be queried with clickstack_timeseries / clickstack_table — use clickstack_sql against the table in the source's metricTables.summary. attributeValuesMeta on each kind reports sampledKeys (queried for values) and truncatedKeys (skipped by the per-call sampling cap) — a key in truncatedKeys was never queried, so query it directly if you need its values. Workflow: clickstack_list_sources → clickstack_list_metrics → clickstack_describe_metric → clickstack_timeseries|clickstack_table.

clickstack_describe_metric

CALL THIS BEFORE WRITING QUERIES — prevents unknown-column errors. Returns the full column schema, map-attribute keys, and sampled low-cardinality values (e.g. SeverityText, StatusCode, ServiceName) for a single data source. Workflow: call clickstack_list_sources first to get source IDs, then call this tool for each source you plan to query. Returns: - columns[]: column name, ClickHouse type, and JS type - mapAttributeKeys: discovered keys in Map columns (e.g. SpanAttributes, ResourceAttributes) - lowCardinalityValues: sampled values for LowCardinality(String) columns (SeverityText, StatusCode, ServiceName, etc.) — use these in filters instead of guessing - mapAttributeValues: sampled top values for the most common map attribute keys (e.g. ResourceAttributes['service.name'] top values) — requires rollup tables - requiredSourceFilters: when present, every query against this source MUST pass `sourceFilters` for each listed column. Sample values for each are returned as `sourceFilterValues` (capped); use clickstack_get_source_filter_values for the full paginated list. Value sampling stops after 30 seconds. If it is cut short, the result still includes the columns and sets partial: true with skippedStages listing what is missing. Cost: one describe call prevents 3–5 exploratory queries against non-existent columns.

clickstack_describe_source

Detect what is NEW or GONE between an earlier baseline window and a current window — log/event patterns that emerged, ramped up, or stopped. This answers "what changed / what is novel?" — NOT "what attribute value differs?". USE THIS for status checks, health reports, post-deploy diffs, and any "call out anything new or worth a closer look" question. It mines event patterns (Drain) in BOTH windows and set-differences them: - emerging: patterns whose share of the window is >= minShareRatio× higher now than in baseline (includes brand-new templates absent from baseline) - disappeared: patterns that were common in baseline but >= minShareRatio× rarer (or absent) now WHY NOT clickstack_event_deltas: event_deltas compares ATTRIBUTE VALUE DISTRIBUTIONS between two row groups (e.g. "region shifted toward eu-west"). It CANNOT surface a brand-new log template or a new endpoint that simply did not exist before — a novel signal has no baseline distribution to shift. Use emerging_signals for novelty/emergence (set membership over time); use event_deltas for "what is different about these rows" (distribution shift within a shared population). Requires sourceId — call clickstack_list_sources / clickstack_describe_source first. Provide two non-overlapping windows: the current window to characterize and an earlier baseline. Typically baselineEndTime == currentStartTime. CALIBRATION: routine variance is not novelty. A pattern that merely wobbled in volume is NOT emerging; only report shifts past minShareRatio. An empty emerging list is a valid, informative answer ("nothing novel") — do not manufacture findings.

clickstack_emerging_signals

Discover what kinds of messages, errors, or events exist. Samples random events, clusters them into templates (Drain), and returns patterns ranked by frequency with sampled and estimated counts, optional trends, and raw samples. Use for "what errors are happening", common or noisy logs, recurring messages. Examples: - "What kinds of errors is checkout producing?" → where:"ServiceName:checkout AND SeverityText:error", topN:5, sampleSize:1000 (trends on by default) - "What messages dominate this service?" → where:"ServiceName:api", trendBuckets:0 - Patterns in a map attribute → bodyExpression:"LogAttributes['exception.type']", where:"LogAttributes['exception.type'] != ''", whereLanguage:"sql" - A field inside JSON bodies → bodyExpression:"JSONExtractString(Body, 'message')", where:"JSONExtractString(Body, 'message') != ''", whereLanguage:"sql" Use instead: exact counts or breakdowns by a known field → clickstack_table / clickstack_timeseries; raw rows → clickstack_search; patterns new or gone vs an earlier window → clickstack_emerging_signals. Counts come from a sample: estimatedCount is an extrapolation, and a pattern with 0 sampled events may still exist. Drill down: call clickstack_search with the same sourceId and time range, where = a pattern's whereSnippet, whereLanguage = "sql". whereSnippet already includes your where filter unless summary.drilldown.includesFilters is false. Requires sourceId — call clickstack_list_sources then clickstack_describe_source first. PREFER THIS over clickstack_sql. Only drop to raw SQL for things the builder tools cannot express — JOINs, sub-queries, CTEs, window functions, tables not registered as sources, or summary-type metrics (the metricTables.summary table on a metric source, which the builder tools cannot query).

clickstack_event_patterns

Without an ID: list all alerts as a high-level summary (id, name, displayName, tags, state, source, interval). Optionally filter by state (e.g. state="ALERT" for firing alerts). With an ID: get full alert detail including configuration, displayName, tags, and recent evaluation history.

clickstack_get_alert

Without an ID: list all dashboards (returns IDs, names, tags). With an ID: get full dashboard detail including all tiles and configuration.

clickstack_get_dashboard

Without an ID: list all saved searches as a high-level summary (id, name, tags). With an ID: get full saved search detail including query, source, filters, and configuration.

clickstack_get_saved_search

Retrieve a single tile from a dashboard by tileId. Useful for inspecting one tile without loading the full dashboard. Returns the tile as JSON in the same shape clickstack_get_dashboard uses for tiles: id, name, x, y, w, h, containerId/tabId when set, and config. An unknown tileId returns an error listing the available tile IDs and names. Use clickstack_get_dashboard (without an ID) to list dashboards, then clickstack_get_dashboard (with an ID) to see all tile IDs.

clickstack_get_dashboard_tile

DISCOVERY: Use this after clickstack_describe_source when you need more metric names than the per-kind sample shows, or when you want to narrow by kind / name pattern / time window. Returns paginated metric names per kind (gauge/sum/histogram/exponential histogram/summary) with optional unit and description (when the OTel-default columns are present). Pass the returned `nextCursor` back unchanged to fetch the next page. Summary metrics are listed for discovery only — they cannot be passed to clickstack_timeseries / clickstack_table; query them with clickstack_sql against the table in the source's metricTables.summary. Workflow: clickstack_list_sources → clickstack_describe_source → clickstack_list_metrics → clickstack_describe_metric → clickstack_timeseries|clickstack_table.

clickstack_list_metrics

List the available values for the required source filter columns on a single source. Use this BEFORE calling any query tool against a source whose configuration declares `requiredSourceFilters`. ONLY use this for sources that have `requiredSourceFilters`. Every such source requires values for every declared column on every query call, and this tool tells you which values exist. Workflow: 1. clickstack_list_sources or clickstack_describe_source to see whether a source declares requiredSourceFilters and which columns it requires. 2. clickstack_get_source_filter_values to fetch the values for those columns. 3. Call your query tool with the sourceFilters parameter set, e.g. sourceFilters: { "<columnA>": ["val1"], "<columnB>": ["val2"] } CROSS-FILTER PRUNING: pass `selectedFilters` with the values you have already chosen for some columns to narrow the option list for the others. PAGINATION: each column reports `totalAvailable`, `truncated`, and (when truncated) `nextOffset`. Use `limit` + `offset` to step through high-cardinality columns instead of pulling everything at once.

clickstack_get_source_filter_values

List all data sources (logs, metrics, traces) and database connections available to this team. Returns source IDs, names, kinds, and connection IDs as a lightweight catalog. Metric sources additionally include metricNamesPreview — a sample of recently-reported metric names per kind — so metrics can be queried immediately. NEXT STEP: After identifying the source(s) you need, call clickstack_describe_source with the sourceId to get the full column schema, attribute keys, and sampled values. This two-step approach avoids fetching expensive schema details for sources you do not need. REQUIRED SOURCE FILTERS: when a source has `requiredSourceFilters`, every query against it MUST supply values for every column in `requiredSourceFilters` via the `sourceFilters` parameter. Call clickstack_get_source_filter_values to discover the available values, or check the sampled `sourceFilterValues` returned by clickstack_describe_source. NOTE: For most queries, use source IDs with clickstack_timeseries, clickstack_table, clickstack_search, or clickstack_event_patterns. Connection IDs are only needed for clickstack_sql (raw ClickHouse SQL). Metric sources may list a "summary" table in metricTables. Summary metrics are not supported by the builder tools — use clickstack_sql to look at them.

clickstack_list_sources

List all teams the current user belongs to and identify which team is active for this session. Use this to discover available teams when the user works across multiple teams. To switch teams, the MCP client must include the `x-hdx-team` HTTP header set to the target team ID on subsequent requests. The header is validated against the user’s team memberships — requests for teams the user does not belong to will be rejected.

clickstack_list_teams

List available webhook destinations (id, name, service type). Use the returned id as the webhookId when creating alerts with clickstack_save_alert.

clickstack_get_webhook

Make targeted updates to a dashboard without resubmitting the full object. You can update dashboard-level fields (name, tags, savedFilterValues) and/or replace a single tile by tileId — all in one call. Unmentioned tiles and fields are preserved. Replacing a tile overwrites its whole config; the old config's fields are not merged in. If the new config cannot carry alerts (anything other than a line, stacked_line, stacked_bar, or number tile), alerts attached to that tile are permanently deleted. Use clickstack_get_dashboard_tile to inspect a tile before patching it. IMPORTANT: After patching a tile, run clickstack_query_tile to confirm the query still works.

clickstack_patch_dashboard

Run the queries for many tiles of a dashboard in ONE call and return a compact per-tile success/failure summary. This is the efficient way to validate an entire dashboard after clickstack_save_dashboard — prefer it over calling clickstack_query_tile once per tile. Accepts a dashboard ID and an optional list of tile IDs. Markdown tiles are excluded by default; a markdown tile passed explicitly in tileIds is returned with status "skipped". A tile that fails is reported inline with its error and the overall call still succeeds, so one broken tile does not hide the rest, and unrecognized tile IDs come back as unknownTileIds rather than failing. At most 50 tiles run per call; any beyond that are returned as unrunTileIds — call again with those as tileIds to run the remainder. Drill into a specific failing tile with clickstack_query_tile. SOURCE FILTERS: when tiles read a source that declares `requiredSourceFilters`, pass `sourceFilters` here to stand in for the dashboard-level SOURCE_FILTER dropdown selections. Without them each such tile is reported as status "error" with a "requires source filter values" message.

clickstack_query_tiles

Execute the query for a specific tile on an existing dashboard. Useful for validating that a tile returns data or for spot-checking results without rebuilding the query from scratch. Returns JSON with `result` (the query output rows), plus `note` when the result was trimmed for size, `hints` when no data matched, and `warnings` for missing raw SQL macros or dashboard-variable reference problems. Event-pattern tiles return pattern-mining output like clickstack_event_patterns; markdown tiles return a plain "no query" message. Query failures come back as tool errors. Use clickstack_get_dashboard with an ID to find tile IDs. SOURCE FILTERS: when the tile reads a source that declares `requiredSourceFilters`, pass `sourceFilters` here to stand in for the dropdown selection so the validation query has values to run with.

clickstack_query_tile

Execute raw ClickHouse SQL. LAST-RESORT TOOL — do NOT reach for this first. Default to the builder tools for querying; they are more reliable and produce richer, structured results: • clickstack_service_health — per-service throughput, errors, latency vs yesterday, ranked • clickstack_table — aggregations, top-N, single-value KPIs, breakdowns • clickstack_timeseries — trends / metrics over time • clickstack_search — browsing individual log/trace rows • clickstack_event_patterns — recurring log/event pattern discovery • clickstack_event_deltas — attributes that differ between two row groups • clickstack_emerging_signals — patterns new or gone vs a baseline window • clickstack_trace_waterfall — one trace as a parent/child span tree • clickstack_trace_top_time_consuming_operations — slowest child operations in a trace ONLY use raw SQL when the query genuinely cannot be expressed by a builder tool — i.e. it requires JOINs, sub-queries, CTEs, window functions, tables not registered as sources, or summary-type metrics (the metricTables.summary table on a metric source, which the builder tools cannot query). A single-table aggregation, top-N, time-series, or row browse is ALWAYS a builder-tool job, never raw SQL. Requires connectionId — call clickstack_list_sources to find connections. Pass sourceId too when querying a source, so $__sourceTable and $__filters resolve. Before writing SQL, get column names from clickstack_describe_source, or clickstack_describe_table for tables that are not sources (instead of querying system.columns / system.tables). SOURCE FILTERS: if the source declares `requiredSourceFilters`, you MUST pass `sourceFilters` AND include `$__filters` in your WHERE clause. Results are table rows; for time series, select a time column and ORDER BY it. To run several independent queries at once, pass queries instead of sql. They run in parallel under a shared 60s budget, and each result reports its own status (ok, error, or timeout).

clickstack_sql

Search dashboards by name and/or tags. Returns matching dashboards with their IDs, names, and tags. More targeted than clickstack_get_dashboard (which lists all dashboards). At least one of query or tags must be provided.

clickstack_search_dashboards

Browse individual log/event/trace rows. Use this when you need to see raw events, investigate specific log lines, or drill into individual records matching a filter. PREFER THIS over clickstack_sql. Only drop to raw SQL for things the builder tools cannot express — JOINs, sub-queries, CTEs, window functions, tables not registered as sources, or summary-type metrics (the metricTables.summary table on a metric source, which the builder tools cannot query). Requires sourceId — call clickstack_list_sources then clickstack_describe_source first. For aggregated metrics, use clickstack_table instead. For pattern discovery, use clickstack_event_patterns instead. Set denoise=true to automatically filter out high-frequency repetitive patterns, surfacing only unusual or interesting events. Column naming: top-level columns are PascalCase (Duration, StatusCode). Map attributes use bracket syntax: SpanAttributes['http.method']. SOURCE FILTERS: when the source declares `requiredSourceFilters` (see clickstack_describe_source / clickstack_list_sources), you MUST pass `sourceFilters` with at least one value for every required column.

clickstack_search

One-call health report for every service on a trace source: throughput, error rate, p50/p95/p99 latency and top error groups, compared with the same window yesterday and ranked by how far each moved the wrong way. Each service gets flags for changes that crossed a fixed threshold and a one-line factual summary. New or growing error groups come first, with first/last-seen times; operations with no prior traffic are listed as likely rollouts. USE THIS FIRST for status checks, "is X healthy", post-deploy checks, and as the entry point for triage. It is per service and per window. To follow up: - clickstack_timeseries by minute to see when a change happened - clickstack_table grouped by span name for per-endpoint shifts - clickstack_emerging_signals on the log source for new log patterns For a flagged service, check its own runtime metrics (memory, GC, CPU, restarts by pod) on the metric source before blaming dependencies, then use clickstack_event_deltas and clickstack_trace_top_time_consuming_operations. CALIBRATION: flags fire only past fixed thresholds (see `usage` in the response); smaller swings are usually normal variance, and no flags is a valid result for a routine check. Thresholds apply to service-wide totals, so an unflagged service can still hide a regression in one endpoint, pod or segment. Weigh the numbers against the question. PREFER THIS over clickstack_sql. Only drop to raw SQL for things the builder tools cannot express — JOINs, sub-queries, CTEs, window functions, tables not registered as sources, or summary-type metrics (the metricTables.summary table on a metric source, which the builder tools cannot query). SOURCE FILTERS: when the source declares `requiredSourceFilters` (see clickstack_describe_source / clickstack_list_sources), you MUST pass `sourceFilters` with at least one value for every required column.

clickstack_service_health

Plot metrics over time as a line or stacked bar chart. Use this when you need to visualize trends, compare time-series, or monitor metric changes over a time window. PREFER THIS over clickstack_sql. Only drop to raw SQL for things the builder tools cannot express — JOINs, sub-queries, CTEs, window functions, tables not registered as sources, or summary-type metrics (the metricTables.summary table on a metric source, which the builder tools cannot query). Requires sourceId — call clickstack_list_sources then clickstack_describe_source first. Each select item defines one plotted series. Column naming: top-level columns are PascalCase (Duration, StatusCode). Map attributes use bracket syntax: SpanAttributes['http.method']. ── METRIC SOURCES ── When sourceId is a metric source, each select item MUST set metricType ("gauge"|"sum"|"histogram"|"exponential histogram") and metricName (the OTel metric name). valueExpression defaults to "Value" — set it explicitly only to transform the value. Discovery: clickstack_describe_source returns a per-kind metric-name sample; clickstack_list_metrics paginates the full catalog; clickstack_describe_metric returns attribute keys + sampled values for a single metric. Per kind: gauge uses last_value/avg/min/max (or aggFn:any + isDelta:true for Prometheus-style delta); sum uses aggFn:"increase" for the counter increase, or sum/avg on the computed rate; histogram and exponential histogram use aggFn:"quantile" + level for percentiles, or aggFn:"count" for total bucket count. TOP-N CAP: aggFn:"increase" + groupBy is capped at 20 groups by the renderer (top by max bucket sum). Narrow with where/groupBy to see other groups. summary metrics are not supported by the query renderer — query them with clickstack_sql against the table in the source's metricTables.summary. SOURCE FILTERS: when the source declares `requiredSourceFilters` (see clickstack_describe_source / clickstack_list_sources), you MUST pass `sourceFilters` with at least one value for every required column.

clickstack_timeseries

Given a parent-span filter and a time window, rank the child operations (ServiceName, SpanName) by cumulative time across all traces whose parent span matches. Same algorithm as the in-app "Top Most Time Consuming Operations" chart. USE WHEN: asking "where is the time going" for a slow operation. Filter to one (ServiceName, SpanName) pair and set minParentDurationMs to the slow threshold. MULTIPLE SLOW OPERATIONS: call this tool ONCE PER (service, operation) and compare the top children. A shared top child suggests a shared cause; different top children are independent regressions. DO NOT merge operations into one parentFilter — the ranking then conflates them. RANKING: totalTimeMs = sum(Duration) of matching child spans, so a fast but frequent child can dominate even with an unremarkable p99. Children are not scoped to the parent's service, so slow cross-service calls (database, cache, upstream HTTP) show up. RETURNS: operations[] with service, operation, totalTimeMs, calls, inParents (parent traces containing that operation), p50Ms, p99Ms, and shareOfTotalTime, plus a summary with operationsReturned, topN, and grandTotalTimeMs. NEXT STEP: once a dominant slow child is found, run clickstack_event_deltas on that child: target = {where: SpanName='<child>' AND Duration > X}, baseline = {where: SpanName='<child>' AND Duration <= X}. PAIR TOOL: clickstack_trace_waterfall shows ONE concrete trace as a parent/child tree, for an example after this breakdown.

clickstack_trace_top_time_consuming_operations

Fetch every span in ONE trace as a parent/child waterfall, pre-ordered for reading. Use it for "show me an example trace" or "what happened in trace X" instead of writing TraceId self-JOINs in raw SQL; it uses the source's configured trace, span, and parent-span ID expressions. NOT FOR AGGREGATE QUESTIONS. "Where does the time go across many slow traces of operation X" is clickstack_trace_top_time_consuming_operations, called once per (service, operation) with minParentDurationMs. Use this tool for a single concrete example, typically after that breakdown has pointed at a suspicious operation. Two modes: 1. Specific trace: pass traceId. 2. Auto-pick: omit traceId and pass pickFilter + pickBy; the tool picks one matching trace and returns its full tree. Returns traceId, spanCount, totalDurationMs, rootSpan, and spans in pre-order DFS, children after their parent in execution order. Each span has depth (root=0), spanId, parentSpanId, serviceName, spanName, spanKind, durationMs, statusCode, statusMessage, timestamp, and spanAttributes. If the trace source has a linked logSourceId, the response also has `logs[]`: log rows sharing the TraceId, sorted by timestamp, each with its spanId. Disable with includeLogs:false. If the log source declares `requiredSourceFilters`, include its columns in `sourceFilters` too (one map shared with the trace source, matched by column name).

clickstack_trace_waterfall