---
title: "Update Tool"
method: PATCH
path: "/v1/convai/tools/{tool_id}"
tags: ["Agents Platform"]
---

# Update Tool

`PATCH /v1/convai/tools/{tool_id}`

Update tool that is available in the workspace.

## Path parameters

- `tool_id` string, required — ID of the requested tool.

## Headers

- `xi-api-key` string, nullable — Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.

## Request body

- ToolRequestModel
  - `tool_config` union, required — Configuration for the tool
    - WebhookToolConfigInput — A webhook tool is a tool that calls an external webhook from our server
      - `type` 'webhook' — The type of tool
      - `name` string, required
      - `description` string, required — Description of when the tool should be used and what it does.
      - `response_timeout_secs` integer — The maximum time in seconds to wait for the tool call to complete. Must be between 5 and 300 seconds (inclusive).
      - `disable_interruptions` boolean — DEPRECATED: use `interruption_mode` instead. If true, the user will not be able to interrupt the agent while this tool is running.
      - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn'
      - `force_pre_tool_speech` boolean — DEPRECATED: use `pre_tool_speech` instead. If true, the agent will speak before the tool call.
      - `pre_tool_speech` 'auto' | 'force' | 'off'
      - `assignments` DynamicVariableAssignment[] — Configuration for extracting values from tool responses and assigning them to dynamic variables
        - `source` 'response' — The source to extract the value from. Currently only 'response' is supported.
        - `dynamic_variable` string, required — The name of the dynamic variable to assign the extracted value to
        - `value_path` string, required — Dot notation path to extract the value from the source (e.g., 'user.name' or 'data.0.id')
        - `sanitize` boolean — If true, this assignment's value will be removed from the tool response before sending to the LLM and transcript, but still processed for variable assignment.
        - `preserve_native_type` boolean — If true, non-scalar values (lists, objects) extracted from the tool response are stored as their native type instead of being stringified to JSON. Enable this to use extracted arrays directly as list dynamic variables.
      - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4', nullable — Predefined tool call sounds; ``None`` means no sound.
      - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played.
      - `tool_error_handling_mode` 'auto' | 'summarized' | 'passthrough' | 'hide' — Controls how tool errors are processed before being shared with the agent.
      - `dynamic_variables` DynamicVariablesConfig
        - `dynamic_variable_placeholders` object — A dictionary of dynamic variable placeholders and their values
      - `execution_mode` 'immediate' | 'post_tool_speech' | 'async'
      - `api_schema` WebhookToolApiSchemaConfigInput, required
        - `request_headers` object — Headers that should be included in the request
        - `url` string, required — The URL that the webhook will be sent to. May include path parameters, e.g. https://example.com/agents/{agent_id}
        - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' — The HTTP method to use for the webhook
        - `path_params_schema` object — Schema for path parameters, if any. The keys should match the placeholders in the URL.
        - `query_params_schema` QueryParamsJsonSchema
          - `properties` object, required
          - `required` string[]
        - `request_body_schema` ObjectJsonSchemaPropertyInput
          - `property_kind` 'array' | 'object'
          - `description` string
          - `dynamic_variable` string — When set, the entire parameter is populated from this dynamic variable at runtime. Mutually exclusive with description (LLM-provided value), constant_value, and is_omitted.
          - `constant_value` object, nullable — When set, the entire object uses this constant JSON value at runtime. Mutually exclusive with description (LLM-provided object), dynamic_variable, and is_omitted.
          - `is_omitted` boolean — If true, this parameter will be completely omitted from the request. Only valid for optional parameters. Mutually exclusive with description, dynamic_variable, and constant_value.
          - `type` 'object'
          - `required` string[]
          - `properties` object
          - `required_constraints` RequiredConstraints — Wrapper for anyOf/allOf composition constraints scoped to required fields.
            - `any_of` RequiredConstraint[]
              - …
            - `all_of` RequiredConstraint[]
              - …
        - `response_body_schema` ObjectJsonSchemaPropertyInput
          - `property_kind` 'array' | 'object'
          - `description` string
          - `dynamic_variable` string — When set, the entire parameter is populated from this dynamic variable at runtime. Mutually exclusive with description (LLM-provided value), constant_value, and is_omitted.
          - `constant_value` object, nullable — When set, the entire object uses this constant JSON value at runtime. Mutually exclusive with description (LLM-provided object), dynamic_variable, and is_omitted.
          - `is_omitted` boolean — If true, this parameter will be completely omitted from the request. Only valid for optional parameters. Mutually exclusive with description, dynamic_variable, and constant_value.
          - `type` 'object'
          - `required` string[]
          - `properties` object
          - `required_constraints` RequiredConstraints — Wrapper for anyOf/allOf composition constraints scoped to required fields.
            - `any_of` RequiredConstraint[]
              - …
            - `all_of` RequiredConstraint[]
              - …
        - `response_filter` ResponseFilter — Configuration for filtering tool responses before they are visible to the agent.
          - `mode` 'all' | 'allow' | 'hide_all' — Controls how tool responses are filtered before being visible to the agent.
          - `filters` string[] — Dot notation paths to include when mode is 'allow' (e.g., ['ticket.id', 'ticket.status']).
          - `content_type` 'application/json' — Content type for response filtering. Only 'application/json' responses are filtered.
        - `content_type` 'application/json' | 'application/x-www-form-urlencoded' — Content type for the request body. Only applies to POST/PUT/PATCH requests.
        - `auth_resolved_params` string[] — URL placeholders resolved from the auth connection (e.g. secrets injected via UrlSecretAuthConnection) rather than from path_params_schema.
        - `auth_connection` union — Optional auth connection to use for authentication with this webhook
          - AuthConnectionLocator — Used to reference an auth connection from the workspace's auth connection store.
            - `auth_connection_id` string, required
          - EnvironmentAuthConnectionLocator — References an environment variable of type 'auth_connection' by label. At runtime, resolves to the auth connection for the current environment, falling back to the default environment.
            - `env_var_label` string, required
    - ClientToolConfigInput — A client tool is one that sends an event to the user's client to trigger something client side
      - `type` 'client' — The type of tool
      - `name` string, required
      - `description` string, required — Description of when the tool should be used and what it does.
      - `response_timeout_secs` integer — The maximum time in seconds to wait for the tool call to complete. Must be between 1 and 120 seconds (inclusive).
      - `disable_interruptions` boolean — DEPRECATED: use `interruption_mode` instead. If true, the user will not be able to interrupt the agent while this tool is running.
      - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn'
      - `force_pre_tool_speech` boolean — DEPRECATED: use `pre_tool_speech` instead. If true, the agent will speak before the tool call.
      - `pre_tool_speech` 'auto' | 'force' | 'off'
      - `assignments` DynamicVariableAssignment[] — Configuration for extracting values from tool responses and assigning them to dynamic variables
        - `source` 'response' — The source to extract the value from. Currently only 'response' is supported.
        - `dynamic_variable` string, required — The name of the dynamic variable to assign the extracted value to
        - `value_path` string, required — Dot notation path to extract the value from the source (e.g., 'user.name' or 'data.0.id')
        - `sanitize` boolean — If true, this assignment's value will be removed from the tool response before sending to the LLM and transcript, but still processed for variable assignment.
        - `preserve_native_type` boolean — If true, non-scalar values (lists, objects) extracted from the tool response are stored as their native type instead of being stringified to JSON. Enable this to use extracted arrays directly as list dynamic variables.
      - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4', nullable — Predefined tool call sounds; ``None`` means no sound.
      - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played.
      - `tool_error_handling_mode` 'auto' | 'summarized' | 'passthrough' | 'hide' — Controls how tool errors are processed before being shared with the agent.
      - `parameters` ObjectJsonSchemaPropertyInput
        - `property_kind` 'array' | 'object'
        - `description` string
        - `dynamic_variable` string — When set, the entire parameter is populated from this dynamic variable at runtime. Mutually exclusive with description (LLM-provided value), constant_value, and is_omitted.
        - `constant_value` object, nullable — When set, the entire object uses this constant JSON value at runtime. Mutually exclusive with description (LLM-provided object), dynamic_variable, and is_omitted.
        - `is_omitted` boolean — If true, this parameter will be completely omitted from the request. Only valid for optional parameters. Mutually exclusive with description, dynamic_variable, and constant_value.
        - `type` 'object'
        - `required` string[]
        - `properties` object
        - `required_constraints` RequiredConstraints — Wrapper for anyOf/allOf composition constraints scoped to required fields.
          - `any_of` RequiredConstraint[]
            - `required` string[], required
          - `all_of` RequiredConstraint[]
            - `required` string[], required
      - `expects_response` boolean — If true, calling this tool should block the conversation until the client responds with some response which is passed to the llm. If false then we will continue the conversation without waiting for the client to respond, this is useful to show content to a user but not block the conversation
      - `dynamic_variables` DynamicVariablesConfig
        - `dynamic_variable_placeholders` object — A dictionary of dynamic variable placeholders and their values
      - `execution_mode` 'immediate' | 'post_tool_speech' | 'async'
    - SystemToolConfigInput — A system tool is a tool that is used to call a system method in the server
      - `type` 'system' — The type of tool
      - `name` string, required
      - `description` string — Description of when the tool should be used and what it does. Leave empty to use the default description that's optimized for the specific tool type.
      - `response_timeout_secs` integer — The maximum time in seconds to wait for the tool call to complete.
      - `disable_interruptions` boolean — DEPRECATED: use `interruption_mode` instead. If true, the user will not be able to interrupt the agent while this tool is running.
      - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn'
      - `force_pre_tool_speech` boolean — DEPRECATED: use `pre_tool_speech` instead. If true, the agent will speak before the tool call.
      - `pre_tool_speech` 'auto' | 'force' | 'off'
      - `assignments` DynamicVariableAssignment[] — Configuration for extracting values from tool responses and assigning them to dynamic variables
        - `source` 'response' — The source to extract the value from. Currently only 'response' is supported.
        - `dynamic_variable` string, required — The name of the dynamic variable to assign the extracted value to
        - `value_path` string, required — Dot notation path to extract the value from the source (e.g., 'user.name' or 'data.0.id')
        - `sanitize` boolean — If true, this assignment's value will be removed from the tool response before sending to the LLM and transcript, but still processed for variable assignment.
        - `preserve_native_type` boolean — If true, non-scalar values (lists, objects) extracted from the tool response are stored as their native type instead of being stringified to JSON. Enable this to use extracted arrays directly as list dynamic variables.
      - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4', nullable — Predefined tool call sounds; ``None`` means no sound.
      - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played.
      - `tool_error_handling_mode` 'auto' | 'summarized' | 'passthrough' | 'hide' — Controls how tool errors are processed before being shared with the agent.
      - `params` union, required
        - EndCallToolConfig
          - `system_tool_type` 'end_call'
        - LanguageDetectionToolConfig
          - `system_tool_type` 'language_detection'
          - `only_at_conversation_start` boolean — If no language switch happens in the first 2 user turns, later attempts fail and the conversation stays in the current language. If the language switches during those turns, later switching stays available. Enable to reduce the possibility of false switching.
        - TransferToAgentToolConfigInput
          - `system_tool_type` 'transfer_to_agent'
          - `transfers` AgentTransferInput[], required
            - `agent_id` string, nullable
            - `node_id` string, nullable
            - `condition` string, required
            - `delay_ms` integer
            - `transfer_message` string, nullable
            - `enable_transferred_agent_first_message` boolean
            - `is_workflow_node_transfer` boolean
            - `preserve_client_tts_overrides` boolean — Defines whether TTS client overrides should be carried over to the transferred agent.
        - TransferToNumberToolConfigInput
          - `system_tool_type` 'transfer_to_number'
          - `transfers` PhoneNumberTransfer[], required
            - `custom_sip_headers` union[] — Custom SIP headers to include when transferring the call. Each header can be either a static value or a dynamic variable reference.
              - …
            - `transfer_destination` union, required
              - …
            - `transfer_type` 'blind' | 'conference' | 'sip_refer'
            - `uui` UUITransferConfig — User-to-User Information envelope for SIP REFER transfers (RFC 7433). Outbound payloads are hex-encoded (the only encoding RFC 7433 defines). The protocol discriminator axis lets per-platform formats (Talkdesk, Genesys, ...) be expressed by configuration rather than scattered transfer flags. Further axes (ASCII encoding, header name, purpose/content parameters) can be added here without touching the transfer model.
              - …
            - `post_dial_digits` union — DTMF digits to send after call connects (e.g., 'ww1234' for extension). Can be either a static value or a dynamic variable reference. Use 'w' for 0.5s pause. Only supported for Twilio transfers.
              - …
            - `phone_number` string, nullable
            - `condition` string, required
          - `enable_client_message` boolean — Whether to play a message to the client while they wait for transfer. Defaults to true for backward compatibility.
        - SkipTurnToolConfig — Allows the agent to explicitly skip its turn. This tool should be invoked by the LLM when the user indicates they would like to think or take a short pause before continuing the conversation—e.g. when they say: "Give me a second", "Let me think", or "One moment please". After calling this tool, the assistant should not speak until the user speaks again, or another normal turn-taking condition is met. The tool itself has no parameters and performs no side-effects other than informing the backend that the current turn generation is complete.
          - `system_tool_type` 'skip_turn'
        - PlayDTMFToolConfig — Allows the agent to play DTMF tones during a phone call. This tool can be used to interact with automated phone systems, such as navigating phone menus, entering extensions, or inputting numeric codes.
          - `system_tool_type` 'play_keypad_touch_tone'
          - `use_out_of_band_dtmf` boolean — Send DTMF tones as out-of-band RTP events (RFC 4733) instead of in-band audio. Only effective for SIP trunk imported numbers.
          - `suppress_turn_after_dtmf` boolean — If true, the agent will not generate further speech after playing DTMF tones. This prevents the agent's speech from interfering with IVR systems.
        - VoicemailDetectionToolConfig — Allows the agent to detect when a voicemail system is encountered. This tool should be invoked by the LLM when it detects that the call has been answered by a voicemail system rather than a human. If a voicemail message is configured, it will be played; otherwise the call will end immediately.
          - `system_tool_type` 'voicemail_detection'
          - `voicemail_message` string, nullable — Optional message to leave on voicemail when detected. If not provided, the call will end immediately when voicemail is detected. Supports dynamic variables (e.g., {{system__time}}, {{system__call_duration_secs}}, {{custom_variable}}).
        - KnowledgeBaseRagToolConfig
          - `system_tool_type` 'knowledge_base_rag'
        - KnowledgeBaseToolConfig
          - `system_tool_type` 'knowledge_base'
          - `enabled_strategies` SearchStrategy[]
        - StartProcedureToolConfigInput
          - `system_tool_type` 'start_procedure'
          - `procedures` object
        - EndProcedureToolConfigInput
          - `system_tool_type` 'end_procedure'
          - `procedures` object
        - RunSubagentToolConfigInput
          - `system_tool_type` 'run_subagent'
          - `agents` SubAgentInput[], required
            - `agent_id` string, required
            - `branch_id` string, nullable
            - `description` string, required
            - `parameters` ObjectJsonSchemaPropertyInput
              - …
    - MCPToolConfigInput — An MCP tool configuration that can be used to call MCP servers
      - `type` 'mcp'
      - `name` string, required
      - `description` string, required — Description of when the tool should be used and what it does.
      - `response_timeout_secs` integer — The maximum time in seconds to wait for the MCP tool call to complete. Must be between 5 and 300 seconds (inclusive).
      - `disable_interruptions` boolean — DEPRECATED: use `interruption_mode` instead. If true, the user will not be able to interrupt the agent while this tool is running.
      - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn'
      - `force_pre_tool_speech` boolean — DEPRECATED: use `pre_tool_speech` instead. If true, the agent will speak before the tool call.
      - `pre_tool_speech` 'auto' | 'force' | 'off'
      - `assignments` DynamicVariableAssignment[] — Configuration for extracting values from tool responses and assigning them to dynamic variables
        - `source` 'response' — The source to extract the value from. Currently only 'response' is supported.
        - `dynamic_variable` string, required — The name of the dynamic variable to assign the extracted value to
        - `value_path` string, required — Dot notation path to extract the value from the source (e.g., 'user.name' or 'data.0.id')
        - `sanitize` boolean — If true, this assignment's value will be removed from the tool response before sending to the LLM and transcript, but still processed for variable assignment.
        - `preserve_native_type` boolean — If true, non-scalar values (lists, objects) extracted from the tool response are stored as their native type instead of being stringified to JSON. Enable this to use extracted arrays directly as list dynamic variables.
      - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4', nullable — Predefined tool call sounds; ``None`` means no sound.
      - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played.
      - `tool_error_handling_mode` 'auto' | 'summarized' | 'passthrough' | 'hide' — Controls how tool errors are processed before being shared with the agent.
      - `integration_type` 'mcp_server' | 'mcp_integration', required
      - `parameters` ObjectJsonSchemaPropertyInput
        - `property_kind` 'array' | 'object'
        - `description` string
        - `dynamic_variable` string — When set, the entire parameter is populated from this dynamic variable at runtime. Mutually exclusive with description (LLM-provided value), constant_value, and is_omitted.
        - `constant_value` object, nullable — When set, the entire object uses this constant JSON value at runtime. Mutually exclusive with description (LLM-provided object), dynamic_variable, and is_omitted.
        - `is_omitted` boolean — If true, this parameter will be completely omitted from the request. Only valid for optional parameters. Mutually exclusive with description, dynamic_variable, and constant_value.
        - `type` 'object'
        - `required` string[]
        - `properties` object
        - `required_constraints` RequiredConstraints — Wrapper for anyOf/allOf composition constraints scoped to required fields.
          - `any_of` RequiredConstraint[]
            - `required` string[], required
          - `all_of` RequiredConstraint[]
            - `required` string[], required
      - `approval_policy` 'auto_approve_all' | 'require_approval_all' | 'require_approval_per_tool' — Defines the MCP server-level approval policy for tool execution.
      - `mcp_tool_name` string, required — The name of the MCP tool to call
      - `mcp_tool_description` string, required — The description of the MCP tool to call
      - `mcp_server_id` string, required — The id of the MCP server to call
      - `mcp_server_name` string, required — The name of the MCP server to call
      - `mcp_input_schema` object, nullable — Original inputSchema dict for consistent hashing
      - `execution_mode` 'immediate' | 'post_tool_speech' | 'async'
      - `input_overrides` object, nullable — Input parameter overrides for this tool
  - `response_mocks` ToolResponseMockConfigInput[], nullable — Mock responses with optional parameter conditions. Evaluated top-to-bottom; first match wins.
    - `parameter_conditions` UnitTestToolCallParameter[] — If the list is empty, the mock will always activate.
      - `eval` union, required
        - LLMParameterEvaluationStrategy
          - `type` 'llm', required
          - `description` string, required — A description of the evaluation strategy to use for the test.
        - RegexParameterEvaluationStrategy
          - `type` 'regex', required
          - `pattern` string, required — A regex pattern to match the agent's response against.
        - ExactParameterEvaluationStrategy
          - `type` 'exact', required
          - `expected_value` string, required — The exact string value that the parameter must match.
        - MatchAnythingParameterEvaluationStrategy
          - `type` 'anything', required
      - `path` string, required
    - `mock_result` string, required — The return value the LLM sees when this mock is active.
    - `is_error` boolean — If true, the mock result is surfaced to the LLM as a tool error rather than a successful result.

