Glossary

Overview

Glossary lets you teach your AI Agent your business’s vocabulary. When an end user uses one of your defined terms, the AI Agent is guided to use your preferred wording — both in its reply and when it looks up available entities like Playbooks and Knowledge articles. It works across every language you support, and just as well within a single language (for example, guiding the AI Agent to respond with “top up” when an end user says “add money”).

You can also attach a plain-language definition to a term to give the AI Agent business context — helping it disambiguate terms, understand internal naming, and respond accurately.

How it works

Glossary is a listen-and-respond system today:

• Trigger-based, per turn: it only acts when an end user’s message contains a User term you’ve defined. If an end user doesn’t use one of your terms, the glossary does nothing that turn.
• One direction: the AI Agent listens for what your end users say (the User term). It does not listen for your AI Agent term.
• Two effects: when a term matches, the AI Agent is guided to use your wording both in its reply and in what it looks up — Playbooks, Knowledge articles, and other entities — including content written in another language.
• Playbooks output: when a Playbook sends an AI-generated (“dynamic”) message to the end user, that output is shaped by the glossary too. Scripted or quoted Playbook content is not, and Playbooks (Classic) output isn’t eligible — see When not to use Glossary.
• Definitions add context: if a matched term has a definition, that business context is given to the AI Agent to shape its reply and its lookups, and to distinguish between terms that could mean more than one thing.
• A strong nudge, not a hard override: the AI Agent is guided toward your wording but still chooses the final phrasing naturally (the reply might not require your term to be used).

Use cases

Glossary helps in a few common situations:

• Preferred wording: map what end users say to the wording you want back — across languages (e.g. an end user’s “add money” or “alimentation” maps to “top up” and “rechargement” respectively).
• Brand and product names: keep names consistent and untranslated. The most valuable use is normalizing casual or non-official wording back to the official term (for example, “basic plan” → “classic plan”).
• Multilingual recognition and retrieval: capture the different ways end users say a term across languages, all mapped to your wording.
• Business definitions: attach a definition to give the AI Agent context it can’t get from wording alone —
  • Disambiguation: clarify a term that has more than one meaning (for example, “credit” as referral credit versus a gift card).
  • Private or transitional context: supply context that doesn’t belong in public content, such as an old brand name still used by end users following a rebrand.
  • Correcting a misleading framing: override a term whose common meaning conflicts with how your business uses it (for example, a “Family Plan” that has no child-specific benefits).
• Voice accuracy: flag important terms so speech-to-text is more likely to recognize them in Voice conversations.

Capabilities & configuration

• Two translation modes:

  • Custom — you define the User term (what end users say) and the AI Agent response term (what the AI Agent replies with) per language.
  • Default — the AI Agent keeps its native translation of the term; use it to attach a business definition and/or flag the term for voice detection. A Default term must have a definition or voice detection enabled.

• Definitions: attach a short, plain-language definition (up to 1,000 characters) to a term in either mode. The AI Agent treats it as the authoritative meaning of the term, using it to shape replies and lookups and to disambiguate. Definitions are context, not commands.

  Examples:

  • Rename — reassure the end user that an old and new name are the same thing: “The Family Plan was previously sold as the ‘Group plan’ and was renamed in 2025. It is the same plan. When a customer refers to the ‘group plan,’ confirm it is now called the Family Plan so they know they’re in the right place.”
  • Disambiguation — one word with more than one meaning; the definition tells the AI Agent how to choose: “‘Credit’ has two meanings: (1) referral credit — earned by referring friends, applied automatically to the next invoice, no code or action needed; (2) gift card / store credit — redeemed by entering a code at abc.ca/redeem. If the customer mentions a code or gift card, treat as gift card; otherwise default to referral credit and briefly note both.”

• Per-language terms: how you add languages depends on where you enter the term. In the dashboard, you add one row per language (a User term and an AI Agent look-up/response term for each). In a bulk CSV, a single row holds the whole term across languages — one user_term:<lang> / ai_agent_term:<lang> value per language, with as many language columns as you need (see the template).

• Voice detection: turn on per term to improve speech-to-text accuracy in Voice conversations. Available on any term regardless of translation mode. Up to 30 terms per AI Agent can have voice detection on.

• Voice vocabulary in Glossary: voice key terms are managed here in Glossary. The AI Agent’s former Vocabulary tab no longer lists terms — it links to the Glossary tab, where you manage them with the Voice detection setting.

• Manage with MCP: list, create, and update glossary terms through Ada’s MCP server, and run a guided conflict audit against the rest of your configuration (see Manage and audit with MCP).

• Import and export (CSV): bulk-create or update terms by importing a CSV, and export your full glossary to CSV from the three vertical dots menu beside the Import button.

• Delete all: clear every term at once from that same three vertical dots menu — useful for starting over from a fresh import.

• Search, filter, and sort: search by Term ID (aka “external_id” from the CSV), User terms, AI Agent terms, and definitions; filter by language; and sort by when they were last edited and Term ID.

• Limits: up to 5,000 terms per AI Agent (across all channels); Term IDs and terms up to 100 characters; definitions up to 1,000 characters; CSV uploads up to 4 MB; voice detection on up to 30 terms.

Preferred wording, definitions, or both

Glossary has two levers, and they don’t compete. Preferred wording changes the word the AI Agent uses and searches with (a Custom term’s user_term → ai_agent_term). A definition changes what the AI Agent understands a term to mean. Which one to reach for depends on what’s wrong:

