Tavus Tool Calling

New to tool calling? Start with the Tools overview and Tool Calling for LLM. This page focuses on best practices for building reliable tool integrations. Maintaining legacy inline tools? See Legacy inline tool calling.

How Tavus tool calls work

A tool dispatches over exactly one channel, set per tool via the delivery field - see Tool Delivery:

App message (default) - the call arrives in your frontend as a conversation.tool_call event; your app runs the logic and sends a conversation.tool_result event back.
API call (HTTP) - Tavus makes an HTTPS request to an endpoint you configure; your backend runs the logic and returns the result in the HTTP response.

What the PAL does with the result - speak it, summarize it, absorb it silently, or ignore it - is set by the tool’s on_resolve, independent of which channel delivered the call. App-message flow:

User speaks
    ↓
The LLM emits a `conversation.tool_call` event (with a tool_call_id)
    ↓ (Tavus → your frontend)
Your app executes the logic (API calls, DB queries, etc.)
    ↓ (your frontend → Tavus)
Your app sends `conversation.tool_result` with the matching tool_call_id
    ↓ (Tavus → user)
The PAL responds per the tool's on_resolve

API (HTTP) flow:

User speaks
    ↓
The LLM decides to call the tool
    ↓ (Tavus → your backend)
Tavus sends an HTTPS request to your configured URL
    ↓ (your backend → Tavus)
Your endpoint returns the result in a 2xx response body
    ↓ (Tavus → user)
The PAL responds per the tool's on_resolve

With app-message delivery, Tavus does not run the tool for you - your frontend handles conversation.tool_call events and runs your own logic. With API delivery, Tavus calls your endpoint directly, so no frontend handling is needed. Pick one per tool; see Tool Delivery.

Because Tavus agents operate in live conversational environments, tool design should prioritize reliability, clarity, and conversational continuity. Below are the six most important principles for building effective tool integrations.

1. Keep Tool Schemas Clear and Explicit

Tool definitions should be as clear and specific as possible. Ambiguous parameters make it harder for the model to choose and populate tools correctly. Prefer narrow tools with explicit parameters. Bad:

{
  "name": "lookup_customer",
  "parameters": {
    "type": "object",
    "properties": {
      "query": { "type": "string" }
    },
    "required": ["query"]
  }
}

Better:

{
  "name": "lookup_customer_by_email",
  "parameters": {
    "type": "object",
    "properties": {
      "customer_email": { "type": "string" }
    },
    "required": ["customer_email"]
  }
}

Clear schemas reduce incorrect tool usage and improve consistency.

2. Separate Read Tools from Write Tools

Tools generally fall into two categories. Read tools retrieve information and are safe to call frequently. Examples:

retrieving account data
searching knowledge bases
checking order status

Write tools modify system state. Examples:

creating support tickets
sending emails
updating records

Write tools should only run when user intent is clear and parameters are validated.

3. Keep Tool Results Small

Whatever you return - the output of a conversation.tool_result (app message) or the body of your HTTP response (API) - is injected back into the model’s context. Large payloads increase token usage and can degrade conversational quality. Return only the fields needed for the next response:

{
  "message_type": "conversation",
  "event_type": "conversation.tool_result",
  "conversation_id": "<conversation_id>",
  "properties": {
    "tool_call_id": "<id from the tool_call event>",
    "output": "Customer Jane Doe is on the Enterprise plan.",
    "status": "success"
  }
}

This keeps conversations efficient and improves response quality.

4. Avoid Triggering Tools Too Early

Tavus agents operate in real-time conversations where users may interrupt or revise their requests. If a tool executes too early, it may perform the wrong action. The LLM does not truly know intent is clear. You make “intent is clear” operational by defining concrete criteria such as:

required slots are present (for example, email, issue_type, etc.)
no unresolved ambiguity (for example, “today or tomorrow?”)
user gave explicit confirmation for write actions (for example, “yes, submit it”)

Best practice:

wait until the user’s intent is clear
avoid executing write actions mid-sentence
allow the conversation to stabilize before triggering tools

Recommended system prompt addendum (copy-paste)

Add the following policy to your PAL’s system prompt to improve tool-call quality and safety:

Tool invocation policy:
- Only call write tools when user intent is explicit and all required parameters are present.
- If any required parameter is missing, ask a follow-up question instead of calling a tool.
- If the user's wording is ambiguous, ask for clarification before calling a tool.
- For irreversible/state-changing actions (create, update, send, submit, charge, delete), require explicit user confirmation immediately before calling the tool.
- Do not call the same write tool repeatedly for the same request unless the user explicitly asks to retry.
- Read-only tools may be called without confirmation when they directly answer the user's request.
- Keep tool results small; summarize succinctly before returning them.