## Response `200`

Successful Response

- ToolResponseModel
  - `id` string, required
  - `tool_config` union, required — The type of tool
    - WebhookToolConfigOutput — A webhook tool is a tool that calls an external webhook from our server
      - `type` 'webhook' — The type of tool
      - `name` string, required
      - `description` string, required — Description of when the tool should be used and what it does.
      - `response_timeout_secs` integer — The maximum time in seconds to wait for the tool call to complete. Must be between 5 and 300 seconds (inclusive).
      - `disable_interruptions` boolean — DEPRECATED: use `interruption_mode` instead. If true, the user will not be able to interrupt the agent while this tool is running.
      - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn'
      - `force_pre_tool_speech` boolean — DEPRECATED: use `pre_tool_speech` instead. If true, the agent will speak before the tool call.
      - `pre_tool_speech` 'auto' | 'force' | 'off'
      - `assignments` DynamicVariableAssignment[] — Configuration for extracting values from tool responses and assigning them to dynamic variables
        - `source` 'response' — The source to extract the value from. Currently only 'response' is supported.
        - `dynamic_variable` string, required — The name of the dynamic variable to assign the extracted value to
        - `value_path` string, required — Dot notation path to extract the value from the source (e.g., 'user.name' or 'data.0.id')
        - `sanitize` boolean — If true, this assignment's value will be removed from the tool response before sending to the LLM and transcript, but still processed for variable assignment.
        - `preserve_native_type` boolean — If true, non-scalar values (lists, objects) extracted from the tool response are stored as their native type instead of being stringified to JSON. Enable this to use extracted arrays directly as list dynamic variables.
      - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4', nullable — Predefined tool call sounds; ``None`` means no sound.
      - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played.
      - `tool_error_handling_mode` 'auto' | 'summarized' | 'passthrough' | 'hide' — Controls how tool errors are processed before being shared with the agent.
      - `dynamic_variables` DynamicVariablesConfig
        - `dynamic_variable_placeholders` object — A dictionary of dynamic variable placeholders and their values
      - `execution_mode` 'immediate' | 'post_tool_speech' | 'async'
      - `api_schema` WebhookToolApiSchemaConfigOutput, required
        - `request_headers` object — Headers that should be included in the request
        - `url` string, required — The URL that the webhook will be sent to. May include path parameters, e.g. https://example.com/agents/{agent_id}
        - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' — The HTTP method to use for the webhook
        - `path_params_schema` object — Schema for path parameters, if any. The keys should match the placeholders in the URL.
        - `query_params_schema` QueryParamsJsonSchema
          - `properties` object, required
          - `required` string[]
        - `request_body_schema` ObjectJsonSchemaPropertyOutput
          - `description` string
          - `dynamic_variable` string — When set, the entire parameter is populated from this dynamic variable at runtime. Mutually exclusive with description (LLM-provided value), constant_value, and is_omitted.
          - `constant_value` object, nullable — When set, the entire object uses this constant JSON value at runtime. Mutually exclusive with description (LLM-provided object), dynamic_variable, and is_omitted.
          - `is_omitted` boolean — If true, this parameter will be completely omitted from the request. Only valid for optional parameters. Mutually exclusive with description, dynamic_variable, and constant_value.
          - `type` 'object'
          - `required` string[]
          - `properties` object
          - `required_constraints` RequiredConstraints — Wrapper for anyOf/allOf composition constraints scoped to required fields.
            - `any_of` RequiredConstraint[]
              - …
            - `all_of` RequiredConstraint[]
              - …
        - `response_body_schema` ObjectJsonSchemaPropertyOutput
          - `description` string
          - `dynamic_variable` string — When set, the entire parameter is populated from this dynamic variable at runtime. Mutually exclusive with description (LLM-provided value), constant_value, and is_omitted.
          - `constant_value` object, nullable — When set, the entire object uses this constant JSON value at runtime. Mutually exclusive with description (LLM-provided object), dynamic_variable, and is_omitted.
          - `is_omitted` boolean — If true, this parameter will be completely omitted from the request. Only valid for optional parameters. Mutually exclusive with description, dynamic_variable, and constant_value.
          - `type` 'object'
          - `required` string[]
          - `properties` object
          - `required_constraints` RequiredConstraints — Wrapper for anyOf/allOf composition constraints scoped to required fields.
            - `any_of` RequiredConstraint[]
              - …
            - `all_of` RequiredConstraint[]
              - …
        - `response_filter` ResponseFilter — Configuration for filtering tool responses before they are visible to the agent.
          - `mode` 'all' | 'allow' | 'hide_all' — Controls how tool responses are filtered before being visible to the agent.
          - `filters` string[] — Dot notation paths to include when mode is 'allow' (e.g., ['ticket.id', 'ticket.status']).
          - `content_type` 'application/json' — Content type for response filtering. Only 'application/json' responses are filtered.
        - `content_type` 'application/json' | 'application/x-www-form-urlencoded' — Content type for the request body. Only applies to POST/PUT/PATCH requests.
        - `auth_resolved_params` string[] — URL placeholders resolved from the auth connection (e.g. secrets injected via UrlSecretAuthConnection) rather than from path_params_schema.
        - `auth_connection` union — Optional auth connection to use for authentication with this webhook
          - AuthConnectionLocator — Used to reference an auth connection from the workspace's auth connection store.
            - `auth_connection_id` string, required
          - EnvironmentAuthConnectionLocator — References an environment variable of type 'auth_connection' by label. At runtime, resolves to the auth connection for the current environment, falling back to the default environment.
            - `env_var_label` string, required
    - ClientToolConfigOutput — A client tool is one that sends an event to the user's client to trigger something client side
      - `type` 'client' — The type of tool
      - `name` string, required
      - `description` string, required — Description of when the tool should be used and what it does.
      - `response_timeout_secs` integer — The maximum time in seconds to wait for the tool call to complete. Must be between 1 and 120 seconds (inclusive).
      - `disable_interruptions` boolean — DEPRECATED: use `interruption_mode` instead. If true, the user will not be able to interrupt the agent while this tool is running.
      - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn'
      - `force_pre_tool_speech` boolean — DEPRECATED: use `pre_tool_speech` instead. If true, the agent will speak before the tool call.
      - `pre_tool_speech` 'auto' | 'force' | 'off'
      - `assignments` DynamicVariableAssignment[] — Configuration for extracting values from tool responses and assigning them to dynamic variables
        - `source` 'response' — The source to extract the value from. Currently only 'response' is supported.
        - `dynamic_variable` string, required — The name of the dynamic variable to assign the extracted value to
        - `value_path` string, required — Dot notation path to extract the value from the source (e.g., 'user.name' or 'data.0.id')
        - `sanitize` boolean — If true, this assignment's value will be removed from the tool response before sending to the LLM and transcript, but still processed for variable assignment.
        - `preserve_native_type` boolean — If true, non-scalar values (lists, objects) extracted from the tool response are stored as their native type instead of being stringified to JSON. Enable this to use extracted arrays directly as list dynamic variables.
      - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4', nullable — Predefined tool call sounds; ``None`` means no sound.
      - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played.
      - `tool_error_handling_mode` 'auto' | 'summarized' | 'passthrough' | 'hide' — Controls how tool errors are processed before being shared with the agent.
      - `parameters` ObjectJsonSchemaPropertyOutput
        - `description` string
        - `dynamic_variable` string — When set, the entire parameter is populated from this dynamic variable at runtime. Mutually exclusive with description (LLM-provided value), constant_value, and is_omitted.
        - `constant_value` object, nullable — When set, the entire object uses this constant JSON value at runtime. Mutually exclusive with description (LLM-provided object), dynamic_variable, and is_omitted.
        - `is_omitted` boolean — If true, this parameter will be completely omitted from the request. Only valid for optional parameters. Mutually exclusive with description, dynamic_variable, and constant_value.
        - `type` 'object'
        - `required` string[]
        - `properties` object
        - `required_constraints` RequiredConstraints — Wrapper for anyOf/allOf composition constraints scoped to required fields.
          - `any_of` RequiredConstraint[]
            - `required` string[], required
          - `all_of` RequiredConstraint[]
            - `required` string[], required
      - `expects_response` boolean — If true, calling this tool should block the conversation until the client responds with some response which is passed to the llm. If false then we will continue the conversation without waiting for the client to respond, this is useful to show content to a user but not block the conversation
      - `dynamic_variables` DynamicVariablesConfig
        - `dynamic_variable_placeholders` object — A dictionary of dynamic variable placeholders and their values
      - `execution_mode` 'immediate' | 'post_tool_speech' | 'async'
    - SystemToolConfigOutput — A system tool is a tool that is used to call a system method in the server
      - `type` 'system' — The type of tool
      - `name` string, required
      - `description` string — Description of when the tool should be used and what it does. Leave empty to use the default description that's optimized for the specific tool type.
      - `response_timeout_secs` integer — The maximum time in seconds to wait for the tool call to complete.
      - `disable_interruptions` boolean — DEPRECATED: use `interruption_mode` instead. If true, the user will not be able to interrupt the agent while this tool is running.
      - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn'
      - `force_pre_tool_speech` boolean — DEPRECATED: use `pre_tool_speech` instead. If true, the agent will speak before the tool call.
      - `pre_tool_speech` 'auto' | 'force' | 'off'
      - `assignments` DynamicVariableAssignment[] — Configuration for extracting values from tool responses and assigning them to dynamic variables
        - `source` 'response' — The source to extract the value from. Currently only 'response' is supported.
        - `dynamic_variable` string, required — The name of the dynamic variable to assign the extracted value to
        - `value_path` string, required — Dot notation path to extract the value from the source (e.g., 'user.name' or 'data.0.id')
        - `sanitize` boolean — If true, this assignment's value will be removed from the tool response before sending to the LLM and transcript, but still processed for variable assignment.
        - `preserve_native_type` boolean — If true, non-scalar values (lists, objects) extracted from the tool response are stored as their native type instead of being stringified to JSON. Enable this to use extracted arrays directly as list dynamic variables.
      - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4', nullable — Predefined tool call sounds; ``None`` means no sound.
      - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played.
      - `tool_error_handling_mode` 'auto' | 'summarized' | 'passthrough' | 'hide' — Controls how tool errors are processed before being shared with the agent.
      - `params` union, required
        - EndCallToolConfig
          - `system_tool_type` 'end_call'
        - LanguageDetectionToolConfig
          - `system_tool_type` 'language_detection'
          - `only_at_conversation_start` boolean — If no language switch happens in the first 2 user turns, later attempts fail and the conversation stays in the current language. If the language switches during those turns, later switching stays available. Enable to reduce the possibility of false switching.
        - TransferToAgentToolConfigOutput
          - `system_tool_type` 'transfer_to_agent'
          - `transfers` AgentTransferOutput[], required
            - `agent_id` string, nullable
            - `node_id` string, nullable
            - `condition` string, required
            - `delay_ms` integer
            - `transfer_message` string, nullable
            - `enable_transferred_agent_first_message` boolean
            - `is_workflow_node_transfer` boolean
            - `preserve_client_tts_overrides` boolean — Defines whether TTS client overrides should be carried over to the transferred agent.
        - TransferToNumberToolConfigOutput
          - `system_tool_type` 'transfer_to_number'
          - `transfers` PhoneNumberTransfer[], required
            - `custom_sip_headers` union[] — Custom SIP headers to include when transferring the call. Each header can be either a static value or a dynamic variable reference.
              - …
            - `transfer_destination` union, required
              - …
            - `transfer_type` 'blind' | 'conference' | 'sip_refer'
            - `uui` UUITransferConfig — User-to-User Information envelope for SIP REFER transfers (RFC 7433). Outbound payloads are hex-encoded (the only encoding RFC 7433 defines). The protocol discriminator axis lets per-platform formats (Talkdesk, Genesys, ...) be expressed by configuration rather than scattered transfer flags. Further axes (ASCII encoding, header name, purpose/content parameters) can be added here without touching the transfer model.
              - …
            - `post_dial_digits` union — DTMF digits to send after call connects (e.g., 'ww1234' for extension). Can be either a static value or a dynamic variable reference. Use 'w' for 0.5s pause. Only supported for Twilio transfers.
              - …
            - `phone_number` string, nullable
            - `condition` string, required
          - `enable_client_message` boolean — Whether to play a message to the client while they wait for transfer. Defaults to true for backward compatibility.
        - SkipTurnToolConfig — Allows the agent to explicitly skip its turn. This tool should be invoked by the LLM when the user indicates they would like to think or take a short pause before continuing the conversation—e.g. when they say: "Give me a second", "Let me think", or "One moment please". After calling this tool, the assistant should not speak until the user speaks again, or another normal turn-taking condition is met. The tool itself has no parameters and performs no side-effects other than informing the backend that the current turn generation is complete.
          - `system_tool_type` 'skip_turn'
        - PlayDTMFToolConfig — Allows the agent to play DTMF tones during a phone call. This tool can be used to interact with automated phone systems, such as navigating phone menus, entering extensions, or inputting numeric codes.
          - `system_tool_type` 'play_keypad_touch_tone'
          - `use_out_of_band_dtmf` boolean — Send DTMF tones as out-of-band RTP events (RFC 4733) instead of in-band audio. Only effective for SIP trunk imported numbers.
          - `suppress_turn_after_dtmf` boolean — If true, the agent will not generate further speech after playing DTMF tones. This prevents the agent's speech from interfering with IVR systems.
        - VoicemailDetectionToolConfig — Allows the agent to detect when a voicemail system is encountered. This tool should be invoked by the LLM when it detects that the call has been answered by a voicemail system rather than a human. If a voicemail message is configured, it will be played; otherwise the call will end immediately.
          - `system_tool_type` 'voicemail_detection'
          - `voicemail_message` string, nullable — Optional message to leave on voicemail when detected. If not provided, the call will end immediately when voicemail is detected. Supports dynamic variables (e.g., {{system__time}}, {{system__call_duration_secs}}, {{custom_variable}}).
        - KnowledgeBaseRagToolConfig
          - `system_tool_type` 'knowledge_base_rag'
        - KnowledgeBaseToolConfig
          - `system_tool_type` 'knowledge_base'
          - `enabled_strategies` SearchStrategy[]
        - StartProcedureToolConfigOutput
          - `system_tool_type` 'start_procedure'
          - `procedures` object
        - EndProcedureToolConfigOutput
          - `system_tool_type` 'end_procedure'
          - `procedures` object
        - RunSubagentToolConfigOutput
          - `system_tool_type` 'run_subagent'
          - `agents` SubAgentOutput[], required
            - `agent_id` string, required
            - `branch_id` string, nullable
            - `description` string, required
            - `parameters` ObjectJsonSchemaPropertyOutput
              - …
    - MCPToolConfigOutput — An MCP tool configuration that can be used to call MCP servers
      - `type` 'mcp'
      - `name` string, required
      - `description` string, required — Description of when the tool should be used and what it does.
      - `response_timeout_secs` integer — The maximum time in seconds to wait for the MCP tool call to complete. Must be between 5 and 300 seconds (inclusive).
      - `disable_interruptions` boolean — DEPRECATED: use `interruption_mode` instead. If true, the user will not be able to interrupt the agent while this tool is running.
      - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn'
      - `force_pre_tool_speech` boolean — DEPRECATED: use `pre_tool_speech` instead. If true, the agent will speak before the tool call.
      - `pre_tool_speech` 'auto' | 'force' | 'off'
      - `assignments` DynamicVariableAssignment[] — Configuration for extracting values from tool responses and assigning them to dynamic variables
        - `source` 'response' — The source to extract the value from. Currently only 'response' is supported.
        - `dynamic_variable` string, required — The name of the dynamic variable to assign the extracted value to
        - `value_path` string, required — Dot notation path to extract the value from the source (e.g., 'user.name' or 'data.0.id')
        - `sanitize` boolean — If true, this assignment's value will be removed from the tool response before sending to the LLM and transcript, but still processed for variable assignment.
        - `preserve_native_type` boolean — If true, non-scalar values (lists, objects) extracted from the tool response are stored as their native type instead of being stringified to JSON. Enable this to use extracted arrays directly as list dynamic variables.
      - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4', nullable — Predefined tool call sounds; ``None`` means no sound.
      - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played.
      - `tool_error_handling_mode` 'auto' | 'summarized' | 'passthrough' | 'hide' — Controls how tool errors are processed before being shared with the agent.
      - `integration_type` 'mcp_server' | 'mcp_integration', required
      - `parameters` ObjectJsonSchemaPropertyOutput
        - `description` string
        - `dynamic_variable` string — When set, the entire parameter is populated from this dynamic variable at runtime. Mutually exclusive with description (LLM-provided value), constant_value, and is_omitted.
        - `constant_value` object, nullable — When set, the entire object uses this constant JSON value at runtime. Mutually exclusive with description (LLM-provided object), dynamic_variable, and is_omitted.
        - `is_omitted` boolean — If true, this parameter will be completely omitted from the request. Only valid for optional parameters. Mutually exclusive with description, dynamic_variable, and constant_value.
        - `type` 'object'
        - `required` string[]
        - `properties` object
        - `required_constraints` RequiredConstraints — Wrapper for anyOf/allOf composition constraints scoped to required fields.
          - `any_of` RequiredConstraint[]
            - `required` string[], required
          - `all_of` RequiredConstraint[]
            - `required` string[], required
      - `approval_policy` 'auto_approve_all' | 'require_approval_all' | 'require_approval_per_tool' — Defines the MCP server-level approval policy for tool execution.
      - `mcp_tool_name` string, required — The name of the MCP tool to call
      - `mcp_tool_description` string, required — The description of the MCP tool to call
      - `mcp_server_id` string, required — The id of the MCP server to call
      - `mcp_server_name` string, required — The name of the MCP server to call
      - `mcp_input_schema` object, nullable — Original inputSchema dict for consistent hashing
      - `execution_mode` 'immediate' | 'post_tool_speech' | 'async'
      - `input_overrides` object, nullable — Input parameter overrides for this tool
  - `access_info` ResourceAccessInfo, required
    - `is_creator` boolean, required — Whether the user making the request is the creator of the agent
    - `creator_name` string, required — Name of the agent's creator
    - `creator_email` string, required — Email of the agent's creator
    - `role` 'admin' | 'editor' | 'commenter' | 'viewer', required — The role of the user making the request
    - `anonymous_access_level_override` 'admin' | 'editor' | 'commenter' | 'viewer', nullable — The access level for anonymous users. If None, the resource is not shared publicly.
    - `access_source` 'creator' | 'explicit' | 'workspace_admin' | 'workspace_default', nullable — Why the requesting user has access to this resource. 'creator' = caller is the owner. 'explicit' = caller (or one of their workspace groups) is listed in role_to_group_ids beyond the workspace-wide everyone group. 'workspace_default' = the workspace-wide everyone group is listed in role_to_group_ids (every non-anon workspace member, including admins, sees this resource). 'workspace_admin' = caller is a workspace admin and the admin seat is the *only* path to access; reserved for docs nobody else can see. Lets the UI disclose why an admin-bypass viewer sees a doc that wasn't explicitly shared with them.
  - `usage_stats` ToolUsageStatsResponseModel, required
    - `total_calls` integer — The total number of calls to the tool
    - `avg_latency_secs` number, required
  - `response_mocks` ToolResponseMockConfigOutput[], nullable — Mock responses with optional parameter conditions. Evaluated top-to-bottom; first match wins.
    - `parameter_conditions` UnitTestToolCallParameter[] — If the list is empty, the mock will always activate.
      - `eval` union, required
        - LLMParameterEvaluationStrategy
          - `type` 'llm', required
          - `description` string, required — A description of the evaluation strategy to use for the test.
        - RegexParameterEvaluationStrategy
          - `type` 'regex', required
          - `pattern` string, required — A regex pattern to match the agent's response against.
        - ExactParameterEvaluationStrategy
          - `type` 'exact', required
          - `expected_value` string, required — The exact string value that the parameter must match.
        - MatchAnythingParameterEvaluationStrategy
          - `type` 'anything', required
      - `path` string, required
    - `mock_result` string, required — The return value the LLM sees when this mock is active.
    - `is_error` boolean — If true, the mock result is surfaced to the LLM as a tool error rather than a successful result.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/elevenlabs/apis/elevenlabs-api-documentation.md) · [All operations](https://skmtc.net/elevenlabs/apis/elevenlabs-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/elevenlabs/elevenlabs-api-documentation/versions/57d56f34628a/schema)