Honeycomb (EU)

Submit feedback about Honeycomb's MCP server to the agentic-intelligence team. When to use: - A tool returned unexpected, wrong, or confusing data. - You wanted a capability that no tool in this server provides. - A workflow felt unnecessarily clunky or required too many tool calls. - A tool description was misleading and caused you to use the wrong tool. Be specific: name the tool you used, what you tried, what you expected, and what you observed. Vague feedback is hard to act on. Pairs with: any tool — call this after completing (or failing) a task to report quality issues.

Search for columns and calculated fields by intent across one or all datasets in an environment. When to use: - "What column has the error rate?" / "Find columns related to duration or latency" — intent-based discovery. - Before composing a run_query, to confirm that columns with the right names exist. - When you are not sure which dataset contains the column you need (omit dataset_slug to search all). - After get_dataset_columns returns too many results to scan, use this to narrow by semantic relevance. Difference from get_dataset_columns: this tool ranks results by relevance to your search input across all datasets; get_dataset_columns returns the complete schema for one specific dataset. Pairs with: get_dataset_columns (full schema once you know the right dataset); run_query (use validated column names here); get_dataset (confirm dataset exists before scoping search).

Search query history and saved queries by intent; returns matching queries with their run PKs. When to use: - "Has anyone queried the error rate for checkout?" — check existing work before composing a new query. - Before calling run_query, verify a semantically similar query does not already exist. - "Show me recent queries for service X" — surface what the team has been investigating. - When the user pastes a query name or description and wants to find the underlying spec. Returns query specifications and run_pks. Pass a run_pk to get_query_results to retrieve the full results from that specific execution. Pairs with: get_query_results (fetch results from a returned run_pk); run_query (run a new query once you've confirmed no similar one exists); create_board (add a found query_id as a panel).

Get dataset metadata and its full column schema (columns + calculated fields), sorted by most recent write activity. When to use: - "What columns does the api-service dataset have?" — retrieve the schema for one dataset. - Before run_query, to verify column names and types exist in the target dataset. - "When was this dataset last updated?" — dataset metadata includes oldest queryable event time. Difference from get_dataset_columns: this tool returns dataset-level metadata (description, granularity, oldest event) alongside the column list. get_dataset_columns additionally supports fetching sample values for specific columns and has metrics-dataset support via metric_name. Pairs with: get_environment (upstream — confirms the dataset slug); get_dataset_columns (fetch sample values for columns or explore metrics datasets); find_columns (search across all datasets when the right dataset is unknown).

Get the full column schema for one dataset, with optional sample values for specific columns. When to use: - Validating column names before composing a run_query (check the column exists and note its type). - "What values does the status column hold?" — pass the column name in 'columns' to fetch sample values. - Exploring a metrics dataset: list metric names first, then pass metric_name to discover filterable attributes. - When find_columns returns too many results and you want the authoritative schema for one dataset. Pairs with: find_columns (intent-based search when you do not know the dataset); get_dataset (dataset metadata alongside schema); run_query (use validated column names here).

Get details for a specific environment, including its dataset list sorted by most recent activity. When to use: - After get_workspace_context returns environment slugs, drill into one to see which datasets it contains. - "What datasets exist in staging?" — list mode for dataset discovery. - Before calling get_dataset or get_dataset_columns, confirm the dataset slug by checking environment contents. Returns up to 100 datasets per page by default, sorted by most recent write activity. Pairs with: get_workspace_context (upstream — provides environment slugs); get_dataset (drill into a specific dataset's schema); get_dataset_columns (full column schema once you know the dataset slug); find_columns (search across all datasets in this environment by intent).

Retrieve results and metadata from an existing query execution. Accepts a Honeycomb URL, a run_pk, or a query_id (returns most recent run). Provide exactly one of these three inputs. When to use: - After find_queries returns a run_pk and you want the actual result rows. - The user pastes a Honeycomb query URL from the browser — extract results without re-running. - After run_query executes a new query and returns a run_pk, use this to fetch the structured output. - You have a query_id and want the latest available result without triggering a new execution. Pairs with: find_queries (source of run_pks); run_query (source of fresh run_pks); list_boards (board detail mode returns query_ids per panel — pass them as query_id here to get the most recent run).

Get a snapshot of service-to-service call dependencies for a specified time range. When to use: - User asks "what calls service X?" or "what does service Y depend on?" — this is the right answer. - Understanding upstream/downstream dependencies before adding instrumentation or making a change. - Auditing which services communicate with each other across an environment. Pairs with: - list_spans — after discovering services here, use list_spans to see which span names each service emits. - run_query — for aggregate request volume or error rates on a specific caller→callee edge, query with service.name breakdown. - get_span_details — to inspect attribute distributions on a specific operation within a discovered service. Returns a Mermaid diagram of caller→callee edges, plus service and dependency counts. filter_nodes uses OR logic: returns all edges where any listed service appears as caller or callee.

Returns Anomaly Signals for the current team. An Anomaly Signal tracks a service in a dataset and detects when its behavior deviates from its historical baseline. Use this tool to investigate a specific Anomaly Signal or to find relevant Anomaly Signals with the allowed filters. Supports: - Detail: pass signal_hcid (other filters ignored). Returns the full Anomaly Signal + query hints + (optional) historical anomalies. - List: pass environment_slug (required) plus any combination of optional filters (service_name, dataset_slug, measured_signal, status, anomalous_only). Returns a table of Anomaly Signals. Use this to find a signal_hcid to pass back in detail mode. Defaults to active Anomaly Signals.

List SLOs for the team, or fetch detailed status and graphs for a single SLO. When to use: - "What SLOs do we have?" / "Is there an SLO for service X?" — list mode (no slo_id). - "What's the compliance on the checkout SLO?" — detail mode by slo_id. - Before creating a new SLO with create_slo, check here that one doesn't already exist. - Checking which SLOs are currently triggered or burning budget fast. Modes: - List mode (no slo_id): paginated table with name, target, compliance, budget remaining, burn alert count, and tags. Filter by environment_slug or tags. - Detail mode (slo_id provided): full configuration, current status, budget burndown graph, historical compliance graph, and all configured burn alerts with recipients. Pairs with: - create_slo / update_slo — list first to avoid duplicates; detail view reveals current config to inform updates. - get_triggers — burn alerts fire as triggers; cross-reference trigger IDs with the burn alert recipients shown here. - create_board — boards can include SLO panels; use list mode to get slo_id values for board construction.

Summarize attributes and their common values observed on spans with a specific name. USE THIS AFTER list_spans (or whenever you already know a span_name) and BEFORE run_query. It tells you which attributes are populated on that operation, how many distinct values each has, and the top observed values — enough to answer most "what does X look like / what fields does X have / what status codes does X return / which users hit X" questions directly, without composing a custom query. Only escalate to run_query when you need: exhaustive value distributions beyond the sample cap, custom calculations (P95/P99, HEATMAP, math across columns), per-attribute COUNT/SUM aggregates over the full time range, or comparison/baseline analysis. Results are paginated with page and items_per_page after applying the sample cap. Paging is a presentation control, not an exhaustive cursor. Values are based on matching span samples, capped at 1000 rows across the selected time range.

Retrieve all spans for a specific trace ID and render them as a waterfall. When to use: - User pastes a trace ID from logs, a Slack alert, or the Honeycomb UI — fetch it here. - Drilling into a specific trace from a run_query result (trace.trace_id column). - Comparing parent/child span timing for a known trace to diagnose latency attribution. Pairs with: - run_query — filter where trace.trace_id = <value> to find traces matching a pattern, then drill in here. - list_spans / get_span_details — use first to discover span names so you can focus this view with focus_span_id. - run_bubbleup — if a query surfaces an anomalous cluster, BubbleUp identifies why; get_trace lets you verify with individual examples. <sampling> Span counts are actual stored spans, not sample-rate-adjusted. When sampling is active, the output includes a mean sample rate. Do not compare corrected query COUNTs (which are sample-rate-adjusted) directly to trace span counts. </sampling>

List triggers (alert rules) for the team, or fetch full configuration for a single trigger. When to use: - "What alerts are firing?" / "What triggers do we have?" — list mode (no trigger_id). - "Show me the config for trigger X" / "Who gets paged for this alert?" — detail mode by trigger_id. - Auditing trigger configurations before creating or updating triggers. - Investigating an active alert to understand its threshold, query, and recipients. Modes: - List mode (no trigger_id): paginated table with name, status, threshold, frequency, recipients, and tags. - Detail mode (trigger_id provided): full query spec (calculations, filters, group-by, formulas), threshold, schedule, and recipient list. Recipients are shown as: type (name/target) [id:ID] — e.g. 'pagerduty (Platform Rotation) [id:abc123]'. Dynamic baseline vs static threshold: triggers with a populated 'baseline' column (list view) or 'Baseline' row (detail view) use a dynamic baseline — the threshold value is a delta (e.g. 50% higher than 1 hour prior), not an absolute count. The detail view formats Threshold as plain-English when baseline is in use. Pairs with: - create_trigger / update_trigger — list first to avoid duplicates; detail view shows current config to inform updates. - list_recipients — to resolve recipient IDs to human-readable names before creating or updating a trigger. - find_queries — to inspect the underlying saved query for a saved-query-backed trigger. - get_slos — SLO burn alerts appear as triggers; cross-reference here when an SLO's burn alert fires.

List boards (saved dashboards) in an environment, or fetch one board's full contents by ID. When to use: - "What dashboards do we have for service X" / "is there an existing board for Y" — list mode with tag filters. - "Show me the contents of board Z" — detail mode by board_id, returns every panel (queries, SLOs, text) with descriptions. - Before calling create_board, to check whether a similar board already exists. Modes: - List mode (default): pass environment_slug, optionally filter by tags (AND semantics across multiple tags). Returns paginated board metadata only. - Detail mode: pass board_id (environment_slug still required). Returns the single board with all panels and their underlying queries/SLOs resolved. Each query panel also reports chart_type, display_style, and thresholds in the exact forms create_board / update_board accept, so you can round-trip a panel's configuration. Pairs with: create_board (this tool's output reveals existing tags and naming conventions to follow); get_query_results (panel query_ids from detail mode can be passed as query_id to fetch the most recent run's results).

List all pre-registered notification recipients (email, Slack, PagerDuty, webhook) for the team. When to use: - Before create_trigger or update_trigger, to find the recipient IDs to attach. - "What Slack channels are configured for alerts?" — audit existing notification targets. - When a user asks which notification channels are available for a new alert. Returns each recipient's ID, type, and routing details. Pass recipient IDs directly to create_trigger or update_trigger. Pairs with: create_recipient (register a new notification target); create_trigger (attach recipients by ID); update_trigger (update which recipients a trigger notifies).

List span names in trace data, ranked by count, with how often each is a trace root and which dataset the count came from. USE THIS FIRST for any question about what's happening in the system: "what's slow", "what's erroring", "what does service X do", "which endpoints exist", "what jobs run here", "show me the operations on Y". It is faster, cheaper, and more diagnostic than composing an equivalent run_query by hand, and it works across all trace-aware datasets in the environment without you having to know which dataset to target. Workflow: 1. Call list_spans (this tool) to see the span-name landscape and pick a candidate. 2. Call get_span_details with that span_name (and its dataset_slug from the row) to learn which attributes and values are present. 3. ONLY if you need a custom calculation, exhaustive value distribution, percentile/heatmap, or per-attribute aggregate that get_span_details cannot express — fall through to run_query, scoped to the dataset_slug from the row. To find which span carries a specific attribute instead of ranking by volume, use populates_attribute (see its property description). Each row is a (span_name, dataset_slug) pair — the same span_name can appear in multiple datasets, so use the row's dataset_slug (not just span_name) in follow-up calls. root_count is the subset of count with no parent (trace roots): root_count == count means always a root (HTTP handler, root job); 0 < root_count < count means it appears as both root and child (often a name shared across services); root_count == 0 means always a child (DB call, internal helper). Results are paginated with page and items_per_page after applying the query cap; narrow the time range or dataset for deeper coverage rather than paging exhaustively.

Vendor-specific guidance for migrating existing telemetry to Honeycomb without disrupting the vendor setup. The onboarding flow's migration branch calls this when it detects a supported vendor.

Record the current onboarding step. The onboarding flow calls this at each step so the session's MCP activity is attributed to the step it happened in.

Read Honeycomb Refinery documentation. Refinery is Honeycomb's trace-aware tail-based sampling proxy. Available topics: - overview: Refinery overview and key concepts - architecture: Architecture, deployment patterns, and how it works - sampling-types: Sampling strategies (deterministic, dynamic, rules-based, throughput) - stress-relief: How stress relief works and how to respond when it activates - troubleshooting: Common Refinery issues, diagnostic queries, and solutions - metrics: Complete reference of all Refinery metrics with descriptions - configuration: Configuration reference for all Refinery settings - rules: Guide to writing sampling rules for the rules-based sampler Use this tool when you need detailed technical information about Honeycomb Refinery to answer user questions.

Run BubbleUp analysis to find what makes a selected data subset different from the baseline. BubbleUp compares value distributions across all schema columns between a "foreground" selection (the interesting region) and the remaining data (the baseline). Columns where the foreground and baseline distributions diverge most are ranked highest. When to use: - User asks "why did latency spike at 14:00?" — pick a heatmap region and BubbleUp it. - Investigating a heatmap selection returned by run_query; you already have a query_pk. - "Compare this known-bad subset to baseline" — user wants to know what's different. - After a run_query heatmap shows an interesting region, surface the root-cause attributes. Pairs with: - run_query — must run first to obtain a query_pk; that query's time range becomes the baseline. - get_trace — drill into specific traces that fall inside the anomalous selection. - find_columns / get_dataset_columns — if you need to know what columns exist before starting analysis. Modes: - New analysis: provide query_pk + selection (heatmap or group selection). For a 2D selection, use either absolute or wall-clock-relative from/to, or source-query-relative time_start/time_end; do not combine them. - Paginate existing results: provide bubbleup_result_id (query_pk and selection are ignored).

Run an aggregate query or return a scoped set of raw rows from a Honeycomb dataset. When to use this tool: - "Reconstruct the events for one session" — filter to the session and request the needed raw_row_columns. - "Compute a percentile / histogram of X" — use P50/P99/HEATMAP calculations. - "Show me error rate before and after deploy" — use two named calcs + a formula, scoped by time. - "Rank services by p99 latency" — use P99 with a breakdown + order. - "See distinct values of X and their frequency" — COUNT with a breakdown on X. - "Compare request volume across services" — COUNT breakdown on service.name. - "Find endpoints where tail latency exceeds 1s" — P99 + having clause. - "Generate a heatmap of request duration" — HEATMAP calculation. When NOT to use this tool: - Discovering what spans or operations exist → use list_spans instead. - Looking at a specific trace → use get_trace instead. - Finding existing saved queries → use find_queries instead. - Exploring which columns a dataset has → use get_dataset_columns or find_columns first. Pairs with: list_spans, get_span_details, find_columns, get_dataset_columns, get_trace, run_bubbleup. <examples> Basic COUNT over the last 24 hours: ```json {"environment_slug": "production", "dataset_slug": "api", "query_spec": {"calculations": [{"op": "COUNT"}], "from": "-24h"}} ``` Raw rows for one session, limited to ten selected columns and up to 100 matching events: ```json {"environment_slug": "production", "dataset_slug": "agent-events", "query_spec": { "filters": [{"column": "session.id", "op": "=", "value": "session-123"}], "from": "-2h"}, "raw_row_columns": [ "session.id", "gen_ai.operation.name", "gen_ai.agent.name", "gen_ai.tool.name", "gen_ai.tool.call.id", "gen_ai.tool.call.arguments", "gen_ai.tool.call.result", "error", "duration_ms", "trace.trace_id"], "results_limit": 100} ``` When a raw-row response includes next_cursor, fetch the next page by repeating the request with the same scope, replace the prior time fields in query_spec with the response Metadata's absolute from and to, and pass next_cursor as cursor. Continue until next_cursor is omitted. Error rate formula: two named calcs combined with a formula, ordered by the formula name (the correct ordering style when formulas are present). The passthrough formula "volume" surfaces a raw calc value alongside formulas: ```json {"environment_slug": "production", "dataset_slug": "api", "query_spec": { "calculations": [ {"op": "COUNT", "name": "total"}, {"op": "COUNT", "name": "errors", "filters": [{"column": "error", "op": "=", "value": true}]}], "formulas": [ {"name": "error_rate", "expression": "$errors / $total * 100"}, {"name": "volume", "expression": "$total"}], "breakdowns": ["service.name"], "orders": [{"column": "error_rate", "order": "descending"}], "from": "-1h", "limit": 20}} ``` Relational fields: any.X in a breakdown requires a matching WHERE filter on the same any.X column: ```json {"environment_slug": "production", "dataset_slug": "traces", "query_spec": { "calculations": [{"op": "COUNT"}, {"op": "P99", "column": "duration_ms"}], "filters": [{"column": "any.http.route", "op": "exists"}], "breakdowns": ["any.http.route"], "from": "-2h"}} ``` </examples> <interpreting_results> The response is rendered as Markdown with these sections (each is omitted if empty): - "# Results" — a Markdown table of aggregate rows. Headers are breakdown columns followed by calculation columns. When formulas are present, the table contains ONLY breakdown columns and formula columns — raw calculation columns (including percentiles like P50/P95, and even named COUNTs) are NOT rendered. To surface a raw calculation's value alongside formulas, add a passthrough formula such as {"name": "p95", "expression": "$p95_latency"}. If a breakdown's cardinality exceeded the spec's limit, an "OTHER" row collapses the remainder; a "TOTAL" row may also appear summing across groups. A "Truncated: shown N / total M" footer indicates more rows than the table displays. - 1D heatmaps render inline within Results when a HEATMAP calculation has no breakdown. - "# Raw Rows" — present when raw_row_columns is provided. Contains matching events restricted to those columns, plus timestamp. The row and column counts share a 1000-value budget. Metadata includes the effective absolute from and to. A full page also includes next_cursor; pass it as cursor in an otherwise equivalent request with those absolute time bounds to fetch more rows. Pagination is not a snapshot. - "# Time Series" — ASCII line graphs per group when the spec has a granularity (time-bucketed series). Width 120, height 12. - "# Heatmaps" — 2D time-series heatmaps when a HEATMAP calculation is paired with breakdowns or granularity. - "# Markers" — deploy/incident markers overlapping the time range, when present. Includes both dataset-scoped and environment-wide markers; the Scope column labels each row "dataset" or "environment". - "# Query Spec" — the canonicalized JSON spec the server actually executed. Useful when comparing what you sent to what ran. - "Metadata:" YAML block at the bottom — contains query_run_pk (passable to get_query_results), query_url (Honeycomb permalink to share with humans), query_result_json / query_result_image (download URLs), elapsed_str, granularity, total (result count), rows_examined. When the requested or auto-selected granularity was adjusted (clamped to the valid window, or raised to the metrics-dataset floor), granularity_note explains the change and granularity_requested echoes an explicit request. When data is sampled, a sampling banner appears above Results listing the mean sample rate and which calculations are sample-rate-weighted vs. raw. If mean_sample_rate > 10x and usage_mode is off, an extra warning notes that COUNT values are corrected estimates and won't match raw trace span counts. When results contain a trace.trace_id column (grouped-by or in raw rows), a "Trace links" block above Results lists ready-to-use UI URLs for those traces. These are already scoped to this query's time range — pass them through verbatim. Do NOT hand-build a trace URL from a trace ID: a link without the query's time scope resolves against a default 2h window and fails to load older traces. </interpreting_results> Important: filter operators use symbols (=, >=, !=). Expression functions inside calculated_fields use words (GTE, EQUALS). Never use GTE/LTE as filter operators.

Query the semantic convention registry: the latest embedded OTel semconv release merged with Honeycomb's overlay, plus the team's custom schema when one exists. Actions: - search: substring match on names/briefs; requires query; concise results. - get: exact ids; full definitions; unknown ids appear in not_found. - list_namespaces: top-level namespaces; optional signal_type filter. Use returned canonical names in queries; Honeycomb normalises names at ingest.

Edit an existing board (dashboard) in place. Add, remove, update, or reorder panels; rename; and replace preset filters or tags. When to use: - "Add the new error-rate query to the API board" — append panels to an existing board. - "Remove the deprecated SLO panel from this dashboard" — drop a panel by id. - "Rename the panel" / "switch this query to a table view" — modify an existing panel's name, description, chart_type, display_style, thresholds, or size. - "Add a 500ms threshold line to the latency panel" — set thresholds on a query panel via update_panels or add_panels. - "Reorder the board so SLOs come first" — reorder panels via panel_order. - "Update the preset filters / tags" — replace the full set (replace, not merge). - Always run list_boards with board_id first so you have the current type+id of each panel. Pairs with: list_boards (board_id and per-panel ids; the IDs you reference here come from there), find_queries (query run PKs for new query panels), get_slos (SLO PKs for new SLO panels), create_board (create instead of update). Operations apply in this order: remove_panels -> update_panels -> add_panels -> panel_order. Within a single call: removed panels can be referenced in remove_panels but not anywhere else; newly added text panels can not be referenced in panel_order or update_panels because they have no stable id until saved (added text panels are appended after any ordered panels). Replacement-set semantics: tags and preset_filters replace the full set when provided. To add one tag, read the current tags from list_boards, append, and pass the full updated list. Pass an empty array to clear. Omit entirely to leave unchanged. Per-panel thresholds also replace the full set: pass [] to clear, omit to leave unchanged. Sizing: if you omit size on an added panel, MCP auto-sizes it (queries by complexity; SLO/text use defaults). For updated panels, size is preserved unless you explicitly supply a new size or set auto_size_updated_panels=true (which auto-sizes query panels in update_panels when their size is omitted).

Update an existing SLO. Only the fields you supply change; omitted fields keep their current values. When to use: - "Tighten the SLO target to 99.95%" / "extend the window to 30 days" — adjust reliability parameters. - "Rename this SLO" / "update the SLO description" — housekeeping changes. - "Replace the SLO's tags" — tag management (tags replace entirely; pass empty array to clear all). - Datasets cannot be changed after creation; create a new SLO if you need different datasets. Pairs with: get_slos (retrieve slo_id and current values), create_slo (create instead of update), update_trigger (update a paired burn-alert trigger simultaneously). Tag replacement semantics: when tags is provided it replaces the entire tag set. To add one tag, first read the current tags via get_slos, append the new tag, and pass the full updated list.

Update an existing trigger. Partial update — only the fields you supply change; omitted fields keep their current values. When to use: - "Disable this trigger temporarily" — set disabled=true without touching other fields. - "Add a Slack channel to the trigger's recipients" — replace recipients with the full updated list (note: replaces, does not merge). - "Lower the threshold from 5% to 3%" — update threshold.value. - "Slow down the evaluation frequency" — change frequency. Pairs with: get_triggers (retrieve trigger_id and current state), list_recipients / create_recipient (get recipient IDs before updating), update_slo (update the paired SLO at the same time). Recipients replacement semantics: when recipients is provided, it replaces the entire recipients list. To add one recipient, read current recipients from get_triggers, append the new ID, then pass the full list here. Pass an empty array [] to remove all recipients.