# Define metric definitions (/core/govern/ai-control-and-optimization/how-to/define-metric-definitions)



<CalloutContainer type="info">
  <CalloutDescription>
    **Target Audience**: Organization admins and data teams configuring AI for their organization.
  </CalloutDescription>
</CalloutContainer>

### TL;DR [#tldr]

Metric definitions tell the assistant exactly what your key business metrics mean and where they come from. When defined, the assistant uses these definitions whenever a user asks about those metrics — ensuring every user gets the same, accurate answer.

***

### When to use this [#when-to-use-this]

Use this page when users ask about key metrics and get inconsistent or incorrect answers. Defining metrics is especially useful for calculated values that are not self-evident from column names, such as ARR, churn rate, or NPS.

***

### Who can change this [#who-can-change-this]

Changing metric definitions requires the **organization update** permission, which **member**, **admin**, and **owner** roles have. Users with the **explorer** role cannot change it.

This setting is available on plans that include AI customization. If the section is locked, contact your account manager.

***

### How to define metrics [#how-to-define-metrics]

1. Open **Settings** and select **AI behavior** in the left sidebar.
2. In the **Metric definitions** card, enter your metrics in the text field — one metric per line.
3. Click **Save**. A confirmation ("Context updated") appears once the change is applied.

<CalloutContainer type="info">
  <CalloutDescription>
    **Format**

    Each line should define one metric. Include the name, the formula or logic, and the source table or column when relevant.

    **Examples**

    ```
    ARR (Annual Recurring Revenue) = Sum of all active subscription values, annualized. Table: billing.subscriptions
    Churn Rate = Customers lost ÷ Customers at start of period × 100. Table: analytics.customer_events
    NPS = % Promoters − % Detractors. Table: surveys.responses, column: score
    ```
  </CalloutDescription>
</CalloutContainer>

***

### Improve with AI [#improve-with-ai]

The **Improve with AI** button generates metric definition suggestions by scanning your connected database schemas and metadata. Click it to open a preview of the suggested metrics. Review them, then click **Accept** to fill the field, and **Save** to keep them.

<CalloutContainer type="info">
  <CalloutDescription>
    If the suggestion comes back empty, it means the assistant could not derive metrics from the available metadata. Adding table descriptions and column descriptions in the [Semantic Layer](/core/build/semantic-layer/how-to/complete-metadata-information) improves the results.
  </CalloutDescription>
</CalloutContainer>

***

### Good to know [#good-to-know]

* **Character limit**: metric definitions are capped at 10,000 characters.
* **One metric per line**: the assistant parses each line as a separate definition. Blank lines are ignored.
* **Scope**: definitions apply organization-wide to every AI interaction.

***

### Related pages [#related-pages]

* [Set AI instructions](/core/govern/ai-control-and-optimization/how-to/set-ai-instructions)
* [Set company context](/core/govern/ai-control-and-optimization/how-to/set-company-context)
* [Complete metadata information](/core/build/semantic-layer/how-to/complete-metadata-information)