curl --request PATCH \
  --url https://tavusapi.com/v2/tools/{tool_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "get_current_weather"
}
'

{
  "tool_id": "tabc123def456",
  "owner_id": 3675,
  "name": "get_weather",
  "description": "Get the current weather for a city",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "City name"
      }
    },
    "required": [
      "city"
    ]
  },
  "delivery": {
    "app_message": true,
    "api": {
      "url": "https://api.example.com/v1/weather/{city}",
      "method": "POST",
      "timeout": 10,
      "headers": {
        "X-Service": "weather-bot"
      },
      "auth": {
        "token": "<string>",
        "username": "<string>",
        "password": "<string>",
        "name": "X-API-Key",
        "value": "<string>",
        "location": "header",
        "secret": "<string>",
        "token_url": "https://auth.example.com/oauth/token",
        "client_id": "<string>",
        "client_secret": "<string>",
        "scope": "<string>"
      },
      "body_template": {},
      "query_params": {
        "units": "metric"
      },
      "content_type": "application/json"
    }
  },
  "is_system_tool": false,
  "trigger_type": "in_call",
  "origin": "llm",
  "on_call": "generate_filler",
  "on_resolve": "generate_response",
  "static_filler": "Sure, let me grab that for you.",
  "created_at": "2026-05-15T10:30:00",
  "updated_at": "2026-05-15T10:30:00"
}

{
  "error": "Bad Request. Cannot modify system tools"
}

{
  "message": "Invalid access token"
}

Tools

Update Tool

Update one or more fields on a tool. Only fields present in the body are changed; omitted fields keep their stored value. System tools cannot be updated.

Secrets and the ******** placeholder. Get Tool returns secret fields scrubbed to ********. If you do a read-modify-write and PATCH that exact value back, the request is rejected - re-encrypting the placeholder would silently corrupt the stored secret. To keep the existing secret, omit the field from the auth object on PATCH.

Sending delivery: null resets delivery to the default { app_message: true }.

PATCH

tools

{tool_id}

curl --request PATCH \
  --url https://tavusapi.com/v2/tools/{tool_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "get_current_weather"
}
'

{
  "tool_id": "tabc123def456",
  "owner_id": 3675,
  "name": "get_weather",
  "description": "Get the current weather for a city",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "City name"
      }
    },
    "required": [
      "city"
    ]
  },
  "delivery": {
    "app_message": true,
    "api": {
      "url": "https://api.example.com/v1/weather/{city}",
      "method": "POST",
      "timeout": 10,
      "headers": {
        "X-Service": "weather-bot"
      },
      "auth": {
        "token": "<string>",
        "username": "<string>",
        "password": "<string>",
        "name": "X-API-Key",
        "value": "<string>",
        "location": "header",
        "secret": "<string>",
        "token_url": "https://auth.example.com/oauth/token",
        "client_id": "<string>",
        "client_secret": "<string>",
        "scope": "<string>"
      },
      "body_template": {},
      "query_params": {
        "units": "metric"
      },
      "content_type": "application/json"
    }
  },
  "is_system_tool": false,
  "trigger_type": "in_call",
  "origin": "llm",
  "on_call": "generate_filler",
  "on_resolve": "generate_response",
  "static_filler": "Sure, let me grab that for you.",
  "created_at": "2026-05-15T10:30:00",
  "updated_at": "2026-05-15T10:30:00"
}

{
  "error": "Bad Request. Cannot modify system tools"
}

{
  "message": "Invalid access token"
}

Authorizations

x-api-key

string

header

required

Path Parameters

tool_id

string

required

The unique identifier of the tool. For system tools this is the tool's name (e.g. end_call).

Example:

"tabc123def456"

Body

application/json

name

string

New function name. Same naming and uniqueness rules as on create.

Example:

"get_current_weather"

description

string

New description. Max 10000 characters (combined with parameters).

parameters

object

Replace the JSON Schema for the tool's arguments. Reserved tavus_* property names are rejected.

delivery

object | null

Replace the delivery config. null resets to the default { app_message: true }.

Show child attributes

trigger_type

enum<string>

Available options:

in_call,

post_call

origin

enum<string> | null

Available options:

llm,

vision,

audio

on_call

enum<string> | null

Available options:

generate_filler,

static_filler,

silent,

passthrough

on_resolve

enum<string> | null

Available options:

generate_response,

response_in_result,

add_to_context,

fire_and_forget

static_filler

string | null

Response

Tool updated

A standalone tool definition. Returned by every tool endpoint and embedded in the data array of the PAL-tool endpoints.

tool_id

string

Unique identifier for the tool. System tools use their name as the tool_id (e.g. end_call).

Example:

"tabc123def456"

owner_id

integer | null

Internal user ID that owns the tool. null for built-in system tools.

Example:

3675

name

string

Function name the LLM uses to call the tool.

Example:

"get_weather"

description

string

Natural-language description of the tool.

Example:

"Get the current weather for a city"

parameters

object

JSON Schema describing the tool's arguments.

Example:

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "City name"
    }
  },
  "required": ["city"]
}

delivery

object

How the tool call is dispatched. Exactly one channel must be enabled:

app_message: true alone - the call is delivered to your frontend over the Daily data channel as a conversation.tool_call event.
api set with app_message: false - Tavus makes an HTTPS request to api.url.

If delivery is omitted on create, the default is { "app_message": true }.

Show child attributes

is_system_tool

boolean

Whether this is a built-in system tool. System tools cannot be modified or deleted.

Example:

false

trigger_type

enum<string>

When the tool runs. post_call tools execute server-side after the conversation ends via delivery.api (HTTPS webhook).

Available options:

in_call,

post_call

Example:

"in_call"

origin

enum<string> | null

Live modality for in-call tools. Null for post-call tools.

Available options:

llm,

vision,

audio

Example:

"llm"

on_call

enum<string> | null

What the PAL does while the tool call is in flight. Always null for perception tools.

Available options:

generate_filler,

static_filler,

silent,

passthrough

Example:

"generate_filler"

on_resolve

enum<string> | null

What the PAL does after the tool returns.

Available options:

generate_response,

response_in_result,

add_to_context,

fire_and_forget

Example:

"generate_response"

static_filler

string | null

Phrase the PAL speaks while the tool call is in flight. Set when on_call is static_filler.

Example:

"Sure, let me grab that for you."

created_at

string

ISO 8601 timestamp of when the tool was created.

Example:

"2026-05-15T10:30:00"

updated_at

string

ISO 8601 timestamp of when the tool was last updated.

Example:

"2026-05-15T10:30:00"

Get Tool Delete Tool

⌘I

Introduction

Conversation

PAL

Face

Tools

Skills

Magic Canvas

Objectives

Guardrails

Knowledge Base

Pronunciation Dictionaries

Voices

Deployments

Update Tool

Authorizations

Path Parameters

Body

Response