• Preferred wording alone — the word is off, but the meaning is clear. Use it for translations, brand and product preservation, or normalizing a casual or outdated name to the official one.
• A definition alone — the word is fine, but the AI Agent is missing context. Use it for a term with more than one meaning (for example, “credit” could refer to store credit and gift card ‘credit’), or a term whose public description could steer the Agent the wrong way.
• Both together — the word is off and context is needed. For a rebrand, map the old name to the current one to fix the word, and add a definition such as “renamed last year, same plan” so the AI Agent acknowledges the rename instead of silently swapping the word.

Implementation & usage

Create a term

To create a term:

1. Go to Config > AI Agent > Glossary, then click New term.
2. Enter a Term ID — a unique identifier (letters, numbers, hyphens, and underscores; no spaces). Use it to update or remove the term later.
3. Choose a translation mode:
   • Custom — to map what end users say to your preferred wording.
   • Default — to keep the AI Agent’s native translation and add a business definition and/or voice detection.
4. (Optional) Turn on Voice detection enabled to improve speech-to-text accuracy for this term in Voice conversations.
5. (Optional for Custom, required for Default unless voice detection is on) Add a definition — a short, plain-language description of what the term means in your business.
6. For a Custom term, add a language row and enter the User term (a word or phrase end users use) and the AI Agent response term (the wording the AI Agent should reply with). Each row needs at least one of the two fields, and across all your languages you must provide at least one User term and at least one AI Agent response term (rows can be asymmetric — for example, a User term in one language and the response term in another). Click Add language to map the term in more languages.
7. Click Create.

Import terms from a CSV

Import treats your CSV as the single source of truth for the glossary: it replaces the current glossary with exactly the rows in your file. Each row is matched to an existing term by Term ID — a matching ID updates that term, a new ID creates one, and any term that isn’t in the CSV is deleted. After a successful import, the dashboard confirms the result (for example, “12 terms imported, 3 deleted”).

To import terms:

1. On the Glossary page, click Import and choose your CSV file.
2. The file is validated on upload. Validation is all-or-nothing: if any row has an error, the whole file is rejected and nothing is imported (your existing glossary is left unchanged).
3. The dashboard lists the rows to fix, with row numbers. For long lists, download the error log, correct the rows, and import the file again.

Your CSV uses these columns: external_id, translation_mode (custom or default), user_term:<language> and ai_agent_term:<language> (for example, user_term:en, ai_agent_term:fr), definition, and voice_detection_enabled. Any columns that aren’t recognized are ignored on import.

Start from the template, which includes example custom rows you can replace:

Download the CSV template

Export your glossary

On the Glossary page, open the three vertical dots menu beside the Import button (top right) and click Export to download your full glossary as a CSV file.

Edit or delete a term

On the Glossary page, find the term — search by Term ID, User term, AI Agent term, or definition, or filter for specific column values. Click the row (or use its three vertical dots row menu) to edit it, or choose Delete from that row menu to remove it.

Delete all terms

To clear the entire glossary at once, open the three vertical dots menu at the top beside the Import button and choose Delete all terms, then confirm. This removes every term and can’t be undone, so export a backup first if you might need it.

Manage and audit with MCP

You can manage the glossary through Ada’s MCP server as part of your end-to-end agentic improvement loop, letting connected tools and AI assistants review and maintain terms:

• List terms: list_glossary_terms returns your terms — including their translation mode, user and AI Agent terms, definition, and voice detection setting.
• Create and update terms: propose_change supports the glossary_term entity to create a new term or update an existing one.
• Audit for conflicts: get_glossary_conflict_guide returns a step-by-step recipe for cross-referencing the glossary against the rest of your configuration — custom instructions, company description, coaching, and knowledge — to surface terms that contradict, duplicate, or undermine each other. It covers definitions as well as term wording. This is a guided audit the assistant runs on demand, not automatic detection.

Best practices

• Start small. Add a term only when you can point to a real before/after it fixes. Every term is something to maintain.
• Source terms from real transcripts, not a hypothetical word list — end-user wording rarely matches internal wording.
• Update when issues arise, rather than on a fixed schedule.
• Prove each definition with a real before/after. Reproduce the weak answer first, add a one-sentence definition, then re-test — if the answer isn’t clearly better, refine or remove it.

When not to use Glossary

• Output-only regardless of what the end user says (aka “trigger-based”) — the glossary only acts on terms the end user actually uses today. Use Coaching, Custom Instructions or Knowledge content for that.
• “Do not say” rules — you can’t map a term to nothing to suppress it. Use custom instructions, Coaching, or “Don’t talk about competitors” (in AI Agent Settings).
• Automatic translation — the glossary guides wording using the translations you provide; it doesn’t generate them.
• Scripted content — greetings, handoffs, processes, and List Option blocks aren’t affected. In general, any script text output you’re providing won’t have access to the glossary when translated, as these are still processed via Google Translate. To preserve wording there (for greetings and handoffs only), use manual translations. (Dynamic, AI-generated Playbook messages are covered — see How it works. Playbooks (Classic) output is not eligible.)

Glossary, Coaching, and Custom Instructions

Glossary is one of a few tools that shape how the AI Agent responds, and it’s easy to confuse them. Each changes something different:

The key distinction: a glossary term — including its definition — describes what a word means; it never tells the AI Agent what to do. A rule like “if a customer mentions a refund, always escalate” is behavior, not meaning — put it in coaching or custom instructions. Definitions ignore embedded behavioral instructions by design.

As your configuration grows, the same terminology can end up defined in more than one place and drift apart. Use the MCP conflict audit periodically to surface terms that clash with your coaching, custom instructions, company description, or knowledge before they reach a live conversation.

Frequently asked questions