The Supervisor and Tool Caller system

The Supervisor and Tool Caller is the execution layer that detects when the ConvoAgent commits to an action and triggers the corresponding backend operation. After each conversational turn, the system analyzes the agent's latest response against a set of available tools, determines which tools need to be called, resolves conflicts between competing tools, and executes the required actions. This article is the definitive developer reference for the Tool Caller's architecture, condition detection logic, conflict resolution, and execution pipeline.

Architecture overview

The CANewoToolCaller flow runs after each conversational turn, triggered by the same broadcast_analyze_conversation event that activates the Observer. While the Observer generates thoughts about what to do next, the Tool Caller detects what the agent has already committed to and makes it happen.

ConvoAgent generates response: "I'll send you an SMS with the details"
    │
    ▼
broadcast_analyze_conversation event
    │
    ├──► CAObserverFlow (thoughts generation)
    ├──► CAThoughtsFlow (directive generation)
    │
    └──► CANewoToolCaller
            ├── compile_tools_object (merge NAF + custom tools)
            ├── get_tools_to_call (condition analysis via LLM)
            ├── rerank_conflict (resolve competing tools)
            └── handle_*_action (execute tools)

The flow contains 21 skills organized into four categories: tool compilation, condition detection, conflict resolution, and action execution.

AnalyzeConversation orchestrator

The AnalyzeConversation skill is the entry point and orchestrator for the entire Tool Caller flow. It runs the following sequence:

1. Compile tools — Calls compile_tools_object to merge NAF and custom tools.
2. Group tools — Separates tools into two groups: those that need full conversation history and those that only need the latest agent answer.
3. Evaluate tools without history — Calls get_tools_to_call with only <LatestConvoAgentAnswer>, passing tools that have useConversationHistory: false.
4. Evaluate tools with history — Calls get_tools_to_call with the full <Conversation> block, passing tools that have useConversationHistory: true.
5. Identify conflicts — Groups selected tools by their conflictPolicy.tag.
6. Resolve conflicts — For each tag group with multiple candidates, calls rerank_conflict to select the winner.
7. Execute tools — Runs the action handler for each selected tool.
8. Update follow-up timer — Adjusts the follow-up delay based on channel (voice channels get shorter delays than chat).
9. Set conversation state — Marks that tools were called during this turn.

::: 🗒️ NOTE The webcall channel is mapped to phone for tool evaluation purposes. The skill normalizes webcall → phone at the start of execution so that phone-only tools (like transfer_call_tool) are available on web call sessions too. :::

Tool compilation

At runtime, the system assembles the complete set of available tools by merging built-in NAF tools with any custom tools defined by the customer.

compile_tools_object

The skill reads NAF-defined tools and merges any custom tools defined in project_attributes_settings_newo_tools into a single tools object that the condition detection step operates on.

Each tool definition follows a standard schema:

{
  "tool_name": {
    "description": "What this tool does",
    "conditions": {
      "condition_name": {
        "type": "boolean",
        "description": "When this condition is true"
      }
    },
    "useConversationHistory": true,
    "conflictPolicy": {
      "tag": "conflict_group_tag"
    },
    "action": {
      "type": "send_event",
      "options": {}
    },
    "after_actions": []
  }
}

Tool activation attributes

Each built-in tool is gated by a boolean project attribute:

The end_conversation_tool is always available regardless of attribute settings.

Condition detection

The get_tools_to_call skill is the analytical core. It uses an LLM to evaluate the agent's latest response against each tool's conditions, applying strict rules to prevent false positives.

Analysis prompt structure

The skill formats each tool into a markdown description and passes it with the conversation context.

Critical exclusion rules

The condition detection enforces five rules to prevent false tool activations:

Conflict resolution

When multiple tools share the same conflictPolicy.tag, they are mutually exclusive — only one can execute per turn. The rerank_conflict skill resolves this.

Conflict resolution flow

The AnalyzeConversation orchestrator handles conflicts as follows:

For each tool selected by get_tools_to_call:
    If tool has conflictPolicy.tag AND other selected tools share that tag:
        Add to rerank_candidates[tag]
    Else:
        Execute immediately

For each conflict group in rerank_candidates:
    If only 1 candidate: execute it
    Else: call rerank_conflict → LLM selects the most relevant tool

Conflict tags

The rerank_conflict skill uses the same prompt structure as get_tools_to_call but asks the LLM to rank and select the single most relevant tool from the competing set.

Tool execution pipeline

Once tools are selected and conflicts resolved, the AnalyzeConversation orchestrator groups tools by conversation history requirement, executes them, and processes post-execution actions.

Execution grouping

Tools are split into two groups for efficiency:

1. Tools without conversation history (useConversationHistory: false) — Evaluated first, using only the latest agent answer.
2. Tools with conversation history (useConversationHistory: true) — Evaluated second, with the full conversation context.

Action handlers

Each tool's action.type routes to a specific handler:

send_event handler

The most common handler — fires a system event that triggers the corresponding execution flow:

send_webhook handler

Used for custom tools that call external APIs:

Custom tool registration

Custom tools are defined in the project_attributes_settings_newo_tools customer attribute as a JSON object:

{
  "tools": {
    "my_custom_tool": {
      "description": "What this tool does",
      "conditions": {
        "agentPromised": {
          "type": "boolean",
          "description": "The agent explicitly states they will perform this action"
        }
      },
      "useConversationHistory": false,
      "action": {
        "type": "send_webhook",
        "options": {
          "url": "https://api.example.com/action",
          "method": "POST",
          "body": {
            "type": "object",
            "properties": {
              "customer_name": {
                "type": "string",
                "description": "The customer's full name"
              }
            }
          }
        }
      },
      "after_actions": [
        {
          "type": "send_urgent_message",
          "options": {
            "prefix": "Action result"
          }
        }
      ]
    }
  }
}

Custom tools are merged with NAF tools at runtime by compile_tools_object and go through the same condition detection, conflict resolution, and execution pipeline.

End-to-end example

Here is a complete walkthrough of what happens when the ConvoAgent says "I'll send you an SMS with the reservation details":

1. Event fires: broadcast_analyze_conversation triggers the CANewoToolCaller flow.

2. Tool compilation: compile_tools_object merges NAF tools (including send_sms_tool since project_attributes_setting_sms_send_information_enabled is "True") with any custom tools.

3. Tools grouped: send_sms_tool has useConversationHistory: false, so it goes in the first evaluation group.

4. Condition detection: get_tools_to_call analyzes the latest agent answer:

   • Subject check: "I" (Agent) is the subject — passes.
   • Tense check: "I'll send" — present commitment, not past or future step — passes.
   • Keyword check: "SMS" appears in the answer — passes.
   • agentPromised condition: met.
   • notRelatedToExistingBooking condition: met (not about managing an existing booking).
   • Result: send_sms_tool selected.

5. Conflict check: send_sms_tool has conflictPolicy.tag: "sms". No other SMS-tagged tool was selected, so no conflict resolution needed.

6. Execution: handle_send_event_action fires:

   SendSystemEvent(eventIdn="send_sms_tool", connectorIdn="system", ...)

7. SMS delivery: The CAActionSendSMSInformationFlow receives the event and processes the SMS delivery through the SmsWorker agent.

Changelog

The Supervisor and Tool Caller system: initial publication

Published developer reference covering the Tool Caller's runtime tool compilation, condition detection with exclusion rules, conflict resolution via reranking, action execution pipeline (send_event, send_webhook, send_urgent_message), custom tool registration, and end-to-end execution walkthrough.