> ## 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.

# Honeycomb MCP Tools Reference

> Reference for the tools Honeycomb MCP exposes to AI agents, including discovery, query, trace, Board, Trigger, SLO, and Canvas investigation tools.

Understand what each Honeycomb MCP tool does, when an agent will reach for it, and any requirements that apply.

## 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.

<Note>
  Some tools require specific access scopes or are limited to certain plan tiers.
  To explore the full matrix, visit [Rate Limits and Scopes](#rate-limits-and-scopes).
</Note>

## 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](#workspace-discovery)                       | `get_workspace_context`, `get_environment`, `get_dataset`, `get_dataset_columns` |                                    |
| [Query and analysis](#query-and-analysis)                         | `run_query`, `get_query_results`, `find_queries`, `find_columns`, `run_bubbleup` |                                    |
| [Traces and spans](#traces-and-spans)                             | `get_trace`, `list_spans`, `get_span_details`                                    |                                    |
| [Service map and anomalies](#service-map-and-anomalies)           | `get_service_map`, `get_anomaly_service_profiles`                                |                                    |
| [Semantic conventions](#semantic-conventions)                     | `search_semconv`, `get_semconv_attribute`, `list_semconv_namespaces`             |                                    |
| [Boards](#boards)                                                 | `list_boards`                                                                    | `create_board`, `update_board`     |
| [Triggers](#triggers)                                             | `get_triggers`                                                                   | `create_trigger`, `update_trigger` |
| [Service Level Objectives (SLOs)](#service-level-objectives-slos) | `get_slos`                                                                       | `create_slo`, `update_slo`         |
| [Notification recipients](#notification-recipients)               | `list_recipients`                                                                | `create_recipient`                 |
| [Canvas investigations](#canvas-investigations)                   | `canvas_agent_poll_response`                                                     | `canvas_agent_invoke`              |
| [AI conversation analysis](#ai-conversation-analysis)             | `list_aiconversations`, `get_aiconversation`                                     |                                    |
| [Other](#other-tools)                                             | `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.

<ParamField path="get_workspace_context" type="read">
  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.
</ParamField>

<ParamField path="get_environment" type="read">
  Returns details for a single environment, including its datasets and calculated fields, sorted by most recent activity.
  Returns up to 100 datasets per call.
</ParamField>

<ParamField path="get_dataset" type="read">
  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.
</ParamField>

<ParamField path="get_dataset_columns" type="read">
  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.
</ParamField>

## 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.

<ParamField path="run_query" type="read">
  Runs a time-series aggregation query against a Honeycomb dataset and returns computed results.
  Supports compound queries ([query math](/investigate/query/math)), per-calculation filters, formulas, breakdowns, [calculated fields](/investigate/query/build/calculated-fields), and [relational trace prefixes](/investigate/query/build#relational-fields) (`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.
</ParamField>

<ParamField path="get_query_results" type="read">
  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.
</ParamField>

<ParamField path="find_queries" type="read">
  Searches query history and saved queries by intent and returns matching queries with their run primary keys.
  Pair the result with [`get_query_results`](#param-get-query-results) to fetch the actual data.

  Useful when you want the agent to learn from prior investigations or reuse a saved query.
</ParamField>

<ParamField path="find_columns" type="read">
  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](/configure/teams/customize-attributes/) feeds richer descriptions into this tool, so well-described attributes produce better matches.
</ParamField>

<ParamField path="run_bubbleup" type="read">
  Runs a [BubbleUp](/investigate/analyze/identify-outliers) 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.
</ParamField>

## 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.

<ParamField path="get_trace" type="read">
  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.
</ParamField>

<ParamField path="list_spans" type="read">
  Lists span names in trace data, ranked by count, with how often each is a trace root and which dataset the count came from.
</ParamField>

<ParamField path="get_span_details" type="read">
  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.
</ParamField>

## 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.

<ParamField path="get_service_map" type="read">
  <Badge>Enterprise</Badge>

  Returns a snapshot of service-to-service call dependencies for a specified time range.
  Powers the same graph as the [Service Map](/investigate/observe/service-map/) view in Honeycomb.
</ParamField>

<ParamField path="get_anomaly_service_profiles" type="read">
  Returns anomaly detection service profiles for the current team.

  <Info>
    Requires that anomaly detection be enabled for the team.
  </Info>
</ParamField>

## 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.

<ParamField path="search_semconv" type="read">
  Searches the semantic convention registry for attributes matching a query.
</ParamField>

<ParamField path="get_semconv_attribute" type="read">
  Returns full definitions of one or more semantic convention attributes by their exact names.
</ParamField>

<ParamField path="list_semconv_namespaces" type="read">
  Lists the top-level semantic convention namespaces available in the team's registry, including any [team-specific attribute customizations](/configure/teams/customize-attributes/).
</ParamField>

## 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.

<ParamField path="list_boards" type="read">
  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.
</ParamField>

<ParamField path="create_board" type="write">
  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](/observe/boards/customize/).
</ParamField>

<ParamField path="update_board" type="write">
  Updates an existing Board.
  Supports renaming, adding, removing, updating, and reordering panels, plus replacing preset filters and tags.
</ParamField>

## Triggers

These tools let your agent inspect, create, and update Honeycomb [Triggers](/notify/triggers/), so you can automate alerting based on query thresholds without leaving your workflow.

<ParamField path="get_triggers" type="read">
  Lists Triggers for the team, or returns detailed configuration for a single Trigger, including recipients with their type, name or target, and ID.
</ParamField>

<ParamField path="create_trigger" type="write">
  Creates a Trigger that fires alerts when query results cross a threshold.

  To learn more about Triggers, visit [Create a Trigger](/notify/triggers/create/).
</ParamField>

<ParamField path="update_trigger" type="write">
  Updates an existing Trigger.
</ParamField>

## Service Level Objectives (SLOs)

These tools let your agent inspect, create, and update Honeycomb Service Level Objectives ([SLOs](/notify/slos/)), so you can establish and maintain reliability targets for your services.

<ParamField path="get_slos" type="read">
  Lists SLOs for the team, or returns detailed status and graphs for a single SLO.
</ParamField>

<ParamField path="create_slo" type="write">
  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](/notify/slos/create/).
</ParamField>

<ParamField path="update_slo" type="write">
  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.
</ParamField>

## 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.

<ParamField path="list_recipients" type="read">
  Lists all pre-registered notification recipients for the team, including email, Slack, PagerDuty, and webhooks, with their IDs.
</ParamField>

<ParamField path="create_recipient" type="write">
  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](/notify/recipients/).
</ParamField>

## Canvas investigations

These tools let your agent interact with Honeycomb [Canvas](/investigate/canvas) and contribute to collaborative investigations alongside your team, running queries, laying out evidence, and summarizing findings on your team's behalf.

<ParamField path="canvas_agent_invoke" type="write">
  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.
</ParamField>

<ParamField path="canvas_agent_poll_response" type="read">
  Polls for the result of a previously-issued `canvas_agent_invoke` call.

  To learn more about Canvas investigations, visit [Canvas](/investigate/canvas/).
</ParamField>

## AI conversation analysis

These tools let your agent analyze telemetry from other AI agents in your stack that emit OpenTelemetry `gen_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.

<ParamField path="list_aiconversations" type="read">
  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.
</ParamField>

<ParamField path="get_aiconversation" type="read">
  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.
</ParamField>

## 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.

<ParamField path="refinery_docs" type="read">
  Reads from Honeycomb [Refinery](/manage-data-volume/sample/honeycomb-refinery/) documentation, so your agent can answer Refinery configuration questions without leaving the conversation.
</ParamField>

<ParamField path="feedback" type="write">
  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.
</ParamField>

## 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-limit responses include the time at which you can retry.

<Info>
  Rate limits are subject to change.
</Info>

### Required scopes for write tools

Write tools require the `mcp: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`    |

OAuth users get write scopes automatically when they grant write access during the consent flow.
To explore full configuration details, visit [Setting Up an API Key](/integrations/mcp/configuration-guide/#setting-up-an-api-key).

## Next steps

* [Core Concepts](/integrations/mcp/concepts/): Understand how Honeycomb MCP works.
* [Example Use Cases](/integrations/mcp/use-cases/): Review real-world examples of prompts and workflows.
* [Troubleshooting](/integrations/mcp/troubleshooting/): Diagnose common issues with tool availability or behavior.