> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akapulu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transition Tools

> Use transition tools to move from one node to another after a tool call.

Transition tools are simple tools whose only purpose is to transition to a new node.

## Create a transition tool

### Attach via JSON

Use a function with `type: "transition"` and set `transition_to` to the destination node.

```json theme={null}
{
  "name": "<transition_tool_name>",
  "description": "<description>",
  "type": "transition",
  "transition_to": "<TARGET_NODE_NAME>"
}
```

For example:

```json theme={null}
{
  "name": "continue_to_verification",
  "description": "Use this tool after the prospect confirms their details to move to the appointment booking node",
  "type": "transition",
  "transition_to": "appointment_booking"
}
```

### Attach via UI

1. Open your scenario and go to the target node.
2. Click **Add function**.
3. Select the `Transition Tool` tab in the pop up modal
4. Enter a **name** and **description** the model will use to decide when to call this tool. Use a short, unique **name** (often `snake_case`, e.g. `continue_to_booking`) with no spaces—same idea as in JSON. The **description** should say **when** to invoke the tool (what the user said or what must be true first), not just what the tool does—for example: “After the user confirms their email, move to booking,” so the assistant does not jump nodes too early.
5. Drag the probe on the right side of the function to the node you wish to transition to.

## Require function call

For nodes that [require a function call](/guides/scenarios/node-basics#require-function-call), we recommend that the required tool **transitions the flow to another node**. If the user remains on the **same** node, every LLM turn will still invoke the required tool. That may be appropriate for tools you mean to reuse every turn (such as a RAG tool before every bot response), but may not be appropriate for other tools.

## Require reason

Set `require_reason: true` on a transition function to make the LLM pass a `reason` argument whenever it calls the tool. The reason shows up in the tool-call payload in the conversation transcript, so you can see *why* the model chose to transition.

```json theme={null}
{
  "name": "continue_to_verification",
  "description": "Use this tool after the prospect confirms their details to move to the appointment booking node",
  "type": "transition",
  "transition_to": "appointment_booking",
  "require_reason": true
}
```

We recommend enabling `require_reason` during development to make transition behavior easier to diagnose. Because the model must generate an additional `reason` field on each call, it introduces a small latency cost, so whether to keep it enabled in production is a trade-off you should make based on your application's latency requirements.

<Note>
  `require_reason` is only valid on `type: "transition"` functions.
</Note>

## Make any tool a transition tool

Any tool can also be configured to transition after it is called, including HTTP endpoints, RAG tools, and vision tools.

To do this in JSON, set `transition_to` on that tool function object.

```json theme={null}
{
  "name": "lookup_policy_and_continue",
  "description": "Search policy details, then move to verification.",
  "type": "rag",
  "knowledge_base_id": "<KNOWLEDGE_BASE_ID>",
  "transition_to": "verification"
}
```

In the UI, drag the function to the node you want to transition to after that tool is called.

## Dynamic HTTP transitions

HTTP endpoints can also use dynamic transition logic instead of a fixed `transition_to` target.

With dynamic HTTP transitions, the tool defines `allowed_next_nodes`, and Akapulu reads `next_node` from the endpoint's JSON response to decide which node to enter next.

To learn how dynamic HTTP routing works, including the `next_node` response contract and error behavior, see [Endpoints](/guides/endpoints/create-endpoint).