---
title: "POST /create-retell-llm"
method: POST
path: "/create-retell-llm"
---

# POST /create-retell-llm

`POST /create-retell-llm`

Create a new Retell LLM Response Engine that can be attached to an agent. This is used to generate response output for the agent.

## Request body

- RetellLlmRequest — Override properties for Retell LLM configuration in agent override requests.
  - `model` 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-5' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5.5' | 'claude-4.5-sonnet' | 'claude-4.6-sonnet' | 'claude-4.5-haiku' | 'gemini-2.5-flash-lite' | 'gemini-3.0-flash' | 'gemini-3.1-flash-lite' | 'null', nullable — Available LLM models for agents.
  - `s2s_model` 'gpt-realtime-2' | 'gpt-realtime-1.5' | 'gpt-realtime' | 'gpt-realtime-mini' | 'null', nullable — Select the underlying speech to speech model. Can only set this or model, not both.
  - `model_temperature` number — If set, will control the randomness of the response. Value ranging from [0,1]. Lower value means more deterministic, while higher value means more random. If unset, default value 0 will apply. Note that for tool calling, a lower value is recommended.
  - `model_high_priority` boolean, nullable — If set to true, will use high priority pool with more dedicated resource to ensure lower and more consistent latency, default to false. This feature usually comes with a higher cost.
  - `tool_call_strict_mode` boolean, nullable — Whether to use strict mode for tool calls. Only applicable when using certain supported models.
  - `knowledge_base_ids` string[], nullable — A list of knowledge base ids to use for this resource.
  - `kb_config` KBConfig
    - `top_k` integer — Max number of knowledge base chunks to retrieve
    - `filter_score` number — Similarity threshold for filtering search results
  - `start_speaker` 'user' | 'agent' — The speaker who starts the conversation. Required. Must be either 'user' or 'agent'.
  - `begin_after_user_silence_ms` integer, nullable — If set, the AI will begin the conversation after waiting for the user for the duration (in milliseconds) specified by this attribute. This only applies if the agent is configured to wait for the user to speak first. If not set, the agent will wait indefinitely for the user to speak.
  - `begin_message` string, nullable — First utterance said by the agent in the call. If not set, LLM will dynamically generate a message. If set to "", agent will wait for user to speak first.
  - `general_prompt` string, nullable — General prompt appended to system prompt no matter what state the agent is in. - System prompt (with state) = general prompt + state prompt. - System prompt (no state) = general prompt.
  - `general_tools` Tool[], nullable — A list of tools the model may call (to get external knowledge, call API, etc). You can select from some common predefined tools like end call, transfer call, etc; or you can create your own custom tool for the LLM to use. - Tools of LLM (with state) = general tools + state tools + state transitions - Tools of LLM (no state) = general tools
    - union
      - EndCallTool
        - `type` 'end_call', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `speak_during_execution` boolean — If true, will speak during execution.
        - `execution_message_description` string — Describes what to say to user when ending the call. Only applicable when speak_during_execution is true.
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
      - TransferCallTool
        - `type` 'transfer_call', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges).
        - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `transfer_destination` union, required
          - TransferDestinationPredefined
            - `type` 'predefined', required — The type of transfer destination.
            - `number` string, required — The number to transfer to in E.164 format or a dynamic variable like {{transfer_number}}.
            - `extension` string — Extension digits to dial after the main number connects. Sent via DTMF. Allow digits, '*', '#', or a dynamic variable like {{extension}}.
          - TransferDestinationInferred
            - `type` 'inferred', required — The type of transfer destination.
            - `prompt` string, required — The prompt to be used to help infer the transfer destination. The model will take the global prompt, the call transcript, and this prompt together to deduce the right number to transfer to. Can contain dynamic variables.
        - `ignore_e164_validation` boolean — If true, the e.164 validation will be ignored for the from_number. This can be useful when you want to dial to internal pseudo numbers. This only applies when you are using custom telephony and does not apply when you are using Retell Telephony. If omitted, the default value is false.
        - `custom_sip_headers` object — Custom SIP headers to be added to the call.
        - `transfer_option` union, required
          - object
            - `type` 'cold_transfer', required — The type of the transfer.
            - `show_transferee_as_caller` boolean — If set to true, will show transferee (the user, not the AI agent) as caller when transferring. Requires the telephony side to support caller id override. Retell Twilio numbers support this option. This parameter takes effect only when `cold_transfer_mode` is set to `sip_invite`. When using `sip_refer`, this option is not available. Retell Twilio numbers always use user's number as the caller id when using `sip refer` cold transfer mode.
            - `cold_transfer_mode` 'sip_refer' | 'sip_invite' — The mode of the cold transfer. If set to `sip_refer`, will use SIP REFER to transfer the call. If set to `sip_invite`, will use SIP INVITE to transfer the call.
            - `transfer_ring_duration_ms` integer — Override the ring duration for this specific transfer, in milliseconds. If not set, falls back to the agent-level `ring_duration_ms`.
          - object
            - `type` 'warm_transfer', required — The type of the transfer.
            - `show_transferee_as_caller` boolean — If set to true, will show transferee (the user, not the AI agent) as caller when transferring, requires the telephony side to support caller id override. Retell Twilio numbers support this option.
            - `agent_detection_timeout_ms` number — The time to wait before considering transfer fails.
            - `transfer_ring_duration_ms` integer — Override the ring duration for this specific transfer, in milliseconds. If not set, falls back to the agent-level `ring_duration_ms`.
            - `on_hold_music` 'none' | 'relaxing_sound' | 'uplifting_beats' | 'ringtone' — The music to play while the caller is being transferred.
            - `public_handoff_option` union — If set, when transfer is successful, will say the handoff message to both the transferee and the agent receiving the transfer. Can leave either a static message or a dynamic one based on prompt. Set to null to disable warm handoff.
              - …
            - `private_handoff_option` union — If set, when transfer is connected, will say the handoff message only to the agent receiving the transfer. Can leave either a static message or a dynamic one based on prompt. Set to null to disable warm handoff.
              - …
            - `ivr_option` WarmTransferPrompt
              - …
            - `opt_out_human_detection` boolean — If set to true, will not perform human detection for the transfer. Default to false.
            - `enable_bridge_audio_cue` boolean — Whether to play an audio cue when bridging the call. Defaults to true.
          - object
            - `type` 'agentic_warm_transfer', required — The type of the transfer.
            - `show_transferee_as_caller` boolean — If set to true, will show transferee (the user, not the AI agent) as caller when transferring, requires the telephony side to support caller id override. Retell Twilio numbers support this option.
            - `on_hold_music` 'none' | 'relaxing_sound' | 'uplifting_beats' | 'ringtone' — The music to play while the caller is being transferred.
            - `transfer_ring_duration_ms` integer — Override the ring duration for this specific transfer, in milliseconds. If not set, falls back to the agent-level `ring_duration_ms`.
            - `public_handoff_option` union — If set, when transfer is successful, will say the handoff message to both the transferee and the agent receiving the transfer. Can leave either a static message or a dynamic one based on prompt. Set to null to disable warm handoff.
              - …
            - `agentic_transfer_config` object, required — Configuration for agentic warm transfer. Required for agentic warm transfer.
              - …
            - `enable_bridge_audio_cue` boolean — Whether to play an audio cue when bridging the call. Defaults to true.
        - `speak_during_execution` boolean — If true, will speak during execution.
        - `execution_message_description` string — Describes what to say to user when transferring the call. Only applicable when speak_during_execution is true.
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
      - CheckAvailabilityCalTool
        - `type` 'check_availability_cal', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `cal_api_key` string, required — Cal.com Api key that have access to the cal.com event you want to check availability for.
        - `event_type_id` union, required — Cal.com event type id number for the cal.com event you want to check availability for. Can be a number or a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime.
          - number
          - string
        - `timezone` string — Timezone to be used when checking availability, must be in [IANA timezone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Can also be a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime. If not specified, will check if user specified timezone in call, and if not, will use the timezone of the Retell servers.
      - BookAppointmentCalTool
        - `type` 'book_appointment_cal', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `cal_api_key` string, required — Cal.com Api key that have access to the cal.com event you want to book appointment.
        - `event_type_id` union, required — Cal.com event type id number for the cal.com event you want to book appointment. Can be a number or a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime.
          - number
          - string
        - `timezone` string — Timezone to be used when booking appointment, must be in [IANA timezone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Can also be a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime. If not specified, will check if user specified timezone in call, and if not, will use the timezone of the Retell servers.
      - AgentSwapTool
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges).
        - `type` 'agent_swap', required
        - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `agent_id` string, required — The id of the agent to swap to.
        - `agent_version` union — Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
          - integer
          - string
        - `speak_during_execution` boolean
        - `execution_message_description` string — The message for the agent to speak when executing agent swap.
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - `post_call_analysis_setting` 'both_agents' | 'only_destination_agent', required
        - `webhook_setting` 'both_agents' | 'only_destination_agent' | 'only_source_agent'
        - `keep_current_voice` boolean — If true, keep the current voice when swapping agents. Defaults to false.
        - `keep_current_language` boolean — If true, keep the current language when swapping agents. Defaults to false.
      - PressDigitTool
        - `type` 'press_digit', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `delay_ms` integer — Delay in milliseconds before pressing the digit, because a lot of IVR systems speak very slowly, and a delay can make sure the agent hears the full menu. Default to 1000 ms (1s). Valid range is 0 to 5000 ms (inclusive).
      - SendSMSTool
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges).
        - `type` 'send_sms', required
        - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `speak_during_execution` boolean — If true, the agent will speak a short line before sending the SMS. If omitted, defaults to true (same as end_call / transfer_call tools).
        - `execution_message_description` string — Describes what to say before sending the SMS. Only applicable when speak_during_execution is true.
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - `sms_content` union, required
          - SmsContentPredefined
            - `type` 'predefined'
            - `content` string — The static message to be sent in the SMS. Can contain dynamic variables.
          - SmsContentInferred
            - `type` 'inferred'
            - `prompt` string — The prompt to be used to help infer the SMS content. The model will take the global prompt, the call transcript, and this prompt together to deduce the right message to send. Can contain dynamic variables.
          - SmsContentTemplate
            - `type` 'template', required
            - `template` 'info_collection', required — The template to use for the SMS content. "info_collection" sends a predefined message requesting information from the user.
      - CustomTool
        - `type` 'custom', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `url` string, required — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `description` string — Describes what this tool does and when to call this tool.
        - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' — Method to use for the request, default to POST.
        - `headers` object — Headers to add to the request.
        - `query_params` object — Query parameters to append to the request URL.
        - `parameters` ToolParameter — The parameters the functions accepts, described as a JSON Schema object. See [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting parameters defines a function with an empty parameter list.
          - `type` 'object', required — Type must be "object" for a JSON Schema object.
          - `properties` object, required — The value of properties is an object, where each key is the name of a property and each value is a schema used to validate that property.
          - `required` string[] — List of names of required property when generating this parameter. LLM will do its best to generate the required properties in its function arguments. Property must exist in properties.
        - `response_variables` object — A mapping of variable names to JSON paths in the response body. These values will be extracted from the response and made available as dynamic variables for use.
        - `speak_during_execution` boolean — Determines whether the agent would say sentence like "One moment, let me check that." when executing the function. Recommend to turn on if your function call takes over 1s (including network) to complete, so that your agent remains responsive.
        - `speak_after_execution` boolean — Determines whether the agent would call LLM another time and speak when the result of function is obtained. Usually this needs to get turned on so user can get update for the function call.
        - `execution_message_description` string — The description for the sentence agent say during execution. Only applicable when speak_during_execution is true. Can write what to say or even provide examples. The default is "The message you will say to callee when calling this tool. Make sure it fits into the conversation smoothly.".
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - `timeout_ms` integer — The maximum time in milliseconds the tool can run before it's considered timeout. If the tool times out, the agent would have that info. The minimum value allowed is 1000 ms (1 s), and maximum value allowed is 600,000 ms (10 min). By default, this is set to 120,000 ms (2 min).
        - `args_at_root` boolean — If set to true, the parameters will be passed as root level JSON object instead of nested under "args".
        - `enable_typing_sound` boolean — If true, play a typing sound on the agent audio track while this tool is executing. Useful when the tool takes a noticeable amount of time to prevent silence on the call.
      - CodeTool
        - `type` 'code', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `description` string — Describes what this tool does and when to call this tool.
        - `code` string, required — JavaScript code to execute in the sandbox.
        - `timeout_ms` integer — The maximum time in milliseconds the code can run before it's considered timeout. Defaults to 30,000 ms (30 s).
        - `response_variables` object — A mapping of variable names to JSON paths in the code execution result. These mapped values will be extracted and added as dynamic variables.
        - `speak_during_execution` boolean — Determines whether the agent would say sentence like "One moment, let me check that." when executing the tool.
        - `speak_after_execution` boolean — Determines whether the agent would call LLM another time and speak when the result of function is obtained.
        - `execution_message_description` string — The description for the sentence agent say during execution. Only applicable when speak_during_execution is true.
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - `enable_typing_sound` boolean — If true, play a typing sound on the agent audio track while this tool is executing.
      - ExtractDynamicVariableTool
        - `type` 'extract_dynamic_variable', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `description` string, required — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `variables` AnalysisData[], required — The variables to be extracted.
          - union
            - StringAnalysisData
              - …
            - EnumAnalysisData
              - …
            - BooleanAnalysisData
              - …
            - NumberAnalysisData
              - …
        - `enable_typing_sound` boolean — If true, play a typing sound on the agent audio track while this tool is executing.
      - BridgeTransferTool
        - `type` 'bridge_transfer', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `description` string — Describes what the tool does. This tool is only available to transfer agents (agents with isTransferAgent set to true) in agentic warm transfer mode. When invoked, it bridges the original caller to the transfer target and ends the transfer agent call.
        - `speak_during_execution` boolean — If true, will speak during execution.
        - `execution_message_description` string — Describes what to say to user when bridging the transfer. Only applicable when speak_during_execution is true.
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
      - CancelTransferTool
        - `type` 'cancel_transfer', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `description` string — Describes what the tool does. This tool is only available to transfer agents (agents with isTransferAgent set to true) in agentic warm transfer mode. When invoked, it cancels the transfer, returns the original caller to the main agent, and ends the transfer agent call.
        - `speak_during_execution` boolean — If true, will speak during execution.
        - `execution_message_description` string — Describes what to say to user when cancelling the transfer. Only applicable when speak_during_execution is true.
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
      - MCPTool
        - `type` 'mcp', required
        - `mcp_id` string — Unique id of the MCP.
        - `name` string, required — Name of the MCP tool.
        - `description` string, required — Description of the MCP tool.
        - `input_schema` object — The input schema of the MCP tool.
        - `response_variables` object — Response variables to add to dynamic variables, key is the variable name, value is the path to the variable in the response
        - `speak_during_execution` boolean — Determines whether the agent would say sentence like "One moment, let me check that." when executing the function. Recommend to turn on if your function call takes over 1s (including network) to complete, so that your agent remains responsive.
        - `speak_after_execution` boolean — Determines whether the agent would call LLM another time and speak when the result of function is obtained. Usually this needs to get turned on so user can get update for the function call.
        - `execution_message_description` string — The description for the sentence agent say during execution. Only applicable when speak_during_execution is true. Can write what to say or even provide examples. The default is "The message you will say to callee when calling this tool. Make sure it fits into the conversation smoothly.".
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - `enable_typing_sound` boolean — If true, play a typing sound on the agent audio track while this MCP tool is executing.
  - `states` State[], nullable — States of the LLM. This is to help reduce prompt length and tool choices when the call can be broken into distinct states. With shorter prompts and less tools, the LLM can better focus and follow the rules, minimizing hallucination. If this field is not set, the agent would only have general prompt and general tools (essentially one state).
    - `name` string, required — Name of the state, must be unique for each state. Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
    - `state_prompt` string — Prompt of the state, will be appended to the system prompt of LLM. - System prompt = general prompt + state prompt.
    - `edges` StateEdge[] — Edges of the state define how and what state can be reached from this state.
      - `destination_state_name` string, required — The destination state name when going through transition of state via this edge. State transition internally is implemented as a tool call of LLM, and a tool call with name "transition_to_{destination_state_name}" will get created. Feel free to reference it inside the prompt.
      - `description` string, required — Describes what's the transition and at what time / criteria should this transition happen.
      - `parameters` ToolParameter — The parameters the functions accepts, described as a JSON Schema object. See [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting parameters defines a function with an empty parameter list.
        - `type` 'object', required — Type must be "object" for a JSON Schema object.
        - `properties` object, required — The value of properties is an object, where each key is the name of a property and each value is a schema used to validate that property.
        - `required` string[] — List of names of required property when generating this parameter. LLM will do its best to generate the required properties in its function arguments. Property must exist in properties.
    - `tools` Tool[] — A list of tools specific to this state the model may call (to get external knowledge, call API, etc). You can select from some common predefined tools like end call, transfer call, etc; or you can create your own custom tool for the LLM to use. - Tools of LLM = general tools + state tools + state transitions
      - union
        - EndCallTool
          - `type` 'end_call', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `speak_during_execution` boolean — If true, will speak during execution.
          - `execution_message_description` string — Describes what to say to user when ending the call. Only applicable when speak_during_execution is true.
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - TransferCallTool
          - `type` 'transfer_call', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges).
          - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `transfer_destination` union, required
            - TransferDestinationPredefined
              - …
            - TransferDestinationInferred
              - …
          - `ignore_e164_validation` boolean — If true, the e.164 validation will be ignored for the from_number. This can be useful when you want to dial to internal pseudo numbers. This only applies when you are using custom telephony and does not apply when you are using Retell Telephony. If omitted, the default value is false.
          - `custom_sip_headers` object — Custom SIP headers to be added to the call.
          - `transfer_option` union, required
            - object
              - …
            - object
              - …
            - object
              - …
          - `speak_during_execution` boolean — If true, will speak during execution.
          - `execution_message_description` string — Describes what to say to user when transferring the call. Only applicable when speak_during_execution is true.
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - CheckAvailabilityCalTool
          - `type` 'check_availability_cal', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `cal_api_key` string, required — Cal.com Api key that have access to the cal.com event you want to check availability for.
          - `event_type_id` union, required — Cal.com event type id number for the cal.com event you want to check availability for. Can be a number or a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime.
            - number
            - string
          - `timezone` string — Timezone to be used when checking availability, must be in [IANA timezone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Can also be a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime. If not specified, will check if user specified timezone in call, and if not, will use the timezone of the Retell servers.
        - BookAppointmentCalTool
          - `type` 'book_appointment_cal', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `cal_api_key` string, required — Cal.com Api key that have access to the cal.com event you want to book appointment.
          - `event_type_id` union, required — Cal.com event type id number for the cal.com event you want to book appointment. Can be a number or a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime.
            - number
            - string
          - `timezone` string — Timezone to be used when booking appointment, must be in [IANA timezone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Can also be a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime. If not specified, will check if user specified timezone in call, and if not, will use the timezone of the Retell servers.
        - AgentSwapTool
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges).
          - `type` 'agent_swap', required
          - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `agent_id` string, required — The id of the agent to swap to.
          - `agent_version` union — Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
            - integer
            - string
          - `speak_during_execution` boolean
          - `execution_message_description` string — The message for the agent to speak when executing agent swap.
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
          - `post_call_analysis_setting` 'both_agents' | 'only_destination_agent', required
          - `webhook_setting` 'both_agents' | 'only_destination_agent' | 'only_source_agent'
          - `keep_current_voice` boolean — If true, keep the current voice when swapping agents. Defaults to false.
          - `keep_current_language` boolean — If true, keep the current language when swapping agents. Defaults to false.
        - PressDigitTool
          - `type` 'press_digit', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `delay_ms` integer — Delay in milliseconds before pressing the digit, because a lot of IVR systems speak very slowly, and a delay can make sure the agent hears the full menu. Default to 1000 ms (1s). Valid range is 0 to 5000 ms (inclusive).
        - SendSMSTool
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges).
          - `type` 'send_sms', required
          - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `speak_during_execution` boolean — If true, the agent will speak a short line before sending the SMS. If omitted, defaults to true (same as end_call / transfer_call tools).
          - `execution_message_description` string — Describes what to say before sending the SMS. Only applicable when speak_during_execution is true.
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
          - `sms_content` union, required
            - SmsContentPredefined
              - …
            - SmsContentInferred
              - …
            - SmsContentTemplate
              - …
        - CustomTool
          - `type` 'custom', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `url` string, required — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `description` string — Describes what this tool does and when to call this tool.
          - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' — Method to use for the request, default to POST.
          - `headers` object — Headers to add to the request.
          - `query_params` object — Query parameters to append to the request URL.
          - `parameters` ToolParameter — The parameters the functions accepts, described as a JSON Schema object. See [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting parameters defines a function with an empty parameter list.
            - `type` 'object', required — Type must be "object" for a JSON Schema object.
            - `properties` object, required — The value of properties is an object, where each key is the name of a property and each value is a schema used to validate that property.
            - `required` string[] — List of names of required property when generating this parameter. LLM will do its best to generate the required properties in its function arguments. Property must exist in properties.
          - `response_variables` object — A mapping of variable names to JSON paths in the response body. These values will be extracted from the response and made available as dynamic variables for use.
          - `speak_during_execution` boolean — Determines whether the agent would say sentence like "One moment, let me check that." when executing the function. Recommend to turn on if your function call takes over 1s (including network) to complete, so that your agent remains responsive.
          - `speak_after_execution` boolean — Determines whether the agent would call LLM another time and speak when the result of function is obtained. Usually this needs to get turned on so user can get update for the function call.
          - `execution_message_description` string — The description for the sentence agent say during execution. Only applicable when speak_during_execution is true. Can write what to say or even provide examples. The default is "The message you will say to callee when calling this tool. Make sure it fits into the conversation smoothly.".
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
          - `timeout_ms` integer — The maximum time in milliseconds the tool can run before it's considered timeout. If the tool times out, the agent would have that info. The minimum value allowed is 1000 ms (1 s), and maximum value allowed is 600,000 ms (10 min). By default, this is set to 120,000 ms (2 min).
          - `args_at_root` boolean — If set to true, the parameters will be passed as root level JSON object instead of nested under "args".
          - `enable_typing_sound` boolean — If true, play a typing sound on the agent audio track while this tool is executing. Useful when the tool takes a noticeable amount of time to prevent silence on the call.
        - CodeTool
          - `type` 'code', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `description` string — Describes what this tool does and when to call this tool.
          - `code` string, required — JavaScript code to execute in the sandbox.
          - `timeout_ms` integer — The maximum time in milliseconds the code can run before it's considered timeout. Defaults to 30,000 ms (30 s).
          - `response_variables` object — A mapping of variable names to JSON paths in the code execution result. These mapped values will be extracted and added as dynamic variables.
          - `speak_during_execution` boolean — Determines whether the agent would say sentence like "One moment, let me check that." when executing the tool.
          - `speak_after_execution` boolean — Determines whether the agent would call LLM another time and speak when the result of function is obtained.
          - `execution_message_description` string — The description for the sentence agent say during execution. Only applicable when speak_during_execution is true.
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
          - `enable_typing_sound` boolean — If true, play a typing sound on the agent audio track while this tool is executing.
        - ExtractDynamicVariableTool
          - `type` 'extract_dynamic_variable', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `description` string, required — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `variables` AnalysisData[], required — The variables to be extracted.
            - union
              - …
          - `enable_typing_sound` boolean — If true, play a typing sound on the agent audio track while this tool is executing.
        - BridgeTransferTool
          - `type` 'bridge_transfer', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `description` string — Describes what the tool does. This tool is only available to transfer agents (agents with isTransferAgent set to true) in agentic warm transfer mode. When invoked, it bridges the original caller to the transfer target and ends the transfer agent call.
          - `speak_during_execution` boolean — If true, will speak during execution.
          - `execution_message_description` string — Describes what to say to user when bridging the transfer. Only applicable when speak_during_execution is true.
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - CancelTransferTool
          - `type` 'cancel_transfer', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `description` string — Describes what the tool does. This tool is only available to transfer agents (agents with isTransferAgent set to true) in agentic warm transfer mode. When invoked, it cancels the transfer, returns the original caller to the main agent, and ends the transfer agent call.
          - `speak_during_execution` boolean — If true, will speak during execution.
          - `execution_message_description` string — Describes what to say to user when cancelling the transfer. Only applicable when speak_during_execution is true.
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - MCPTool
          - `type` 'mcp', required
          - `mcp_id` string — Unique id of the MCP.
          - `name` string, required — Name of the MCP tool.
          - `description` string, required — Description of the MCP tool.
          - `input_schema` object — The input schema of the MCP tool.
          - `response_variables` object — Response variables to add to dynamic variables, key is the variable name, value is the path to the variable in the response
          - `speak_during_execution` boolean — Determines whether the agent would say sentence like "One moment, let me check that." when executing the function. Recommend to turn on if your function call takes over 1s (including network) to complete, so that your agent remains responsive.
          - `speak_after_execution` boolean — Determines whether the agent would call LLM another time and speak when the result of function is obtained. Usually this needs to get turned on so user can get update for the function call.
          - `execution_message_description` string — The description for the sentence agent say during execution. Only applicable when speak_during_execution is true. Can write what to say or even provide examples. The default is "The message you will say to callee when calling this tool. Make sure it fits into the conversation smoothly.".
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
          - `enable_typing_sound` boolean — If true, play a typing sound on the agent audio track while this MCP tool is executing.
  - `starting_state` string, nullable — Name of the starting state. Required if states is not empty.
  - `default_dynamic_variables` object, nullable — Default dynamic variables represented as key-value pairs of strings. These are injected into your Retell LLM prompt and tool description when specific values are not provided in a request. Only applicable for Retell LLM.
  - `mcps` MCP[], nullable — A list of MCPs to use for this LLM.
    - `name` string, required
    - `url` string, required — The URL of the MCP server.
    - `headers` object — Headers to add to the MCP connection request.
    - `query_params` object — Query parameters to append to the MCP connection request URL.
    - `timeout_ms` integer — Maximum time to wait for a connection to be established (in milliseconds). Default to 120,000 ms (2 minutes).

## Response `201`

Successfully created a new Retell LLM Response Engine.

- RetellLLMResponse — Override properties for Retell LLM configuration in agent override requests.
  - `llm_id` string, required — Unique id of Retell LLM Response Engine.
  - `version` integer — Version of the Retell LLM Response Engine.
  - `is_published` boolean — Whether the Retell LLM Response Engine is published.
  - `model` 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-5' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5.5' | 'claude-4.5-sonnet' | 'claude-4.6-sonnet' | 'claude-4.5-haiku' | 'gemini-2.5-flash-lite' | 'gemini-3.0-flash' | 'gemini-3.1-flash-lite' | 'null', nullable — Available LLM models for agents.
  - `s2s_model` 'gpt-realtime-2' | 'gpt-realtime-1.5' | 'gpt-realtime' | 'gpt-realtime-mini' | 'null', nullable — Select the underlying speech to speech model. Can only set this or model, not both.
  - `model_temperature` number — If set, will control the randomness of the response. Value ranging from [0,1]. Lower value means more deterministic, while higher value means more random. If unset, default value 0 will apply. Note that for tool calling, a lower value is recommended.
  - `model_high_priority` boolean, nullable — If set to true, will use high priority pool with more dedicated resource to ensure lower and more consistent latency, default to false. This feature usually comes with a higher cost.
  - `tool_call_strict_mode` boolean, nullable — Whether to use strict mode for tool calls. Only applicable when using certain supported models.
  - `knowledge_base_ids` string[], nullable — A list of knowledge base ids to use for this resource.
  - `kb_config` KBConfig
    - `top_k` integer — Max number of knowledge base chunks to retrieve
    - `filter_score` number — Similarity threshold for filtering search results
  - `start_speaker` 'user' | 'agent' — The speaker who starts the conversation. Required. Must be either 'user' or 'agent'.
  - `begin_after_user_silence_ms` integer, nullable — If set, the AI will begin the conversation after waiting for the user for the duration (in milliseconds) specified by this attribute. This only applies if the agent is configured to wait for the user to speak first. If not set, the agent will wait indefinitely for the user to speak.
  - `begin_message` string, nullable — First utterance said by the agent in the call. If not set, LLM will dynamically generate a message. If set to "", agent will wait for user to speak first.
  - `general_prompt` string, nullable — General prompt appended to system prompt no matter what state the agent is in. - System prompt (with state) = general prompt + state prompt. - System prompt (no state) = general prompt.
  - `general_tools` Tool[], nullable — A list of tools the model may call (to get external knowledge, call API, etc). You can select from some common predefined tools like end call, transfer call, etc; or you can create your own custom tool for the LLM to use. - Tools of LLM (with state) = general tools + state tools + state transitions - Tools of LLM (no state) = general tools
    - union
      - EndCallTool
        - `type` 'end_call', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `speak_during_execution` boolean — If true, will speak during execution.
        - `execution_message_description` string — Describes what to say to user when ending the call. Only applicable when speak_during_execution is true.
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
      - TransferCallTool
        - `type` 'transfer_call', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges).
        - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `transfer_destination` union, required
          - TransferDestinationPredefined
            - `type` 'predefined', required — The type of transfer destination.
            - `number` string, required — The number to transfer to in E.164 format or a dynamic variable like {{transfer_number}}.
            - `extension` string — Extension digits to dial after the main number connects. Sent via DTMF. Allow digits, '*', '#', or a dynamic variable like {{extension}}.
          - TransferDestinationInferred
            - `type` 'inferred', required — The type of transfer destination.
            - `prompt` string, required — The prompt to be used to help infer the transfer destination. The model will take the global prompt, the call transcript, and this prompt together to deduce the right number to transfer to. Can contain dynamic variables.
        - `ignore_e164_validation` boolean — If true, the e.164 validation will be ignored for the from_number. This can be useful when you want to dial to internal pseudo numbers. This only applies when you are using custom telephony and does not apply when you are using Retell Telephony. If omitted, the default value is false.
        - `custom_sip_headers` object — Custom SIP headers to be added to the call.
        - `transfer_option` union, required
          - object
            - `type` 'cold_transfer', required — The type of the transfer.
            - `show_transferee_as_caller` boolean — If set to true, will show transferee (the user, not the AI agent) as caller when transferring. Requires the telephony side to support caller id override. Retell Twilio numbers support this option. This parameter takes effect only when `cold_transfer_mode` is set to `sip_invite`. When using `sip_refer`, this option is not available. Retell Twilio numbers always use user's number as the caller id when using `sip refer` cold transfer mode.
            - `cold_transfer_mode` 'sip_refer' | 'sip_invite' — The mode of the cold transfer. If set to `sip_refer`, will use SIP REFER to transfer the call. If set to `sip_invite`, will use SIP INVITE to transfer the call.
            - `transfer_ring_duration_ms` integer — Override the ring duration for this specific transfer, in milliseconds. If not set, falls back to the agent-level `ring_duration_ms`.
          - object
            - `type` 'warm_transfer', required — The type of the transfer.
            - `show_transferee_as_caller` boolean — If set to true, will show transferee (the user, not the AI agent) as caller when transferring, requires the telephony side to support caller id override. Retell Twilio numbers support this option.
            - `agent_detection_timeout_ms` number — The time to wait before considering transfer fails.
            - `transfer_ring_duration_ms` integer — Override the ring duration for this specific transfer, in milliseconds. If not set, falls back to the agent-level `ring_duration_ms`.
            - `on_hold_music` 'none' | 'relaxing_sound' | 'uplifting_beats' | 'ringtone' — The music to play while the caller is being transferred.
            - `public_handoff_option` union — If set, when transfer is successful, will say the handoff message to both the transferee and the agent receiving the transfer. Can leave either a static message or a dynamic one based on prompt. Set to null to disable warm handoff.
              - …
            - `private_handoff_option` union — If set, when transfer is connected, will say the handoff message only to the agent receiving the transfer. Can leave either a static message or a dynamic one based on prompt. Set to null to disable warm handoff.
              - …
            - `ivr_option` WarmTransferPrompt
              - …
            - `opt_out_human_detection` boolean — If set to true, will not perform human detection for the transfer. Default to false.
            - `enable_bridge_audio_cue` boolean — Whether to play an audio cue when bridging the call. Defaults to true.
          - object
            - `type` 'agentic_warm_transfer', required — The type of the transfer.
            - `show_transferee_as_caller` boolean — If set to true, will show transferee (the user, not the AI agent) as caller when transferring, requires the telephony side to support caller id override. Retell Twilio numbers support this option.
            - `on_hold_music` 'none' | 'relaxing_sound' | 'uplifting_beats' | 'ringtone' — The music to play while the caller is being transferred.
            - `transfer_ring_duration_ms` integer — Override the ring duration for this specific transfer, in milliseconds. If not set, falls back to the agent-level `ring_duration_ms`.
            - `public_handoff_option` union — If set, when transfer is successful, will say the handoff message to both the transferee and the agent receiving the transfer. Can leave either a static message or a dynamic one based on prompt. Set to null to disable warm handoff.
              - …
            - `agentic_transfer_config` object, required — Configuration for agentic warm transfer. Required for agentic warm transfer.
              - …
            - `enable_bridge_audio_cue` boolean — Whether to play an audio cue when bridging the call. Defaults to true.
        - `speak_during_execution` boolean — If true, will speak during execution.
        - `execution_message_description` string — Describes what to say to user when transferring the call. Only applicable when speak_during_execution is true.
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
      - CheckAvailabilityCalTool
        - `type` 'check_availability_cal', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `cal_api_key` string, required — Cal.com Api key that have access to the cal.com event you want to check availability for.
        - `event_type_id` union, required — Cal.com event type id number for the cal.com event you want to check availability for. Can be a number or a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime.
          - number
          - string
        - `timezone` string — Timezone to be used when checking availability, must be in [IANA timezone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Can also be a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime. If not specified, will check if user specified timezone in call, and if not, will use the timezone of the Retell servers.
      - BookAppointmentCalTool
        - `type` 'book_appointment_cal', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `cal_api_key` string, required — Cal.com Api key that have access to the cal.com event you want to book appointment.
        - `event_type_id` union, required — Cal.com event type id number for the cal.com event you want to book appointment. Can be a number or a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime.
          - number
          - string
        - `timezone` string — Timezone to be used when booking appointment, must be in [IANA timezone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Can also be a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime. If not specified, will check if user specified timezone in call, and if not, will use the timezone of the Retell servers.
      - AgentSwapTool
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges).
        - `type` 'agent_swap', required
        - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `agent_id` string, required — The id of the agent to swap to.
        - `agent_version` union — Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
          - integer
          - string
        - `speak_during_execution` boolean
        - `execution_message_description` string — The message for the agent to speak when executing agent swap.
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - `post_call_analysis_setting` 'both_agents' | 'only_destination_agent', required
        - `webhook_setting` 'both_agents' | 'only_destination_agent' | 'only_source_agent'
        - `keep_current_voice` boolean — If true, keep the current voice when swapping agents. Defaults to false.
        - `keep_current_language` boolean — If true, keep the current language when swapping agents. Defaults to false.
      - PressDigitTool
        - `type` 'press_digit', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `delay_ms` integer — Delay in milliseconds before pressing the digit, because a lot of IVR systems speak very slowly, and a delay can make sure the agent hears the full menu. Default to 1000 ms (1s). Valid range is 0 to 5000 ms (inclusive).
      - SendSMSTool
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges).
        - `type` 'send_sms', required
        - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `speak_during_execution` boolean — If true, the agent will speak a short line before sending the SMS. If omitted, defaults to true (same as end_call / transfer_call tools).
        - `execution_message_description` string — Describes what to say before sending the SMS. Only applicable when speak_during_execution is true.
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - `sms_content` union, required
          - SmsContentPredefined
            - `type` 'predefined'
            - `content` string — The static message to be sent in the SMS. Can contain dynamic variables.
          - SmsContentInferred
            - `type` 'inferred'
            - `prompt` string — The prompt to be used to help infer the SMS content. The model will take the global prompt, the call transcript, and this prompt together to deduce the right message to send. Can contain dynamic variables.
          - SmsContentTemplate
            - `type` 'template', required
            - `template` 'info_collection', required — The template to use for the SMS content. "info_collection" sends a predefined message requesting information from the user.
      - CustomTool
        - `type` 'custom', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `url` string, required — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `description` string — Describes what this tool does and when to call this tool.
        - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' — Method to use for the request, default to POST.
        - `headers` object — Headers to add to the request.
        - `query_params` object — Query parameters to append to the request URL.
        - `parameters` ToolParameter — The parameters the functions accepts, described as a JSON Schema object. See [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting parameters defines a function with an empty parameter list.
          - `type` 'object', required — Type must be "object" for a JSON Schema object.
          - `properties` object, required — The value of properties is an object, where each key is the name of a property and each value is a schema used to validate that property.
          - `required` string[] — List of names of required property when generating this parameter. LLM will do its best to generate the required properties in its function arguments. Property must exist in properties.
        - `response_variables` object — A mapping of variable names to JSON paths in the response body. These values will be extracted from the response and made available as dynamic variables for use.
        - `speak_during_execution` boolean — Determines whether the agent would say sentence like "One moment, let me check that." when executing the function. Recommend to turn on if your function call takes over 1s (including network) to complete, so that your agent remains responsive.
        - `speak_after_execution` boolean — Determines whether the agent would call LLM another time and speak when the result of function is obtained. Usually this needs to get turned on so user can get update for the function call.
        - `execution_message_description` string — The description for the sentence agent say during execution. Only applicable when speak_during_execution is true. Can write what to say or even provide examples. The default is "The message you will say to callee when calling this tool. Make sure it fits into the conversation smoothly.".
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - `timeout_ms` integer — The maximum time in milliseconds the tool can run before it's considered timeout. If the tool times out, the agent would have that info. The minimum value allowed is 1000 ms (1 s), and maximum value allowed is 600,000 ms (10 min). By default, this is set to 120,000 ms (2 min).
        - `args_at_root` boolean — If set to true, the parameters will be passed as root level JSON object instead of nested under "args".
        - `enable_typing_sound` boolean — If true, play a typing sound on the agent audio track while this tool is executing. Useful when the tool takes a noticeable amount of time to prevent silence on the call.
      - CodeTool
        - `type` 'code', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `description` string — Describes what this tool does and when to call this tool.
        - `code` string, required — JavaScript code to execute in the sandbox.
        - `timeout_ms` integer — The maximum time in milliseconds the code can run before it's considered timeout. Defaults to 30,000 ms (30 s).
        - `response_variables` object — A mapping of variable names to JSON paths in the code execution result. These mapped values will be extracted and added as dynamic variables.
        - `speak_during_execution` boolean — Determines whether the agent would say sentence like "One moment, let me check that." when executing the tool.
        - `speak_after_execution` boolean — Determines whether the agent would call LLM another time and speak when the result of function is obtained.
        - `execution_message_description` string — The description for the sentence agent say during execution. Only applicable when speak_during_execution is true.
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - `enable_typing_sound` boolean — If true, play a typing sound on the agent audio track while this tool is executing.
      - ExtractDynamicVariableTool
        - `type` 'extract_dynamic_variable', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `description` string, required — Describes what the tool does, sometimes can also include information about when to call the tool.
        - `variables` AnalysisData[], required — The variables to be extracted.
          - union
            - StringAnalysisData
              - …
            - EnumAnalysisData
              - …
            - BooleanAnalysisData
              - …
            - NumberAnalysisData
              - …
        - `enable_typing_sound` boolean — If true, play a typing sound on the agent audio track while this tool is executing.
      - BridgeTransferTool
        - `type` 'bridge_transfer', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `description` string — Describes what the tool does. This tool is only available to transfer agents (agents with isTransferAgent set to true) in agentic warm transfer mode. When invoked, it bridges the original caller to the transfer target and ends the transfer agent call.
        - `speak_during_execution` boolean — If true, will speak during execution.
        - `execution_message_description` string — Describes what to say to user when bridging the transfer. Only applicable when speak_during_execution is true.
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
      - CancelTransferTool
        - `type` 'cancel_transfer', required
        - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
        - `description` string — Describes what the tool does. This tool is only available to transfer agents (agents with isTransferAgent set to true) in agentic warm transfer mode. When invoked, it cancels the transfer, returns the original caller to the main agent, and ends the transfer agent call.
        - `speak_during_execution` boolean — If true, will speak during execution.
        - `execution_message_description` string — Describes what to say to user when cancelling the transfer. Only applicable when speak_during_execution is true.
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
      - MCPTool
        - `type` 'mcp', required
        - `mcp_id` string — Unique id of the MCP.
        - `name` string, required — Name of the MCP tool.
        - `description` string, required — Description of the MCP tool.
        - `input_schema` object — The input schema of the MCP tool.
        - `response_variables` object — Response variables to add to dynamic variables, key is the variable name, value is the path to the variable in the response
        - `speak_during_execution` boolean — Determines whether the agent would say sentence like "One moment, let me check that." when executing the function. Recommend to turn on if your function call takes over 1s (including network) to complete, so that your agent remains responsive.
        - `speak_after_execution` boolean — Determines whether the agent would call LLM another time and speak when the result of function is obtained. Usually this needs to get turned on so user can get update for the function call.
        - `execution_message_description` string — The description for the sentence agent say during execution. Only applicable when speak_during_execution is true. Can write what to say or even provide examples. The default is "The message you will say to callee when calling this tool. Make sure it fits into the conversation smoothly.".
        - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - `enable_typing_sound` boolean — If true, play a typing sound on the agent audio track while this MCP tool is executing.
  - `states` State[], nullable — States of the LLM. This is to help reduce prompt length and tool choices when the call can be broken into distinct states. With shorter prompts and less tools, the LLM can better focus and follow the rules, minimizing hallucination. If this field is not set, the agent would only have general prompt and general tools (essentially one state).
    - `name` string, required — Name of the state, must be unique for each state. Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
    - `state_prompt` string — Prompt of the state, will be appended to the system prompt of LLM. - System prompt = general prompt + state prompt.
    - `edges` StateEdge[] — Edges of the state define how and what state can be reached from this state.
      - `destination_state_name` string, required — The destination state name when going through transition of state via this edge. State transition internally is implemented as a tool call of LLM, and a tool call with name "transition_to_{destination_state_name}" will get created. Feel free to reference it inside the prompt.
      - `description` string, required — Describes what's the transition and at what time / criteria should this transition happen.
      - `parameters` ToolParameter — The parameters the functions accepts, described as a JSON Schema object. See [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting parameters defines a function with an empty parameter list.
        - `type` 'object', required — Type must be "object" for a JSON Schema object.
        - `properties` object, required — The value of properties is an object, where each key is the name of a property and each value is a schema used to validate that property.
        - `required` string[] — List of names of required property when generating this parameter. LLM will do its best to generate the required properties in its function arguments. Property must exist in properties.
    - `tools` Tool[] — A list of tools specific to this state the model may call (to get external knowledge, call API, etc). You can select from some common predefined tools like end call, transfer call, etc; or you can create your own custom tool for the LLM to use. - Tools of LLM = general tools + state tools + state transitions
      - union
        - EndCallTool
          - `type` 'end_call', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `speak_during_execution` boolean — If true, will speak during execution.
          - `execution_message_description` string — Describes what to say to user when ending the call. Only applicable when speak_during_execution is true.
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - TransferCallTool
          - `type` 'transfer_call', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges).
          - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `transfer_destination` union, required
            - TransferDestinationPredefined
              - …
            - TransferDestinationInferred
              - …
          - `ignore_e164_validation` boolean — If true, the e.164 validation will be ignored for the from_number. This can be useful when you want to dial to internal pseudo numbers. This only applies when you are using custom telephony and does not apply when you are using Retell Telephony. If omitted, the default value is false.
          - `custom_sip_headers` object — Custom SIP headers to be added to the call.
          - `transfer_option` union, required
            - object
              - …
            - object
              - …
            - object
              - …
          - `speak_during_execution` boolean — If true, will speak during execution.
          - `execution_message_description` string — Describes what to say to user when transferring the call. Only applicable when speak_during_execution is true.
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - CheckAvailabilityCalTool
          - `type` 'check_availability_cal', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `cal_api_key` string, required — Cal.com Api key that have access to the cal.com event you want to check availability for.
          - `event_type_id` union, required — Cal.com event type id number for the cal.com event you want to check availability for. Can be a number or a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime.
            - number
            - string
          - `timezone` string — Timezone to be used when checking availability, must be in [IANA timezone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Can also be a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime. If not specified, will check if user specified timezone in call, and if not, will use the timezone of the Retell servers.
        - BookAppointmentCalTool
          - `type` 'book_appointment_cal', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `cal_api_key` string, required — Cal.com Api key that have access to the cal.com event you want to book appointment.
          - `event_type_id` union, required — Cal.com event type id number for the cal.com event you want to book appointment. Can be a number or a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime.
            - number
            - string
          - `timezone` string — Timezone to be used when booking appointment, must be in [IANA timezone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Can also be a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime. If not specified, will check if user specified timezone in call, and if not, will use the timezone of the Retell servers.
        - AgentSwapTool
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges).
          - `type` 'agent_swap', required
          - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `agent_id` string, required — The id of the agent to swap to.
          - `agent_version` union — Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
            - integer
            - string
          - `speak_during_execution` boolean
          - `execution_message_description` string — The message for the agent to speak when executing agent swap.
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
          - `post_call_analysis_setting` 'both_agents' | 'only_destination_agent', required
          - `webhook_setting` 'both_agents' | 'only_destination_agent' | 'only_source_agent'
          - `keep_current_voice` boolean — If true, keep the current voice when swapping agents. Defaults to false.
          - `keep_current_language` boolean — If true, keep the current language when swapping agents. Defaults to false.
        - PressDigitTool
          - `type` 'press_digit', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `delay_ms` integer — Delay in milliseconds before pressing the digit, because a lot of IVR systems speak very slowly, and a delay can make sure the agent hears the full menu. Default to 1000 ms (1s). Valid range is 0 to 5000 ms (inclusive).
        - SendSMSTool
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges).
          - `type` 'send_sms', required
          - `description` string — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `speak_during_execution` boolean — If true, the agent will speak a short line before sending the SMS. If omitted, defaults to true (same as end_call / transfer_call tools).
          - `execution_message_description` string — Describes what to say before sending the SMS. Only applicable when speak_during_execution is true.
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
          - `sms_content` union, required
            - SmsContentPredefined
              - …
            - SmsContentInferred
              - …
            - SmsContentTemplate
              - …
        - CustomTool
          - `type` 'custom', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `url` string, required — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `description` string — Describes what this tool does and when to call this tool.
          - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' — Method to use for the request, default to POST.
          - `headers` object — Headers to add to the request.
          - `query_params` object — Query parameters to append to the request URL.
          - `parameters` ToolParameter — The parameters the functions accepts, described as a JSON Schema object. See [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting parameters defines a function with an empty parameter list.
            - `type` 'object', required — Type must be "object" for a JSON Schema object.
            - `properties` object, required — The value of properties is an object, where each key is the name of a property and each value is a schema used to validate that property.
            - `required` string[] — List of names of required property when generating this parameter. LLM will do its best to generate the required properties in its function arguments. Property must exist in properties.
          - `response_variables` object — A mapping of variable names to JSON paths in the response body. These values will be extracted from the response and made available as dynamic variables for use.
          - `speak_during_execution` boolean — Determines whether the agent would say sentence like "One moment, let me check that." when executing the function. Recommend to turn on if your function call takes over 1s (including network) to complete, so that your agent remains responsive.
          - `speak_after_execution` boolean — Determines whether the agent would call LLM another time and speak when the result of function is obtained. Usually this needs to get turned on so user can get update for the function call.
          - `execution_message_description` string — The description for the sentence agent say during execution. Only applicable when speak_during_execution is true. Can write what to say or even provide examples. The default is "The message you will say to callee when calling this tool. Make sure it fits into the conversation smoothly.".
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
          - `timeout_ms` integer — The maximum time in milliseconds the tool can run before it's considered timeout. If the tool times out, the agent would have that info. The minimum value allowed is 1000 ms (1 s), and maximum value allowed is 600,000 ms (10 min). By default, this is set to 120,000 ms (2 min).
          - `args_at_root` boolean — If set to true, the parameters will be passed as root level JSON object instead of nested under "args".
          - `enable_typing_sound` boolean — If true, play a typing sound on the agent audio track while this tool is executing. Useful when the tool takes a noticeable amount of time to prevent silence on the call.
        - CodeTool
          - `type` 'code', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `description` string — Describes what this tool does and when to call this tool.
          - `code` string, required — JavaScript code to execute in the sandbox.
          - `timeout_ms` integer — The maximum time in milliseconds the code can run before it's considered timeout. Defaults to 30,000 ms (30 s).
          - `response_variables` object — A mapping of variable names to JSON paths in the code execution result. These mapped values will be extracted and added as dynamic variables.
          - `speak_during_execution` boolean — Determines whether the agent would say sentence like "One moment, let me check that." when executing the tool.
          - `speak_after_execution` boolean — Determines whether the agent would call LLM another time and speak when the result of function is obtained.
          - `execution_message_description` string — The description for the sentence agent say during execution. Only applicable when speak_during_execution is true.
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
          - `enable_typing_sound` boolean — If true, play a typing sound on the agent audio track while this tool is executing.
        - ExtractDynamicVariableTool
          - `type` 'extract_dynamic_variable', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `description` string, required — Describes what the tool does, sometimes can also include information about when to call the tool.
          - `variables` AnalysisData[], required — The variables to be extracted.
            - union
              - …
          - `enable_typing_sound` boolean — If true, play a typing sound on the agent audio track while this tool is executing.
        - BridgeTransferTool
          - `type` 'bridge_transfer', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `description` string — Describes what the tool does. This tool is only available to transfer agents (agents with isTransferAgent set to true) in agentic warm transfer mode. When invoked, it bridges the original caller to the transfer target and ends the transfer agent call.
          - `speak_during_execution` boolean — If true, will speak during execution.
          - `execution_message_description` string — Describes what to say to user when bridging the transfer. Only applicable when speak_during_execution is true.
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - CancelTransferTool
          - `type` 'cancel_transfer', required
          - `name` string, required — Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
          - `description` string — Describes what the tool does. This tool is only available to transfer agents (agents with isTransferAgent set to true) in agentic warm transfer mode. When invoked, it cancels the transfer, returns the original caller to the main agent, and ends the transfer agent call.
          - `speak_during_execution` boolean — If true, will speak during execution.
          - `execution_message_description` string — Describes what to say to user when cancelling the transfer. Only applicable when speak_during_execution is true.
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
        - MCPTool
          - `type` 'mcp', required
          - `mcp_id` string — Unique id of the MCP.
          - `name` string, required — Name of the MCP tool.
          - `description` string, required — Description of the MCP tool.
          - `input_schema` object — The input schema of the MCP tool.
          - `response_variables` object — Response variables to add to dynamic variables, key is the variable name, value is the path to the variable in the response
          - `speak_during_execution` boolean — Determines whether the agent would say sentence like "One moment, let me check that." when executing the function. Recommend to turn on if your function call takes over 1s (including network) to complete, so that your agent remains responsive.
          - `speak_after_execution` boolean — Determines whether the agent would call LLM another time and speak when the result of function is obtained. Usually this needs to get turned on so user can get update for the function call.
          - `execution_message_description` string — The description for the sentence agent say during execution. Only applicable when speak_during_execution is true. Can write what to say or even provide examples. The default is "The message you will say to callee when calling this tool. Make sure it fits into the conversation smoothly.".
          - `execution_message_type` 'prompt' | 'static_text' — Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
          - `enable_typing_sound` boolean — If true, play a typing sound on the agent audio track while this MCP tool is executing.
  - `starting_state` string, nullable — Name of the starting state. Required if states is not empty.
  - `default_dynamic_variables` object, nullable — Default dynamic variables represented as key-value pairs of strings. These are injected into your Retell LLM prompt and tool description when specific values are not provided in a request. Only applicable for Retell LLM.
  - `mcps` MCP[], nullable — A list of MCPs to use for this LLM.
    - `name` string, required
    - `url` string, required — The URL of the MCP server.
    - `headers` object — Headers to add to the MCP connection request.
    - `query_params` object — Query parameters to append to the MCP connection request URL.
    - `timeout_ms` integer — Maximum time to wait for a connection to be established (in milliseconds). Default to 120,000 ms (2 minutes).
  - `last_modification_timestamp` integer, required — Last modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `500` — Internal Server Error

---

[API](https://skmtc.net/retellai/apis/retell-sdk.md) · [All operations](https://skmtc.net/retellai/apis/retell-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/retellai/retell-sdk/versions/2a182bedbfc5/schema)