Glossaries

User messages inside an organization are full of vocabulary the model has no way to guess: internal acronyms, product codenames, department shorthand, ticket prefixes. When someone types "can you ping the Atlas team about the k8s rollout in PodA?" the agent needs to know that Atlas is your internal order-management product, k8s is Kubernetes, and PodA is a specific infrastructure team.

A glossary is a reusable mapping of such terms to their expanded forms. You attach a glossary to one or more agent steps and, whenever a user message contains a matching term, the agent receives a small hint block alongside the original message explaining what those terms mean. The user's text is never rewritten, so the agent still sees exactly what the user typed.

When to use a glossary

Use glossaries for vocabulary that is common inside your organization but not outside it:

• Internal acronyms and abbreviations — k8s, SLO, RCA, EOD.
• Product and project codenames — Atlas, Nebula, Project Orion.
• Team and department names — PodA, Platform Infra, CS Tier 2.
• Internal systems and tool names that share a name with something else — Bolt (the billing service, not the unrelated public product).

Avoid adding common English words, brand names the model already recognizes, or terms whose meaning changes by context. Every matched term adds a line of hint text to the prompt, so a small, curated glossary works better than a large noisy one.

Glossaries vs. instructions

Instructions shape how an agent behaves — its persona, tone, and rules. Glossaries give the agent a vocabulary lookup. Keep the two separate: instructions stay short and stable, glossaries grow as your organization's jargon grows.

Performance trade-offs

Glossaries are optimized for read speed. The indexing technique we use makes term lookup on every user turn effectively free, even when the glossary contains thousands of entries. The trade-off is that writes are slower and propagation is eventually consistent:

• Each POST or DELETE of entries rebuilds the glossary's lookup index. Bulk-load entries in as few requests as possible rather than calling the API once per entry.
• After an upsert or delete, active agent sessions may continue to see the previous version of the glossary for a short period (typically well under a minute) while caches refresh. Stage changes before the traffic that depends on them; do not rely on glossary updates landing in-flight during a live conversation.

This is a deliberate trade-off — glossaries are meant to capture vocabulary that changes on the order of days or weeks, not per-request context. For per-session context, use session metadata instead.

Create a glossary

Create a glossary with a stable key, a human-readable name, and an optional description. The glossary starts empty — entries are added in a separate step.

CREATE A GLOSSARY

Code example with multiple language options.bashjson

1

If you omit the key, one is auto-generated from the name.

Add or update entries

Entries are upserted in bulk as a map from term to expansion. Existing terms are overwritten, new terms are inserted. You can send up to 1,000 entries per request.

UPSERT ENTRIES

Code example with multiple language options.bashjson

1

Deletes work the same way — send a list of terms to remove:

DELETE ENTRIES

Code example with multiple language options.bashjson

1

Both upsert and delete trigger an asynchronous index rebuild. The API returns as soon as the write is durable; the new view becomes visible to agents shortly after.

Attach a glossary to an agent step

Glossary expansion is opt-in per step. To use a glossary, add a glossary_expansion reminder to the step's reminders array and point it at the glossary's key.

AGENT STEP USING A GLOSSARY

Code example with json syntax.json

1

Because this attachment is per-step, different steps in the same agent can use different glossaries (or none at all). A step without a glossary_expansion reminder receives no glossary hints, even if the agent has other steps that do.

What the agent actually sees

The user's original text is preserved. Before the message reaches the LLM, a small hint block is appended listing each matched term and its expansion. For example, given the glossary above, a user message:

Can you ping the Atlas team about the k8s rollout in PodA?

reaches the LLM as:

Can you ping the Atlas team about the k8s rollout in PodA?
<glossary hint="possible meanings">
Atlas: our internal order management system
k8s: Kubernetes
PodA: the infrastructure platform team that owns the ingest pipeline
</glossary>

The agent treats this as a hint, not a command — it may still ask the user to clarify if the context is ambiguous. Terms that appear multiple times in the message are listed once. Terms that do not appear are not listed.

Matching behavior

• Case-insensitive. An entry with term k8s matches k8s, K8s, and K8S.
• Whole-word matching. env does not match inside environment. Multi-word terms match whole phrases with the same whole-word rule at each end.
• Multi-word terms are supported. An entry with term order desk matches the phrase order desk in user input, but does not match order or desk on its own.
• Deduplicated per message. If the same term appears multiple times in one message, it is listed once in the hint block.

Limits

Field	Limit
Glossary key	1–50 characters, [a-zA-Z0-9_=\-]
Glossary name	1–100 characters
Glossary description	up to 500 characters
Term	1–200 characters
Expansion	1–1000 characters
Entries per upsert or delete	1–1000

Next steps

• Browse the full Glossaries API reference for every endpoint, parameter, and response shape.
• Learn how instructions and session metadata work alongside glossaries to give your agent the full context it needs.