5. Log Tool Calls for Observability

Production systems should log tool activity so issues can be debugged easily. For app-message delivery, listen to Tavus app-events (Daily app-message events) for end-to-end observability. For API delivery, log on your backend. Either way, you can trace the full lifecycle:

when the conversation.tool_call (or HTTPS request) fired
what payload was received
what your app executed
what result you returned (the conversation.tool_result output or the HTTP response body)

At minimum, log:

conversation_id
tool_call_id
tool_name
parameters
execution result
status (success / error)
timestamp

This helps identify duplicate calls, incorrect parameters, or unexpected behavior during conversations.

6. Return Results Back to the Conversation

After executing a tool call, return the result so the LLM can use it. How you return it depends on the delivery channel; what the PAL does with it is controlled by the tool’s on_resolve.

App-message delivery

The call arrives as a conversation.tool_call event carrying a tool_call_id:

{
  "message_type": "conversation",
  "event_type": "conversation.tool_call",
  "conversation_id": "<conversation_id>",
  "properties": {
    "name": "get_current_time",
    "arguments": "{\"location\": \"New York\"}",
    "tool_call_id": "call_abc123"
  }
}

properties.arguments is a JSON string - parse it to read the parameters. Execute your logic, then send a conversation.tool_result back with the matching tool_call_id:

if (message.message_type === 'conversation' && message.event_type === 'conversation.tool_call') {
  const { name, arguments: rawArgs, tool_call_id } = message.properties;

  // Execute your tool logic
  const result = await executeTool(name, JSON.parse(rawArgs));

  // Return the result, matching the tool_call_id
  call.sendAppMessage({
    message_type: "conversation",
    event_type: "conversation.tool_result",
    conversation_id: message.conversation_id,
    properties: {
      tool_call_id,            // must match the tool_call event
      output: result,          // string passed through; object is JSON-serialized
      status: "success"        // or "error" to have the PAL acknowledge a failure
    }
  }, '*');
}

If your client never sends a result, the dispatch eventually drops out of context - the PAL just won’t have the data.

API (HTTP) delivery

Tavus calls your configured HTTPS endpoint with the tool arguments; you return the result in the response. A 2xx is treated as success and the response body becomes the tool result; non-2xx is marked error. There’s nothing to send back over the data channel - see Tool Delivery for the request/response shapes, retries, and signature verification.

Controlling What the PAL does with the result

Set the tool’s on_resolve (it applies to both channels):

You want	Set `on_resolve` to
The PAL speaks a natural-language summary of the result	`generate_response`
The PAL speaks the result text verbatim	`response_in_result`
Add the result to context silently, with nothing spoken this turn	`add_to_context`
Don’t wait for or process a result (side-effect-only tools)	`fire_and_forget`

See the on_resolve reference for full details.

Example Implementation

For a complete working example of how to implement tool calling with Tavus, see the official example repository: https://github.com/Tavus-Engineering/tavus-examples/tree/main/examples/cvi-tool-calling This example demonstrates how to:

Create tools and attach them to a PAL
Listen for conversation.tool_call events
Execute backend logic when a tool is triggered
Return results with conversation.tool_result

Getting started

Build

Deploy

Debug

Guides

Resources

Tavus Tool Calling

How Tavus tool calls work

1. Keep Tool Schemas Clear and Explicit

2. Separate Read Tools from Write Tools

3. Keep Tool Results Small

4. Avoid Triggering Tools Too Early

Recommended system prompt addendum (copy-paste)

5. Log Tool Calls for Observability

6. Return Results Back to the Conversation

App-message delivery

API (HTTP) delivery

Controlling What the PAL does with the result

Example Implementation

​How Tavus tool calls work

​1. Keep Tool Schemas Clear and Explicit

​2. Separate Read Tools from Write Tools

​3. Keep Tool Results Small

​4. Avoid Triggering Tools Too Early

​Recommended system prompt addendum (copy-paste)

​5. Log Tool Calls for Observability

​6. Return Results Back to the Conversation

​App-message delivery

​API (HTTP) delivery

​Controlling What the PAL does with the result

​Example Implementation

How Tavus tool calls work

1. Keep Tool Schemas Clear and Explicit

2. Separate Read Tools from Write Tools

3. Keep Tool Results Small

4. Avoid Triggering Tools Too Early

Recommended system prompt addendum (copy-paste)

5. Log Tool Calls for Observability

6. Return Results Back to the Conversation

App-message delivery

API (HTTP) delivery

Controlling What the PAL does with the result

Example Implementation