> For the complete documentation index, see [llms.txt](https://docs.toucanai.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toucanai.cloud/govern/ai-control-and-optimization/how-to/define-metric-definitions.md).

# Define metric definitions

{% hint style="info" %}
**Target Audience**: Organization admins and data teams configuring AI for their organization.
{% endhint %}

### TL;DR

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

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

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

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.

{% hint style="info" %}
**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
```

{% endhint %}

***

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

{% hint style="info" %}
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](/build/semantic-layer/how-to/complete-metadata-information.md) improves the results.
{% endhint %}

***

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

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