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

# Customize Telemetry Schema

> Define a custom telemetry schema so that MCP tools understand your team's telemetry data and give AI agents accurate, team-specific context.

[Honeycomb MCP tools](/integrations/mcp/concepts/) use attribute descriptions to understand your telemetry data.
By default, these descriptions come from standard [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/) 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 a custom telemetry schema, a YAML-based configuration that overlays the standard OpenTelemetry and Honeycomb attribute definitions with your own.

For a full list of supported fields, refer to the [Supported Fields](#supported-fields) section.

### Attribute resolution

Honeycomb resolves attribute descriptions by merging three layers in order:

1. **OpenTelemetry base**: Standard [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/) (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 as a custom telemetry schema.

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 **Telemetry Schema** page in **Team Settings** to define, update, or remove your team's custom attribute descriptions.

### Viewing your registry

<Info>
  To complete this task, you must be a [Team Owner](/configure/teams/manage-permissions/).
</Info>

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 **Telemetry Schema** tab.

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

<Info>
  To complete this task, you must be a [Team Owner](/configure/teams/manage-permissions/).
</Info>

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 **Telemetry Schema** tab.
3. Enter or paste your registry YAML into the editor.
   The YAML must follow the [OpenTelemetry Weaver format](https://github.com/open-telemetry/weaver).
   For a full list of supported fields, refer to the [Supported Fields](#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 OpenTelemetry Weaver schema before saving.
If the YAML is invalid, an error message describes what went wrong.

### Deleting your registry

<Info>
  To complete this task, you must be a [Team Owner](/configure/teams/manage-permissions/).
</Info>

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 **Telemetry Schema** tab.
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 custom telemetry schema uses the [OpenTelemetry Weaver YAML format](https://github.com/open-telemetry/weaver), 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:

```yaml theme={}
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](#supported-fields) section.

### Supported fields

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

#### Attribute fields

Each attribute supports:

| Field   | Required | Description                                                                                                |
| ------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `name`  | Yes      | The attribute name, which must exactly match the field name in your Honeycomb telemetry data.              |
| `type`  | Yes      | The attribute type: `string`, `int`, `double`, `boolean`, `string[]`, `int[]`, `double[]`, or `boolean[]`. |
| `brief` | Yes      | A short description of the attribute. This is what MCP tools surface to AI agents.                         |

#### Group fields

Each group supports:

| Field        | Required | Description                                                                   |
| ------------ | -------- | ----------------------------------------------------------------------------- |
| `id`         | Yes      | A unique identifier for the group, typically using dot-separated namespacing. |
| `type`       | Yes      | Must be `attribute_group`.                                                    |
| `brief`      | Yes      | A short description of the group.                                             |
| `note`       | No       | Additional context or usage notes for the group.                              |
| `attributes` | Yes      | The list of attributes in the group.                                          |

## Best practices

Follow these guidelines to get the most out of your custom telemetry schema.

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