Understand what each Honeycomb MCP tool does, when an agent will reach for it, and any requirements that apply.Documentation Index
Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt
Use this file to discover all available pages before exploring further.
How tools are used
AI agents discover MCP tools automatically when they connect. Each tool corresponds to a specific Honeycomb capability, like running a query, fetching a trace, or creating a Board. Agents pick which tool to call based on the tool’s name, description, and your prompt, so you do not normally have to name a tool yourself. This page documents every tool the Honeycomb MCP server exposes. Use it to understand what your agent can do, to write more directed prompts, or to troubleshoot why an agent did or did not use a particular capability.Some tools require specific access scopes or are limited to certain plan tiers.
To explore the full matrix, visit Rate Limits and Scopes.
Tool surface at a glance
Use this table to get a quick overview of what your agent can read and write before diving into the full reference.| Category | Read tools | Write tools |
|---|---|---|
| Workspace discovery | get_workspace_context, get_environment, get_dataset, get_dataset_columns | |
| Query and analysis | run_query, get_query_results, find_queries, find_columns, run_bubbleup | |
| Traces and spans | get_trace, list_spans, get_span_details | |
| Service map and anomalies | get_service_map, get_anomaly_service_profiles | |
| Semantic conventions | search_semconv, get_semconv_attribute, list_semconv_namespaces | |
| Boards | list_boards | create_board, update_board |
| Triggers | get_triggers | create_trigger, update_trigger |
| Service Level Objectives (SLOs) | get_slos | create_slo, update_slo |
| Notification recipients | list_recipients | create_recipient |
| Canvas investigations | canvas_agent_poll_response | canvas_agent_invoke |
| AI conversation analysis | list_aiconversations, get_aiconversation | |
| Other | refinery_docs | feedback |
Workspace discovery
Before your agent can do useful work, it needs to know where it is. These tools help it orient itself within your Honeycomb team and locate the right environments, datasets, and columns.Returns the team name, current time, and a list of environments with their slugs and dataset counts.
Takes no parameters.Agents call this tool first to orient themselves before doing anything else.
Most prompt-driven workflows start here so the agent knows which environments exist before running queries or fetching data.
Returns details for a single environment, including its datasets and calculated fields, sorted by most recent activity.
Returns up to 100 datasets per call.
Returns metadata and the full column schema for a single dataset, including columns and calculated fields in a unified list sorted by last write time.
Returns up to 100 columns per call by default.
Returns the full column schema for a single dataset, with optional sample values for specific columns.For metrics datasets, returns metric names by default.
Pass a
metric_name to discover the attributes available for filtering or grouping a specific metric.Query and analysis
These tools give your agent the ability to ask questions about your data—running aggregation queries, fetching prior query results, finding existing queries, locating relevant columns, and analyzing query subsets with BubbleUp.Runs a time-series aggregation query against a Honeycomb dataset and returns computed results.
Supports compound queries (query math), per-calculation filters, formulas, breakdowns, calculated fields, and relational trace prefixes (
root., parent., child., any.).Agents use this tool to compute custom aggregations that go beyond what simpler discovery tools can answer.
When data is sampled, results include sampling metadata.
Agents can use the usage_mode flag to disable sample-rate correction.Retrieves results and metadata from a previously executed query run.
Accepts a Honeycomb query URL, a query run primary key, or a query ID (which returns the most recent run).Agents use this tool to fetch the output of a saved or earlier query without re-running it.
Searches query history and saved queries by intent and returns matching queries with their run primary keys.
Pair the result with
get_query_results to fetch the actual data.Useful when you want the agent to learn from prior investigations or reuse a saved query.Searches for columns and calculated fields by intent across one or all datasets in an environment.
Agents use this tool to find relevant fields based on natural-language keywords rather than exact column names.Honeycomb’s Weaver registry feeds richer descriptions into this tool, so well-described attributes produce better matches.
Runs a BubbleUp analysis on an existing query result to identify what makes a selected subset of data different from the baseline.
BubbleUp compares value distributions across columns and surfaces the statistically significant differences.
Traces and spans
These tools let your agent move from aggregate query results into raw trace data, exploring span names and attributes across trace-aware datasets, so it can follow a request through your system and identify where things went wrong.Retrieves all spans for a specific trace ID and renders them as a waterfall.
Agents can use the parameters for this tool to zoom in to specific subtrees of a trace and identify errors.
Lists span names in trace data, ranked by count, with how often each is a trace root and which dataset the count came from.
Returns a summary of attributes and their common values observed on spans with a specific name, including which attributes are populated, how many distinct values each has, and the top observed values.
Service map and anomalies
These tools give your agent a higher-level view of your system, so it can understand service dependencies and surface active anomaly detection profiles.EnterpriseReturns a snapshot of service-to-service call dependencies for a specified time range.
Powers the same graph as the Service Map view in Honeycomb.
Returns anomaly detection service profiles for the current team.
Requires that anomaly detection be enabled for the team.
Semantic conventions
These tools let your agent search and inspect OpenTelemetry semantic convention attributes, including any team-specific extensions defined in the Weaver registry, so it can write better instrumentation and more accurate queries.Searches the semantic convention registry for attributes matching a query.
Returns full definitions of one or more semantic convention attributes by their exact names.
Lists the top-level semantic convention namespaces available in the team’s registry, including any team-specific attribute customizations.
Boards
These tools let your agent create and manage Boards, so investigation results can be captured and shared with your team in a format everyone can revisit.Lists Boards in an environment, or returns the full contents of a single Board by ID.
Use this before
update_board to inspect existing panels and IDs.Creates a Board with query panels, Service Level Objective (SLO) panels, and text (Markdown) panels.
Panels appear in the order you specify them and can include explicit width and height.
Supports preset filters that become filter dropdowns on the Board.To learn more about Boards, visit Customize Boards.
Updates an existing Board.
Supports renaming, adding, removing, updating, and reordering panels, plus replacing preset filters and tags.
Triggers
These tools let your agent inspect, create, and update Honeycomb Triggers, so you can automate alerting based on query thresholds without leaving your workflow.Lists Triggers for the team, or returns detailed configuration for a single Trigger, including recipients with their type, name or target, and ID.
Creates a Trigger that fires alerts when query results cross a threshold.To learn more about Triggers, visit Create a Trigger.
Updates an existing Trigger.
Service Level Objectives (SLOs)
These tools let your agent inspect, create, and update Honeycomb Service Level Objectives (SLOs), so you can establish and maintain reliability targets for your services.Lists SLOs for the team, or returns detailed status and graphs for a single SLO.
Creates an SLO with an auto-created Service Level Indicator (SLI) derived column.
Provide the SLI expression and an alias, and the tool creates the derived column if needed, validates the expression, and then creates the SLO.To learn more about SLOs, visit Create an SLO.
Updates an existing SLO.
Partial-update semantics apply; omitted fields keep their current values.Dataset associations are fixed at creation time; create a new SLO to use different datasets.
Notification recipients
These tools let your agent manage the notification destinations that Triggers and Service Level Objective (SLO) burn alerts route to, so alerts reach the right people and systems.Lists all pre-registered notification recipients for the team, including email, Slack, PagerDuty, and webhooks, with their IDs.
Creates a notification recipient that can be attached to Triggers and SLO burn alerts.
Returns the recipient ID for use with
create_trigger and update_trigger.To learn more about recipients, visit Recipients for Notifications.Canvas investigations
These tools let your agent interact with Honeycomb Canvas and contribute to collaborative investigations alongside your team, running queries, laying out evidence, and summarizing findings on your team’s behalf.Sends a message to the Canvas agent.
If an investigation ID is provided, the message is routed to the user’s agent in that investigation.
Otherwise, a new investigation is created.
Polls for the result of a previously-issued
canvas_agent_invoke call.To learn more about Canvas investigations, visit Canvas.AI conversation analysis
These tools let your agent analyze telemetry from other AI agents in your stack that emit OpenTelemetrygen_ai.* attributes, answering questions like “which conversations had errors” and “how many tokens did this agent use” without requiring you to compose run_query calls.
Lists recent AI agent conversations (
gen_ai.conversation.id values) in an environment, ordered by total event count.
Includes a per-conversation breakdown of agents, services, event counts, error counts, and token usage.Returns the full event timeline for a single AI conversation by its
gen_ai.conversation.id value, including every LLM call, tool call, and related agent event with span name, operation, agent name, model, tool name, duration, and error detail.
Also includes an aggregate summary with LLM call count, tool call count, failure count, total tokens, and total duration.Other tools
These tools cover capabilities that do not fit neatly into the categories above but are still useful for getting the most out of Honeycomb MCP.Reads from Honeycomb Refinery documentation, so your agent can answer Refinery configuration questions without leaving the conversation.
Submits feedback about the Honeycomb MCP server experience to the Honeycomb team that maintains it.
Ask your agent to “submit feedback to Honeycomb” with your message.
Rate limits and scopes
Understanding rate limits and required scopes helps you configure your agent correctly and avoid unexpected errors during operation.Rate limits
Honeycomb MCP enforces per-tool rate limits to protect platform stability. Most tools share a default limit of 50 calls per minute, but discovery and metadata tools allow higher limits, and expensive or mutating tools have lower ones.| Tool | Limit per minute |
|---|---|
get_workspace_context, get_dataset, get_environment, list_boards, list_recipients, find_columns, refinery_docs | 200 |
search_semconv, get_semconv_attribute, list_semconv_namespaces | 300 |
canvas_agent_poll_response | 300 |
get_triggers, get_anomaly_service_profiles, find_queries, get_query_results | 150 |
run_query, get_trace, get_dataset_columns, get_slos, feedback | 100 |
update_trigger, update_slo | 30 |
create_trigger, create_slo, create_recipient, canvas_agent_invoke | 20 |
get_service_map | 10 |
| All other tools | 50 (default) |
Rate limits are subject to change.
Required scopes for write tools
Write tools require themcp:write scope to protect your data from unintended changes.
When connecting with an API key, your key must grant the Write scope under Model Context Protocol, and the API key’s environment access must include any environment the agent will write to.
| Write tool | Required scope |
|---|---|
create_board, update_board | mcp:write |
create_trigger, update_trigger | mcp:write |
create_slo, update_slo | mcp:write |
create_recipient | mcp:write |
canvas_agent_invoke | mcp:write |
feedback | mcp:write |
Next steps
- Core Concepts: Understand how Honeycomb MCP works.
- Example Use Cases: Review real-world examples of prompts and workflows.
- Troubleshooting: Diagnose common issues with tool availability or behavior.