How the Agent Sees a Transition

Under the hood, every transition is exposed to the LLM as a callable function with three parts:

• A name (internal, the agent does not reason about it).
• A description that explains when the tool should be used.
• A destination — which state the conversation moves to when it fires.

After every caller turn, the agent compares what the caller said to the descriptions of the transitions available in the current state, and fires the best match. If no match is clear, it stays in the current state and keeps talking.

What Makes a Good Description

Think of the description as a one-sentence instruction to a new hire. "Do X when the caller Y."

• Name the trigger in caller terms. What would the caller actually say? Use their language, not yours. "Caller asks to book an appointment" beats "Initiate scheduling workflow."
• Be specific. "Collect contact info" is too broad. "Collect the caller's name and email when they show interest in pricing, a demo, or speaking with sales" is better.
• Include the boundary. If two transitions could fire on similar input, add a qualifier. For example, a "Reschedule" transition should say "when the caller wants to change an existing appointment," not just "when the caller mentions rescheduling."

Good and Bad Examples

Bad: "Transfer call."
Good: "Transfer the caller to a live representative when they explicitly ask to speak with a person or when the AI cannot answer their question."

Bad: "Collect info."
Good: "Gather the caller's name, company, and callback number when they ask for pricing, a quote, or want a sales follow-up."

Bad: "Go to scheduling."
Good: "Move to scheduling when the caller wants to book a new appointment. Do not use this for rescheduling or cancellations."

The AI Suggest Button

If you are not sure where to start, click AI Suggest on a transition. The agent builder drafts a description based on the transition name, the source state, and the destination state. Review the draft, tighten it with your business vocabulary, and save. It is faster than a blank page, but the final wording should always be yours.

Debugging Bad Transitions

When the agent fires the wrong transition on a test call:

1. Look at what the caller said that triggered it.
2. Open the description of the transition that fired. Does it actually cover that phrasing?
3. Open the description of the transition that should have fired. Is the trigger clear enough?
4. Tighten the wrong one ("do not fire when the caller mentions X"), loosen the right one, and retest.

Most routing bugs are description bugs, not model bugs.