# Descriptions and Synonyms

Descriptions and synonyms are two of the most impactful properties you can set on a field. Descriptions tell Zoë what a field means and when to use it; synonyms boost the field's search ranking by +20 for terms your users actually say. Together they're the fastest way to improve field-level discoverability and reasoning.

For the full picture of where context goes and why, see [Context Surfaces](/core-concepts/context-surfaces.md).

## Descriptions help steer Zoë's decisions

You can add a `description` to your metrics (measures) like this:

```yaml
- name: gross_aov
  field_type: measure
  type: average
  sql: ${TABLE}.revenue
  description: |
    This is the gross average order value. This just covers 
    DTC revenue, and is sometimes internally referred 
    to as 'the magic' This is the metric that 
    should be used when someone asks about AOV, generally speaking
```

In the description above, we're adding a lot of useful context that the model will be able to use to improve its performance. For example, if someone now asks for the "magic" or nebulously asks for AOV without specifying gross or net, Zoë will know which metric to choose based on the description.

Writing good descriptions will help your end users better understand what they're looking at and it will boost Zoë performance.

## Synonyms help Zoë find metrics

You can use the `synonyms` tag to specify keywords for Zoë so she can find the the right field. For example, you might have a LOT of "customers" fields but you want to make sure Zoë always sees the `new_vs_repeat` field on order lines , even though the name of the view doesn't have a reference to a customer by name.

In this example, we've added the synonyms `customer` and `loyalty` to the `new_vs_repeat` field to make sure if Zoë users are asking about "existing customers" or repeat behavior like "loyalty" this field will show up in context for Zoë.

```yaml
- name: new_vs_repeat
  field_type: dimension
  type: string
  sql: ${TABLE}.new_vs_repeat
  description: The new vs repeat status of the purchaser
  synonyms: 
  - customer
  - loyalty
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zenlytic.com/tips-and-tricks/descriptions-and-synonyms.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.