Skip to main content

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 use attribute descriptions to understand your telemetry data. By default, these descriptions come from standard OpenTelemetry semantic conventions and Honeycomb’s built-in attribute registry. If your team uses custom attributes, you can define descriptions for them so that AI agents understand what those attributes mean in the context of your system, giving them team-specific context when they search attributes, explore fields, or describe your data.

​
How it works

Honeycomb’s attribute registry is a merged stack of three layers. Your team can customize the top layer to teach AI agents about your team’s specific attributes.

​
Custom attribute descriptions

You define custom attribute descriptions for your Team using the Weaver Registry, a YAML-based format that overlays the standard OpenTelemetry and Honeycomb attribute definitions with your own. For a full list of supported fields, refer to the Supported Fields section.

​
Attribute resolution

Honeycomb resolves attribute descriptions by merging three layers in order:
  1. OpenTelemetry base: Standard OpenTelemetry semantic conventions (for example, http.request.method, service.name).
  2. Honeycomb overlay: Honeycomb-specific field names produced during OTLP translation (for example, duration_ms, samplerate).
  3. Team overlay: Your custom attribute descriptions, defined in the Weaver Registry.
When the same attribute appears in more than one layer, the later layer takes precedence. Your team overlay replaces any default description for attributes you define in it; all other attributes continue to use their standard definitions.

​
Tools that use the registry

The following MCP tools use the merged registry when they reason about your data:
  • search_semconv
  • get_semconv_attribute
  • list_semconv_namespaces
  • get_dataset_columns
  • find_columns
  • get_workspace_context

​
Managing your registry

Use the Weaver Registry in Team Settings to define, update, or remove your team’s custom attribute descriptions.

​
Viewing your registry

To complete this task, you must be a Team Owner.
Check your current registry to confirm what descriptions are active for your team before making changes.
  1. Select Account from the navigation menu, then Team Settings.
  2. Select the Weaver Registry view.
If your team has already defined a registry, it appears in the editor. If not, the editor is empty and ready for input.

​
Creating or updating your registry

To complete this task, you must be a Team Owner.
Add or update your registry to give AI agents richer context about your team’s custom attributes the next time they explore your telemetry data.
  1. Select Account from the navigation menu, then Team Settings.
  2. Select the Weaver Registry view.
  3. Enter or paste your registry YAML into the editor. The YAML must follow the Weaver semantic convention format. For a full list of supported fields, refer to the Supported Fields section.
  4. Select Save Schema to save a new registry, or Update Schema to replace an existing one.
Honeycomb validates the YAML against the Weaver schema before saving. If the YAML is invalid, an error message describes what went wrong.

​
Deleting your registry

To complete this task, you must be a Team Owner.
Delete your registry to remove all custom attribute descriptions for your team.
  1. Select Account from the navigation menu, then Team Settings.
  2. Select the Weaver Registry view.
  3. Select Delete Schema.
  4. Confirm the deletion in the dialog.
MCP tools fall back to the standard OpenTelemetry and Honeycomb attribute descriptions.

​
Registry format

The registry uses the Weaver semantic convention YAML format, the same format used by the OpenTelemetry project to define semantic conventions. Each registry file contains one or more attribute groups. Each group has a unique ID, a type, a brief description, and a list of attributes.

​
Example

The following example defines three custom attributes for a commerce platform: 
groups:
  - id: acme.commerce
    type: attribute_group
    brief: ACME commerce platform attributes
    attributes:
      - name: acme.order.priority
        type: string
        brief: Order fulfillment priority tier (standard, express, overnight)
      - name: acme.warehouse.region
        type: string
        brief: Regional warehouse code that processed the order
      - name: acme.cart.item_count
        type: int
        brief: Number of distinct items in the shopping cart at checkout
For a full list of supported fields, refer to the Supported Fields section.

​
Supported fields

The registry YAML supports the following fields for attributes and groups.

​
Attribute fields

Each attribute supports:
FieldRequiredDescription
nameYesThe attribute name, which must exactly match the field name in your Honeycomb telemetry data.
typeYesThe attribute type: string, int, double, boolean, string[], int[], double[], or boolean[].
briefYesA short description of the attribute. This is what MCP tools surface to AI agents.

​
Group fields

Each group supports:
FieldRequiredDescription
idYesA unique identifier for the group, typically using dot-separated namespacing.
typeYesMust be attribute_group.
briefYesA short description of the group.
noteNoAdditional context or usage notes for the group.
attributesYesThe list of attributes in the group.

​
Best practices

Follow these guidelines to get the most out of your Weaver Registry.
  • Name attributes to exactly match your field names: The name value must match the field name in your Honeycomb telemetry data exactly for MCP tools to apply the description.
  • Write briefs for someone unfamiliar with your system: The brief field is what AI agents see. Describe what the attribute represents and what its values mean, not just what the name suggests.
  • Group related attributes: Use attribute groups to organize attributes by service, domain, or team. The group brief gives AI agents additional context about how those attributes relate to each other.
  • Define only what you need to customize: You only need to define attributes where you want to override or supplement the standard OpenTelemetry or Honeycomb attributes.