> ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Get Tool > Returns a single tool by its `tool_id`. Works for both user-owned tools and built-in system tools. Secret fields (`token`, `password`, `value`, `secret`, `client_secret`) are replaced with `********` in the response. ## OpenAPI ````yaml get /v2/tools/{tool_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Faces - name: Voices - name: Conversations - name: Deployments - name: PALs - name: Tools - name: PAL Tools - name: Pronunciation Dictionaries - name: Replacements - name: Transcriptions - name: Documents paths: /v2/tools/{tool_id}: parameters: - name: tool_id in: path required: true description: >- The unique identifier of the tool. For system tools this is the tool's `name` (e.g. `end_call`). schema: type: string example: tabc123def456 get: tags: - Tools summary: Get Tool description: >- Returns a single tool by its `tool_id`. Works for both user-owned tools and built-in system tools. Secret fields (`token`, `password`, `value`, `secret`, `client_secret`) are replaced with `********` in the response. operationId: getTool responses: '200': description: Tool returned content: application/json: schema: $ref: '#/components/schemas/tool' '400': description: Tool not found content: application/json: schema: type: object properties: error: type: string example: Bad Request. Tool not found '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] components: schemas: tool: type: object description: >- A standalone tool definition. Returned by every tool endpoint and embedded in the `data` array of the PAL-tool endpoints. properties: tool_id: type: string description: >- Unique identifier for the tool. System tools use their `name` as the `tool_id` (e.g. `end_call`). example: tabc123def456 owner_id: type: integer nullable: true description: >- Internal user ID that owns the tool. `null` for built-in system tools. example: 3675 name: type: string description: Function name the LLM uses to call the tool. example: get_weather description: type: string description: Natural-language description of the tool. example: Get the current weather for a city parameters: type: object description: JSON Schema describing the tool's arguments. example: type: object properties: city: type: string description: City name required: - city delivery: $ref: '#/components/schemas/toolDelivery' is_system_tool: type: boolean description: >- Whether this is a built-in system tool. System tools cannot be modified or deleted. example: false trigger_type: type: string enum: - in_call - post_call description: >- When the tool runs. `post_call` tools execute server-side after the conversation ends via `delivery.api` (HTTPS webhook). example: in_call origin: type: string enum: - llm - vision - audio nullable: true description: Live modality for in-call tools. Null for post-call tools. example: llm on_call: type: string enum: - generate_filler - static_filler - silent - passthrough nullable: true description: >- What the PAL does while the tool call is in flight. Always null for perception tools. example: generate_filler on_resolve: type: string enum: - generate_response - response_in_result - add_to_context - fire_and_forget nullable: true description: What the PAL does after the tool returns. example: generate_response static_filler: type: string nullable: true description: >- 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: type: string description: ISO 8601 timestamp of when the tool was created. example: '2026-05-15T10:30:00' updated_at: type: string description: ISO 8601 timestamp of when the tool was last updated. example: '2026-05-15T10:30:00' toolDelivery: type: object description: > 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 }`. properties: app_message: type: boolean default: true description: >- Set to `true` to deliver tool calls to your frontend as `conversation.tool_call` events. Mutually exclusive with `api`. api: $ref: '#/components/schemas/toolApiDelivery' toolApiDelivery: type: object required: - url description: HTTPS request configuration for tool calls delivered via API. properties: url: type: string description: > 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. example: https://api.example.com/v1/weather/{city} method: type: string enum: - GET - POST - PUT - PATCH - DELETE - HEAD default: POST description: HTTP method. `GET`, `HEAD`, and `DELETE` reject `body_template`. timeout: type: number minimum: 0 exclusiveMinimum: true maximum: 60 default: 10 description: >- Request timeout in seconds. Must be greater than 0 and at most 60. Default 10. headers: type: object additionalProperties: type: string description: >- Static HTTP headers sent with every request. Keys and values must be strings. example: X-Service: weather-bot auth: $ref: '#/components/schemas/toolAuth' body_template: type: object description: >- 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: type: object additionalProperties: type: string description: >- Static query parameters appended to the URL. Keys and values must be strings; values support `{placeholder}` substitutions. Ignored when `auth.type` is `hmac`. example: units: metric content_type: type: string description: >- Override the request `Content-Type` header. Defaults to `application/json` when not set. example: application/json toolAuth: type: object required: - type description: > Outbound authentication for API delivery. The required fields depend on `type`: - `none` - no auth. - `bearer` - `token` is sent as `Authorization: Bearer `. - `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. properties: type: type: string enum: - none - bearer - basic - api_key - hmac - oauth2_client_credentials description: Auth strategy. token: type: string description: Bearer token. Required when `type=bearer`. username: type: string description: HTTP Basic username. Required when `type=basic`. password: type: string description: HTTP Basic password. Required when `type=basic`. name: type: string description: API key header / query parameter name. Required when `type=api_key`. example: X-API-Key value: type: string description: API key value. Required when `type=api_key`. location: type: string enum: - header - query default: header description: Where the API key is sent. Used only when `type=api_key`. secret: type: string description: HMAC shared secret. Required when `type=hmac`. token_url: type: string description: >- OAuth2 token endpoint. Must use HTTPS and pass the same SSRF rules as the tool URL. Required when `type=oauth2_client_credentials`. example: https://auth.example.com/oauth/token client_id: type: string description: OAuth2 client ID. Required when `type=oauth2_client_credentials`. client_secret: type: string description: >- OAuth2 client secret. Required when `type=oauth2_client_credentials`. scope: type: string description: >- Optional OAuth2 scope string. Used only when `type=oauth2_client_credentials`. securitySchemes: apiKey: type: apiKey in: header name: x-api-key ````