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 }.

Request body

namestring

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

descriptionstring

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

parametersobject

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

trigger_type'in_call' | 'post_call'

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

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

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

static_fillerstring nullable

Example request

{
  "name": "get_current_weather",
  "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"
    }
  }
}

Response

Tool updated

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"
}