v1

latestOpenAPI 3.0.32026-07-267015229.9 KB

Tools

Create Tool

Create a standalone tool that can be attached to one or more PALs via Attach Tools To PAL.

In-call tools (trigger_type: in_call, default) are invoked during the conversation by an LLM (origin: llm) or a perception model (origin: vision / origin: audio).

Post-call actions (trigger_type: post_call) run once after the conversation ends; omit origin and set delivery.api (HTTPS webhook). See Post-Call Actions.

Every tool dispatches via exactly one delivery channel:

delivery.app_message: true (default) - calls land on your frontend as a conversation.tool_call event over the Daily data channel.
delivery.api - Tavus makes an HTTPS request to a URL you configure. Supports five auth types and {placeholder} templating in the URL path, query string, and body.

See Tools Overview, LLM Tool Delivery, and LLM Tool Auth for the conceptual model.

post/v2/tools

Request body

namestring required

Function name the LLM uses to call the tool. Must match OpenAI function-naming rules (letters, digits, underscores; must start with a letter or underscore; max 64 characters) and be unique within your account.

descriptionstring required

Natural-language description used by the LLM to decide when to call the tool. description plus the serialized parameters together must be at most 10000 characters.

parametersobject

JSON Schema describing the tool's arguments. Follows the standard OpenAI function-calling shape. Property names starting with tavus_ are reserved for Tavus-injected placeholders and are rejected.

trigger_type'in_call' | 'post_call'

When the tool runs. in_call (default) offers the tool during the live conversation. post_call runs once after the conversation ends; omit origin and set delivery.api (HTTPS webhook). See Post-Call Actions.

origin'llm' | 'vision' | 'audio' nullable

Live modality for in-call tools only. Required when trigger_type is in_call (defaults to llm). Must be omitted or null for post_call tools.

on_call'generate_filler' | 'static_filler' | 'silent' | 'passthrough' nullable

What the PAL does while the tool call is in flight. generate_filler (default for llm tools) lets the LLM speak a contextual filler line. static_filler plays the static_filler string verbatim. silent says nothing. passthrough skips filler entirely. Must be null for perception tools.

on_resolve'generate_response' | 'response_in_result' | 'add_to_context' | 'fire_and_forget' nullable

what the PAL does after the tool returns. generate_response re-prompts the LLM with the result so it can answer naturally. response_in_result speaks the response text returned by your endpoint verbatim. add_to_context silently adds the result to conversation context. fire_and_forget ignores the result. Perception tools must use fire_and_forget.

static_fillerstring nullable

Phrase the PAL speaks while the tool call is in flight. Required when on_call is static_filler; must be null for perception tools.

Example request

{
  "name": "get_weather",
  "description": "Get the current weather for a city",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "City name"
      }
    },
    "required": [
      "city"
    ]
  },
  "delivery": {
    "api": {
      "url": "https://api.example.com/v1/weather/{city}",
      "headers": {
        "X-Service": "weather-bot"
      },
      "auth": {
        "name": "X-API-Key",
        "token_url": "https://auth.example.com/oauth/token"
      },
      "query_params": {
        "units": "metric"
      },
      "content_type": "application/json"
    }
  },
  "trigger_type": "in_call",
  "origin": "llm",
  "on_call": "generate_filler",
  "on_resolve": "generate_response",
  "static_filler": "Sure, let me grab that for you."
}

Response

Tool created

tool_idstring

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

owner_idinteger nullable

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

namestring

Function name the LLM uses to call the tool.

descriptionstring

Natural-language description of the tool.

parametersobject

JSON Schema describing the tool's arguments.

is_system_toolboolean

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

trigger_type'in_call' | 'post_call'

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

origin'llm' | 'vision' | 'audio' nullable

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

on_call'generate_filler' | 'static_filler' | 'silent' | 'passthrough' nullable

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

on_resolve'generate_response' | 'response_in_result' | 'add_to_context' | 'fire_and_forget' nullable

What the PAL does after the tool returns.

static_fillerstring nullable

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

created_atstring

ISO 8601 timestamp of when the tool was created.

updated_atstring

ISO 8601 timestamp of when the tool was last updated.

Example response

{
  "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": {
    "api": {
      "url": "https://api.example.com/v1/weather/{city}",
      "headers": {
        "X-Service": "weather-bot"
      },
      "auth": {
        "name": "X-API-Key",
        "token_url": "https://auth.example.com/oauth/token"
      },
      "query_params": {
        "units": "metric"
      },
      "content_type": "application/json"
    }
  },
  "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"
}