Tool Calling for LLM

LLM tool calling lets the PAL trigger functions based on what the user says during a conversation. Tools are reusable objects: create them once, and attach them to any number of PALs. They dispatch via the channel you pick on the delivery field - see Tool Delivery and Tool Authentication.

This page documents the tools registry (/v2/tools). If your PAL still defines tools inline under layers.llm.tools, see Legacy inline tool calling.

Tool Object

Top-Level Fields

Field	Type	Required	Description
`name`	string	✅	A unique identifier for the tool, scoped to your account. Must match OpenAI function naming rules (`^[a-zA-Z_][a-zA-Z0-9_]{0,63}$`).
`description`	string	✅	Natural language explanation of what the tool does. Used by the model to decide when to call it.
`parameters`	object	❌	JSON Schema object describing the tool’s input arguments. Defaults to `{}` (no arguments).
`origin`	string	❌	One of `llm`, `vision`, `screen`, `audio`. Defaults to `llm`. This page covers `llm`; see Tool Calling for Perception for `vision` / `screen` / `audio`.
`on_call`	string	❌	what the PAL does while the tool is running. See `on_call` reference. Defaults to `generate_filler` for `llm` tools; must be omitted for `vision` / `screen` / `audio` tools.
`on_resolve`	string	❌	what the PAL does after the tool returns a result. See `on_resolve` reference. Defaults to `fire_and_forget`.
`static_filler`	string	❌	The exact line the PAL speaks while the tool runs when `on_call` is `static_filler`. Required in that case.
`delivery`	object	❌	How the tool call is delivered. See Tool Delivery. Defaults to `{"app_message": true}`.

`parameters`

Standard JSON Schema. Same shape as the OpenAI function.parameters object.

Field	Type	Required	Description
`type`	string	✅	Always `"object"`.
`properties`	object	✅	Map of parameter name to its schema (`type`, `description`, `enum`, etc.).
`required`	array of strings	❌	Names of mandatory parameters.

Examples

No arguments
Single required argument
Enum + optional argument

parameters

{
  "type": "object",
  "properties": {}
}

parameters

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "The city to get the weather for, e.g. San Francisco"
    }
  },
  "required": ["city"]
}

parameters

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "The city to get the weather for"
    },
    "unit": {
      "type": "string",
      "enum": ["celsius", "fahrenheit"],
      "description": "Temperature unit"
    }
  },
  "required": ["city"]
}

`on_call` reference

on_call controls what the PAL does while a tool is dispatched but has not yet returned. Defaults to generate_filler for llm tools; set it explicitly if you want a different behavior.

Value	Behavior
`generate_filler`	The LLM produces a short filler line itself (a `response_to_user` argument is injected into the tool’s schema). the PAL speaks it via TTS.
`static_filler`	The PAL speaks the configured `static_filler` string at dispatch time. The top-level `static_filler` field is required.
`silent`	The face stays silent while the tool runs.
`passthrough`	The tool spec is untouched. You manage the prompt and the schema. Use this when the LLM is already configured to preamble (i.e. the model naturally speaks a short line on its own before invoking a tool).

Examples

generate_filler
static_filler
silent
passthrough

{
  "on_call": "generate_filler"
}

The LLM picks the filler line per-call (e.g. “Let me check that for you.”).

{
  "on_call": "static_filler",
  "static_filler": "One moment - checking the weather now."
}

The PAL speaks the exact static_filler string every time the tool fires.

{
  "on_call": "silent"
}

The face says nothing while the tool runs.

{
  "on_call": "passthrough"
}

The tool spec is untouched. Use when your LLM is already configured to preamble before tool calls.

`on_resolve` reference

on_resolve controls what the PAL does with the tool’s result once it returns.

Value	Behavior
`generate_response`	The LLM regenerates a contextual reply using the tool’s result. Most common choice; The PAL speaks a natural-language summary of the result.
`response_in_result`	The tool’s response body is spoken verbatim via TTS - return `Content-Type: text/plain` with a single natural-language string. Use when the tool already returns a fully-formed natural-language reply. On timeout, non-2xx, or transport error, the tool call falls back to `generate_response` so the PAL still acknowledges the user.
`add_to_context`	The result lands silently in the conversation history as a system message. Nothing is spoken on the result-landing turn; the next user utterance’s LLM call sees it.
`fire_and_forget`	The result is not awaited or processed. Used when the tool’s side effect is what matters (e.g. logging a CRM event). The default when `on_resolve` is omitted.

Seeing “Do not call this tool again” in the transcript? While Tavus waits for a tool result, the PAL may see a placeholder message with this text. It only means “don’t send the same request again while this call is still running.” The PAL can still use the tool later in the conversation.With add_to_context, the result arrives as a new message instead of replacing the placeholder, so you may see both in the transcript. This text can’t be changed with a setting. If your integration only needs the tool to perform an action and the PAL doesn’t need the result, consider fire_and_forget.

