> ## Documentation Index
> Fetch the complete documentation index at: https://honeydew.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Metadata

Metadata helps AI to understand the context of your business.
You can add AI-specific metadata to various semantic objects.
This metadata provides AI with additional context
to accurately answer user questions.

<Tip>
  The most important metadata for an object is its **name**.

  Always prefer descriptive names for objects
  (entities, attributes, metrics) over explanations about what they do.

  AI metadata serves to amplify the context for a semantic object
  that is not obvious from its name.
  For broader organizational knowledge — such as business definitions
  or analytical methodologies — use
  [context management](/docs/integration/context-layer/context-management)
  instead, loaded via [agents](/docs/integration/context-layer/agents).
</Tip>

## Domain

Domain metadata is the place to teach AI about
the context of your business domain as a whole.
A typical explanation might include who you are,
what you do, and limitations of your data
to ground it in your business domain.

<Tip>
  For example, "We are ACME corp., an export-import provider
  in the Northwest. This includes all our sales data
  for the last seven years for financial analysis.
  NOTE: Data is up to previous day only."
</Tip>

Domain metadata can be changed in Honeydew Studio,
or within the domain YAML structure:

```yaml theme={null}
...
metadata:
  - name: honeydew_ai
    metadata:
      - name: description
        value: This is a domain-level AI-specific context for the domain
```

## Attributes and Metrics

You can add AI-specific metadata to attributes and metrics
that specifies the AI context for these fields, including
synonyms that help AI match user terminology to the correct fields.
When an AI-specific description is not provided,
the general field description is used as a fallback.

<Tip>
  Typical hints can include:

  * Synonyms: "also known as GMV"
  * Data structure: "US state, abbreviated to two letters as NY"
  * Usage rules: "Use case-insensitive ILIKE to filter"
  * Other hints for when to prefer a field: "Key indicator for performance"
</Tip>

Field metadata can be changed in Honeydew Studio, or in YAML:

* For [metrics](/docs/calculations/metrics#yaml-schema) and
  [calculated attributes](/docs/calculations/attributes#yaml-schema),
  add it to the field's own YAML file:

```yaml theme={null}
...
metadata:
  - name: honeydew_ai
    metadata:
      - name: description
        value: This is an AI-specific description for the attribute
      - name: synonyms
        value: synonym1, synonym2
      - name: values
        value:
          - value1
          - value2
          - value3
```

* For [dataset attributes](/docs/modeling/source-data#yaml-schema), add the metadata under
  the attribute entry in the dataset's YAML file:

```yaml theme={null}
...
attributes:
  ...
  - column: <src column name>
    name: <attribute name>
    ...
    metadata:
      - name: honeydew_ai
        metadata:
          - name: description
            value: This is an AI-specific description for the attribute
```

## Entities

You can add AI-specific metadata to entities
that specifies the AI context for these entities as a whole,
including synonyms that help AI recognize alternative names.
When an AI-specific description is not provided,
the general description is used as a fallback.

<Tip>
  For example, "Only includes customers with an active subscription"
  for a `customers` entity.
</Tip>

Entity metadata can be changed in Honeydew Studio,
or within the entity YAML structure:

```yaml theme={null}
...
metadata:
  - name: honeydew_ai
    metadata:
      - name: description
        value: This is an AI-specific description for the entity
      - name: synonyms
        value: synonym1, synonym2
```