1Open Slashspace and go to Settings, then Connectors.
2On Discover, search for ClickHouse MCP and click Connect.
3Sign in to ClickHouse MCP in your browser. Slashspace updates when the account is connected.
Then ask for what you need in any Agent mode chat. ClickHouse MCP is on in every chat unless you switch it off.
What your chats can do
32 tools from ClickHouse MCP.
Clickstack delete dashboardPermanently delete a dashboard by ID. Also removes any alerts attached to its tiles. Use clickstack_get_dashboard (without an ID) to list available dashboard IDs.
Clickstack delete sourcePermanently delete a data source by ID. Other sources may reference it (e.g. a trace source linked to a log source) — those links are left dangling, so check dependencies first. Use clickstack_list_sources to find available source IDs.
Clickstack delete webhookPermanently 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 describe metricDRILL-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 sourceCALL 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.
Cost: one describe call prevents 3–5 exploratory queries against non-existent columns.
Clickstack emerging signalsDetect 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 event deltasRank the properties of two row groups (logs or trace spans) by how much their value distributions differ. Same algorithm as the in-app Event Deltas view (DBDeltaChart). High-cardinality fields (IDs, request IDs, timestamps) are filtered out by default so the ranking surfaces the categorical attributes that actually separate the two groups. Score is computed after normalizing each group to 100% so it's robust to different group sizes.
USE THIS INSTEAD OF MANUAL PIVOTS. When two row sets visibly differ and you don't know which attribute(s) separate them, the standard agentic move is to run a GROUP BY for each candidate attribute and compare. event_deltas does this for ALL attributes in one call, ranked by signal strength — usually 1 call instead of 5–20.
NARROW the target to the specific outlier rows. A broad target mostly contains healthy rows, so the ranking comes back noisy. The narrower target — the sharper the ranking.
TYPICAL USES (any source — logs or traces):
- Slow vs fast spans (MOST COMMON for latency triage):
target = {where: <op-filter> AND Duration > <threshold>},
baseline = {where: <op-filter> AND Duration <= <threshold>}
Scope BOTH to the same operation/endpoint via `<op-filter>`; the ranked attribute(s) are then what discriminates the slow invocations of THAT operation from the fast ones. Skipping the op-filter gives a noisy "which operation is slow" answer instead of "which sub-set of one operation is slow".
- Before vs after a deploy / incident onset:
target = {window: after onset}, baseline = {window: before onset}
- Failing vs succeeding rows:
target = {where: <failing filter>}, baseline = {where: <succeeding filter>}
- One service / endpoint vs the rest:
target = {where: ServiceName=X}, baseline = {where: ServiceName != X}
Any pair of row sets over the same source works — the tool just asks "what is statistically different about target vs baseline".
WHEN NOT TO USE: when the question is already known to be about a specific attribute (use clickstack_table groupBy), when you want raw rows (use clickstack_search), or when you need a time-series shape (use clickstack_timeseries).
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).
OUTPUT SHAPE: an array of properties, each with rank, key, score, semanticBoost (true for well-known OTel attrs like service.name / http.method / error.type / status), targetCount and baselineCount (sample sizes), and topDeltas — the values whose share shifted most, each with `value`, `targetPct`, `baselinePct`, and `diffPct`. topDeltas already contains the full per-value comparison for that attribute, so there is no separate target/baseline distribution to consult.
IMPORTANT — DO NOT STOP AT RANK 1. The top ~5 ranked properties are often INDEPENDENT axes that together explain the population shift (e.g. a regression localized on the intersection of two attributes). Scan down the list until the score visibly drops to noise level; any property well above that floor is a candidate axis to combine with the others.
Clickstack event patternsDiscover the most common log messages and event patterns. Samples random events, clusters them using the Drain algorithm, and returns patterns sorted by frequency with estimated counts and time trends.
PREFER THIS TOOL over clickstack_search or clickstack_table when the goal is to understand what kinds of messages, errors, or events exist — e.g. "sample logs", "what errors are happening", "show me common messages", "what does this service log". It returns frequency-ranked patterns instead of raw rows, giving a much better overview.
Also use when asked about "top patterns", "common logs", "noisy services", "recurring messages", or log noise analysis.
Each pattern includes a "whereSnippet" — use it as the "where" parameter in a follow-up clickstack_search call to browse matching raw events.
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).
When to use which tool:
- clickstack_event_patterns: clustering / recurring shapes / noise analysis
- clickstack_search: raw individual rows
- clickstack_table: aggregated metrics / counts / top-N
Clickstack get alertWithout 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 dashboardWithout an ID: list all dashboards (returns IDs, names, tags). With an ID: get full dashboard detail including all tiles and configuration.
Clickstack get dashboard tileRetrieve a single tile from a dashboard by tileId. Useful for inspecting one tile without loading the full dashboard. Use clickstack_get_dashboard (without an ID) to list dashboards, then clickstack_get_dashboard (with an ID) to see all tile IDs.
Clickstack get saved searchWithout 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 source filter valuesList 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 webhookList available webhook destinations (id, name, service type). Use the returned id as the webhookId when creating alerts with clickstack_save_alert.
Clickstack list metricsDISCOVERY: 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 sourcesList 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 teamsList 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 patch dashboardMake targeted updates to a dashboard without resubmitting the full object. You can update dashboard-level fields (name, tags) and/or replace a single tile by tileId — all in one call. Unmentioned tiles and fields are preserved. 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 query tileExecute 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. Use clickstack_get_dashboard with an ID to find tile IDs.
SOURCE FILTERS: when the tile reads a source that declares `requiredSourceFilters` (core filters) but carries no tile-level `sourceFilters` of its own (which is the recommended default), pass `sourceFilters` here to stand in for the dropdown selection so the validation query has values to run with. The values you pass are used only for this query and are NOT persisted on the tile. If the tile already pins its own tile-level `sourceFilters`, do NOT pass `sourceFilters` here: omit it so the validation runs with the tile's own values. Anything you pass here takes precedence over the tile-level values (the two are never merged), so passing a different set would validate something other than what the tile will actually use.
Clickstack query tilesRun 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.
Clickstack save alertCreate a new alert (omit id) or update an existing one (provide id). Alerts monitor a saved search, a dashboard tile, or an inline chart config (source "inline" + chartConfig — no saved search or dashboard needed) and fire when the metric crosses a threshold. At least one webhook notification channel is required: pass "channels" for 1-10 targets, or the legacy singular "channel" for one. Updates replace the alert configuration rather than merging it, so read the alert first and resend its full "channels" array to avoid dropping channels you did not mean to remove.
Clickstack save dashboardCreate a new dashboard (omit id) or update an existing one (provide id). Call clickstack_list_sources first to obtain sourceId and connectionId values. IMPORTANT: After saving a dashboard, always run clickstack_query_tiles to validate every tile in one call (or clickstack_query_tile for a single tile) and confirm the queries work and return expected data. Tiles can silently fail due to incorrect filter syntax, missing attributes, or wrong column names. TIP: To update a single tile without resubmitting all tiles, use clickstack_patch_dashboard instead.
Clickstack save saved searchCreate a new saved search (omit id) or update an existing one (provide id). A saved search stores a reusable query against a data source. Use clickstack_list_sources to find the sourceId.
Clickstack save sourceCreate a new data source (omit id) or update an existing one (provide id) so shipped telemetry becomes queryable. Update is a full replace of the source definition. Required for all kinds: kind, name, connection, databaseName, tableName, timestampValueExpression. Kind-specific requirements: log & trace need defaultTableSelectExpression; trace also needs durationExpression, traceIdExpression, spanIdExpression, parentSpanIdExpression, spanNameExpression, spanKindExpression; session needs traceSourceId; metric needs metricTables and resourceAttributesExpression. Get connection and source IDs from clickstack_list_sources.
Clickstack save webhookCreate a new webhook (omit id) or update an existing one (provide id). Use the returned id as the webhookId when creating alerts with clickstack_save_alert. Required: name, service (slack, generic, or incidentio), and url. For the slack service the url host must end in slack.com and headers/queryParams/body are not supported. On update, readable fields (description, body) are a full replace while write-only headers/queryParams are preserved when omitted (send {} to clear); changing the destination clears omitted write-only secrets.
Clickstack searchBrowse 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 dashboardsSearch 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 sqlExecute 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_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. If you are unsure, try the builder tool first and only fall back to SQL if it cannot express what you need.
Requires connectionId — call clickstack_list_sources to find connections. Call clickstack_describe_source to discover column names before writing SQL.
SOURCE FILTERS: when querying a table backed by a registered source, pass `sourceId` so the `$__sourceTable` and `$__filters` macros resolve. If that source declares `requiredSourceFilters`, you MUST also pass `sourceFilters` AND include `$__filters` in your WHERE clause. Source filter values are rendered as `<column> IN (<value>, <value2>, ...)` conditions.
Results are always returned as table rows — for time-series semantics, include a time column and ORDER BY it in your SQL.
Clickstack tableCompute aggregated metrics as a table, single number, pie chart, or bar chart. Use this for grouped aggregations, top-N queries, single-value KPIs, or proportional breakdowns.
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.
Use the top-level "where" to scope the entire query (e.g. filter by service). Each select item can also have its own "where" for per-metric cohort comparisons (compiles to <aggFn>If(...)). Both can be used together.
Column naming: top-level columns are PascalCase (Duration, StatusCode). Map attributes use bracket syntax: SpanAttributes['http.method']. Map attributes work in groupBy and valueExpression, including toFloat64OrZero(SpanAttributes['key']).
Shape auto-upgrade: if shape is "number", "pie", or "bar" but select has >1 item, it is transparently upgraded to "table".
── 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; sum uses aggFn:"increase" for counter increase (top-N capped at 20 groups when combined with groupBy), or sum/avg on the rate; histogram and exponential histogram use aggFn:"quantile" + level for percentiles, or aggFn:"count" for total bucket count.
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 timeseriesPlot 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 trace top time consuming operationsGiven a parent-span filter and a time window, return the child operations contributing the most cumulative time across all traces matching the parent filter. Same algorithm as the in-app "Top Most Time Consuming Operations" chart on the service dashboard.
WHAT IT DOES (two-stage, runs as one SQL):
1. Pick distinct TraceIds where the parent span matches `parentFilter` in the window. Optionally restrict to `minParentDurationMs` to focus on slow parents.
2. Aggregate ALL spans across those traces (excluding the matching root span itself) by (ServiceName, SpanName), ranked by `total_time_ms` DESC.
USE WHEN: investigating "where is the time going" for a slow operation. Filter to a specific (ServiceName, SpanName) pair and set `minParentDurationMs` to the threshold above which a parent span counts as "slow" for your investigation.
MULTIPLE OPERATIONS SLOW: when more than one operation shows elevated latency, call this tool ONCE PER (service, operation) and compare the top child rows across the result sets. Operations with the same top child likely share a cause; operations with different top children are independent regressions that happen to co-occur. DO NOT merge multiple operations into a single parentFilter — the cumulative rank then conflates independent investigations into one noisy answer.
RANKING METRIC: `total_time_ms = sum(Duration)` across all matching child spans. This captures the true contribution to elapsed time — a fast-but-frequent child can dominate the latency even if its p99 is unremarkable.
RETURNS: array of rows, each with `service`, `operation`, `total_time_ms`, `calls`, `in_parents` (how many parent traces contained at least one such span), `p50_ms`, `p99_ms`. Plus a `summary` block with the matched-parent count.
NEXT STEP after this tool: once a dominant slow child operation is identified, the canonical follow-up is clickstack_event_deltas with slow-vs-fast spans of THAT child operation as target/baseline (target = {where: SpanName='<slow-child>' AND Duration > X}, baseline = {where: SpanName='<slow-child>' AND Duration <= Y}). The ranked attributes surface what distinguishes slow invocations of the child operation from fast ones.
CROSS-SERVICE BREAKDOWN: this tool does NOT scope children to the parent's service. Slow cross-service calls (database, cache, upstream HTTP) surface naturally — useful for triage.
PAIR TOOL: clickstack_trace_waterfall returns ONE concrete trace as a parent/child tree. Use it for an example after this tool's aggregate breakdown has pointed you at the slow downstream operation.
Clickstack trace waterfallFetch all spans in ONE trace and return them as a parent/child waterfall, pre-ordered for human-readable display. Use this for "show me a concrete example trace" or "what happened in trace X" investigations — the tool walks the cascade for you instead of forcing the model to write self-JOINs in raw SQL.
NOT THE RIGHT TOOL when the question is "where does the time go across MANY slow traces of operation X" — that is the aggregate question, and the answer is clickstack_trace_top_time_consuming_operations (called per affected (service, operation) with `minParentDurationMs`). Use this tool only when you want a single concrete example to inspect, or after the aggregate breakdown has already identified a suspicious operation.
Two modes:
1. Specific trace: pass `traceId`. Returns every span in that trace.
2. Auto-pick: pass `pickFilter` + `pickBy`. The tool finds one matching trace (slowest / first_error / most_recent) and returns its full tree.
Each returned span has: depth (root=0), spanId, parentSpanId, serviceName, spanName, spanKind, durationMs, statusCode, statusMessage, timestamp, and spanAttributes. Spans are pre-order DFS — child spans follow their parent in execution order. The tool also surfaces a `summary` section with the picked TraceId, total span count, and root span info.
When the trace source has a linked logSourceId (the standard config), the response also includes a `logs[]` array of correlated log rows that share the same TraceId — sorted by timestamp, each carrying its `spanId` so the agent can attribute messages to specific spans. 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).
Prefer this over running raw SQL with JOINs on TraceId — it uses the source's configured traceIdExpression / parentSpanIdExpression / spanIdExpression so attribute extraction stays consistent with the rest of the platform.
PAIR TOOL: clickstack_trace_top_time_consuming_operations is the aggregate counterpart — given a parent-span filter, it ranks child operations by total time across MANY matching traces. Use that when the question is "where does time go in slow X" (aggregate), and use THIS tool when the question is "show me one example of a slow X" (single trace).
