---
title: "Get Tools"
method: GET
path: "/v2/tools"
tags: ["Tools"]
---

# Get Tools

`GET /v2/tools`

Returns a paginated list of tools. The `type` query parameter controls which tools are returned:

- `type=user` (default) - tools you created via [Create Tool](/api-reference/tools/create-tool).
- `type=system` - built-in system tools Tavus provides. These are always available to every conversation; you do not need to attach them. The only system tool today is `end_call`, which lets the PAL hang up at a natural stopping point.
- `type=all` - both, with system tools listed first.

System tools have `is_system_tool: true`, an `owner_id` of `null`, and use their `name` as the `tool_id` (e.g. `end_call`). They cannot be created, updated, or deleted.

## Query parameters

- `limit` integer
- `page` integer
- `sort` 'asc' | 'desc'
- `type` 'user' | 'system' | 'all'
- `name_or_uuid` string

## Response `200`

Tools returned

- object
  - `data` Tool[]
    - `tool_id` string — Unique identifier for the tool. System tools use their `name` as the `tool_id` (e.g. `end_call`).
    - `owner_id` integer, nullable — Internal user ID that owns the tool. `null` for built-in system tools.
    - `name` string — Function name the LLM uses to call the tool.
    - `description` string — Natural-language description of the tool.
    - `parameters` object — JSON Schema describing the tool's arguments.
    - `delivery` ToolDelivery — 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 }`.
      - `app_message` boolean — Set to `true` to deliver tool calls to your frontend as `conversation.tool_call` events. Mutually exclusive with `api`.
      - `api` ToolApiDelivery — HTTPS request configuration for tool calls delivered via API.
        - `url` string, required — HTTPS URL Tavus calls. Must use `https://`. Hostname must not point at private / loopback / link-local / metadata-server IP space and must not contain `{placeholder}` substitutions - placeholders are only resolved in the path, query string, and body.
        - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' — HTTP method. `GET`, `HEAD`, and `DELETE` reject `body_template`.
        - `timeout` number — Request timeout in seconds. Must be greater than 0 and at most 60. Default 10.
        - `headers` object — Static HTTP headers sent with every request. Keys and values must be strings.
        - `auth` ToolAuth — Outbound authentication for API delivery. The required fields depend on `type`: - `none` - no auth. - `bearer` - `token` is sent as `Authorization: Bearer <token>`. - `basic` - `username` + `password` are encoded into `Authorization: Basic ...`. - `api_key` - `name` + `value` are sent as a header (`location: header`, default) or query parameter (`location: query`). - `hmac` - `secret` signs a fixed Tavus envelope body with HMAC-SHA256; the signature is sent in the `X-Tavus-Signature` header. HMAC mode ignores `body_template`, `query_params`, and URL placeholders. - `oauth2_client_credentials` - Tavus does a client-credentials exchange against `token_url` using `client_id` + `client_secret` (and optional `scope`) and uses the returned bearer token to call the tool URL. On response, all secret fields (`token`, `password`, `value`, `secret`, `client_secret`) are scrubbed to `********`. Echoing that back on PATCH is rejected; omit the field instead to keep the stored secret.
          - `type` 'none' | 'bearer' | 'basic' | 'api_key' | 'hmac' | 'oauth2_client_credentials', required — Auth strategy.
          - `token` string — Bearer token. Required when `type=bearer`.
          - `username` string — HTTP Basic username. Required when `type=basic`.
          - `password` string — HTTP Basic password. Required when `type=basic`.
          - `name` string — API key header / query parameter name. Required when `type=api_key`.
          - `value` string — API key value. Required when `type=api_key`.
          - `location` 'header' | 'query' — Where the API key is sent. Used only when `type=api_key`.
          - `secret` string — HMAC shared secret. Required when `type=hmac`.
          - `token_url` string — OAuth2 token endpoint. Must use HTTPS and pass the same SSRF rules as the tool URL. Required when `type=oauth2_client_credentials`.
          - `client_id` string — OAuth2 client ID. Required when `type=oauth2_client_credentials`.
          - `client_secret` string — OAuth2 client secret. Required when `type=oauth2_client_credentials`.
          - `scope` string — Optional OAuth2 scope string. Used only when `type=oauth2_client_credentials`.
        - `body_template` object — Optional JSON object used as the request body. String values support `{placeholder}` substitutions referencing keys declared in the tool's `parameters.properties`. Rejected when `method` is `GET`, `HEAD`, or `DELETE`, and ignored when `auth.type` is `hmac` (which uses a fixed Tavus envelope).
        - `query_params` object — Static query parameters appended to the URL. Keys and values must be strings; values support `{placeholder}` substitutions. Ignored when `auth.type` is `hmac`.
        - `content_type` string — Override the request `Content-Type` header. Defaults to `application/json` when not set.
    - `is_system_tool` boolean — 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_filler` string, nullable — Phrase the PAL speaks while the tool call is in flight. Set when `on_call` is `static_filler`.
    - `created_at` string — ISO 8601 timestamp of when the tool was created.
    - `updated_at` string — ISO 8601 timestamp of when the tool was last updated.
  - `total_count` integer — Total number of tools matching the filters (across all pages).

## Other responses

- `401` — Unauthorized

---

[API](https://skmtc.dev/tavus/apis/tavus-developer-api-collection.md) · [All operations](https://skmtc.dev/tavus/apis/tavus-developer-api-collection/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tavus/tavus-developer-api-collection/revisions/c878e2f6508d/schema)