Examples

generate_response
response_in_result
add_to_context
fire_and_forget

{
  "on_resolve": "generate_response"
}

The LLM regenerates a contextual reply using the tool’s result. Most common choice.

{
  "on_resolve": "response_in_result"
}

The tool’s response body is spoken verbatim via TTS. Return Content-Type: text/plain with a natural-language string.

{
  "on_resolve": "add_to_context"
}

The result lands silently in conversation history; the next user turn’s LLM call sees it.

{
  "on_resolve": "fire_and_forget"
}

The result is not awaited or processed. Use for side-effect-only tools (e.g. logging a CRM event).

Creating a Tool

Create tool

curl --request POST \
  --url https://tavusapi.com/v2/tools \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "get_current_weather",
    "description": "Get the current weather for a city.",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "The city to get the weather for, e.g. San Francisco"
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"]
        }
      },
      "required": ["city"]
    },
    "origin": "llm",
    "on_call": "generate_filler",
    "on_resolve": "generate_response",
    "delivery": {
      "api": {
        "url": "https://api.example.com/tools/get_weather",
        "method": "POST",
        "auth": { "type": "hmac", "secret": "whsec_long_random_string" },
        "timeout": 20
      }
    }
  }'

A successful create returns the full tool object including its tool_id:

Response

{
  "tool_id": "tabc123def456",
  "owner_id": 12345,
  "name": "get_current_weather",
  "description": "Get the current weather for a city.",
  "parameters": { "...": "..." },
  "delivery": { "api": { "...": "..." } },
  "is_system_tool": false,
  "origin": "llm",
  "on_call": "generate_filler",
  "on_resolve": "generate_response",
  "static_filler": null,
  "created_at": "2026-05-20 14:22:01.123456",
  "updated_at": "2026-05-20 14:22:01.123456"
}

The tool_id (prefix t…) is how you reference the tool when attaching it to a PAL or updating / deleting it.

Attaching Tools to a PAL

A PAL only sees a tool if it is attached. Attach one or more tools in a single call:

Attach tools to PAL

curl --request POST \
  --url https://tavusapi.com/v2/pals/{pal_id}/tools \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "tool_ids": ["tabc123def456", "tdef456abc789"]
  }'

List the tools currently attached to a PAL:

List PAL tools

curl --request GET \
  --url https://tavusapi.com/v2/pals/{pal_id}/tools \
  --header 'x-api-key: <api-key>'

Detach a single tool from a PAL:

Detach tool from PAL

curl --request DELETE \
  --url https://tavusapi.com/v2/pals/{pal_id}/tools/{tool_id} \
  --header 'x-api-key: <api-key>'

Detaching removes the link between the PAL and the tool. The tool itself is untouched and still attached to any other PALs that use it.

End-to-End Example

Create the tool at /v2/tools (see above). Save the returned tool_id.
Attach it to a PAL at /v2/pals/{pal_id}/tools.
Start a conversation with that PAL. The tool is now available to the face.
Handle the tool call in your application:
- If delivery.app_message: true, listen for conversation.tool_call events in your frontend.
- If delivery.api is set, your endpoint receives the call. See Tool Delivery.
Return a result (only meaningful when on_resolve is not fire_and_forget):
- App message delivery: send a conversation.tool_result event with the matching tool_call_id. See Tool Delivery.
- API delivery: return a 2xx response with the result in the response body.

Errors

Status	When
`400`	Validation failure (bad `name`, missing `on_call` on an `llm` tool, both delivery channels set, invalid API URL, unknown enum value, etc.).
`400`	Attempted to attach a non-existent `tool_id`.
`409`	A tool with the same `name` already exists in your account. Names are unique per owner.
`404`	`tool_id` not found, or the authenticated account does not own it.

Replace <api-key> with your actual API key. You can generate one in the PAL Maker.

Getting Started

Guides

Build

Deploy

Debug

Teams & SSO

Resources

Tool Calling for LLM

Tool Object

Top-Level Fields

`parameters`

Examples

`on_call` reference

Examples

`on_resolve` reference

Examples

Creating a Tool

Attaching Tools to a PAL

End-to-End Example

Errors

​Tool Object

​Top-Level Fields

​parameters

​Examples

​on_call reference

​Examples

​on_resolve reference

​Examples

​Creating a Tool

​Attaching Tools to a PAL

​End-to-End Example

​Errors

Tool Object

Top-Level Fields

`parameters`

Examples

`on_call` reference

Examples

`on_resolve` reference

Examples

Creating a Tool

Attaching Tools to a PAL

End-to-End Example

Errors