Transition Descriptions as Tools

Transition Descriptions as Tools

Transitions are the arrows between states in your flow. To the AI Agent, each transition looks like a tool it can call. The description you write on a transition is what the agent reads to decide whether to fire it. A good description is the difference between an agent that routes correctly every time and one that guesses.

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" will work better than "Initiate scheduling workflow."
  • Be specific. "Collect contact info" is too broad and leaves room for error. "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

 An example might be, when a caller asks to speak with sales, the agent might transition from "Greeting" to "Collecting Info.".

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, select '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.


The transition description is a prompt the agent reads every turn. Treat it like one. Short, concrete, and unambiguous beats clever every time. 

Debugging Bad Transitions

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

  1. Look at what the caller said that triggered it by checking the call details in the Call History and toggling on the System Events.
  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.


Still have questions? Submit a ticket and we will help you get your transitions firing the right way.

    • Related Articles

    • Connecting External Tools with MCP Servers

      Your AI Agent can reach beyond its built-in tools to talk to your CRM, your booking system, your inventory service, or any other system that exposes a standard interface. The mechanism is MCP — the Model Context Protocol — an open standard for ...

    • State Type: Error Handling

      The Error Handling state is the recovery branch of your flow — where the agent goes when something did not go as expected. A caller spoke a language the agent does not understand, a tool returned an error, a required field was not captured, an ...

    • OneCloud Professional Contact Center - Analytics Descriptions Reference Guide

      Table Settings Options and Descriptions Reference Guide Queue Stats Table Settings Options and Descriptions Call Handling Metrics Call Volume (VOL): Total number of calls originating through a call queue, including answered, abandoned, forwarded, and ...

    • Building Conversation Flows

      A flow is the conversation blueprint for your AI Agent. It defines the stages of a phone call, what the agent does at each stage, which tools it can use, and when the conversation moves forward. Think of it like a flowchart: each box is a stage the ...

    • State Type: Assisting

      The Assisting state is the agent's general-purpose "stay and help" state. It is the default conversational state — broad in scope, liberal with tools, and the place most calls spend the majority of their time. What It Does Assisting is what it sounds ...