Create an outbound phone call using a Retell AI voice agent.
WHEN TO USE: User asks you to make, place, or initiate a phone call.
WORKFLOW (typical sequence):
1. list_agents → find the right agent, note its agent_id
2. get_agent → check config, get its retell_llm_id
3. update_retell_llm → set the conversation prompt/instructions
4. Wait 2-3 seconds (let config propagate)
5. create_phone_call → initiate the call
6. Poll get_call every 5-10s until status is "ended"
EXAMPLE:
{ "from_number": "+14155551234", "to_number": "+14155559876", "override_agent_id": "agent_xxx", "override_agent_version": 2 }
COMMON MISTAKES:
- Skipping update_retell_llm first: the agent will use the previous call's prompt
- Passing override_agent_id without override_agent_version: Retell may route to the wrong or unpublished version
- Assuming the phone number is already bound: check list_phone_numbers/get_phone_number
- Updating the agent or LLM but not publishing the version before calling
ERROR RECOVERY:
- 401: API key is missing or invalid → the user adds it in Settings → Connectors in the app; do not ask for it in chat
- 404: resource/version/binding not found → check phone number outbound_agents, get_agent_versions, then publish_agent or pass override_agent_version
- 422: bad parameter shape/value → verify E.164 phone numbers and valid agent/version IDs
CRITICAL: If the call returns 404, the most common causes are:
- The phone number has no outbound agent bound → use update_phone_number to bind one
- The agent version is unpublished → use publish_agent first, or pass override_agent_version
- Always pass override_agent_id AND override_agent_version for reliable routing
RELATED TOOLS:
- update_retell_llm: Set the prompt before placing the call
- get_phone_number/list_phone_numbers: Verify outbound bindings and from_number
- publish_agent/get_agent_versions: Confirm the version is live
- get_call: Monitor status and retrieve transcript/recording
RETURNS: call_id, status, agent_id, fro
输入参数metadatato_number必填from_number必填override_agent_idoverride_agent_versionretell_llm_dynamic_variables
Create a browser-based voice call session. Returns a web_call_link the user can open to talk to a Retell agent.
WHEN TO USE:
- User wants a voice call in their browser instead of their phone
- Phone call route is blocked (e.g. phone number binding issue)
- Testing or demoing an agent without using phone minutes
EXAMPLE:
{ "agent_id": "agent_xxx", "agent_version": "latest", "retell_llm_dynamic_variables": { "customer_name": "Jane" } }
COMMON MISTAKES:
- Forgetting agent_version when testing a specific published version
- Sharing an old web_call_link instead of creating a fresh session
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: agent/version not found → list_agents, get_agent_versions, then publish_agent if needed
- 422: bad dynamic variable shape → send a plain JSON object
RELATED TOOLS:
- list_agents/get_agent: Find the agent_id and response engine
- update_retell_llm: Set the prompt before creating the test session
- get_call: Retrieve transcript, analysis, and recording after the session
RETURNS: call_id, web_call_link, status, agent_id, access_token. Share web_call_link with the user.
输入参数agent_id必填metadataagent_versionretell_llm_dynamic_variables
Get details of a specific call including status, transcript, recording URL, and duration.
WHEN TO USE:
- After create_phone_call or create_web_call to monitor progress
- To retrieve the full transcript after a call ends
- To check call status: "registered" (queued), "ongoing" (live), "ended" (complete), "error" (failed)
WORKFLOW: Poll every 5-10 seconds after creating a call until status is "ended" or "error".
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: call_id not found → check the ID returned by create_phone_call/create_web_call or use list_calls
RELATED TOOLS:
- create_phone_call/create_web_call: Source of call_id
- list_calls: Find recent call IDs if call_id is unknown
- stop_call: End an ongoing call
RETURNS: call_id, status, transcript, transcript_object, recording_url, call_analysis, duration_ms, disconnection_reason.
输入参数call_id必填
List calls with filtering and pagination. Returns recent calls by default (newest first).
WHEN TO USE:
- Browse call history
- Find calls by agent, date range, or status
- Verify recent call activity
FILTERING:
- agent_id accepts an array of one or more agent IDs
- filter_criteria timestamps accept Unix milliseconds (number) or a parseable date string (e.g. "2026-01-01"); date strings are converted to milliseconds before the API call
- Example: { "limit": 20, "agent_id": ["agent_xxx"], "filter_criteria": { "after_start_timestamp": 1735689600000 } }
COMMON MISTAKES:
- Passing one agent_id as a string instead of an array
- Using seconds for numeric timestamps; Retell expects milliseconds
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 422: invalid filter shape → check agent_id is an array and numeric timestamps are milliseconds
RELATED TOOLS:
- get_call: Get transcript/recording/analysis for a returned call_id
- list_agents: Find agent IDs for filtering
- stop_call: End an ongoing call
RETURNS: calls, count, pagination_key, has_more. Each call includes call_id, status, agent_id, timestamps, and call metadata.
输入参数limitagent_idsort_orderpagination_keyfilter_criteria
Get your account's current call concurrency and limits.
WHEN TO USE:
- Before create_batch_call or a burst of create_phone_call calls, to check capacity headroom
- To decide reserved_concurrency for a batch call (leave room for inbound traffic)
- To diagnose 429/rate-limit or call-queuing issues
HOW TO READ: concurrency_limit is the max simultaneous calls (base + purchased). current_concurrency is how many calls are live right now. Headroom = concurrency_limit - current_concurrency. If concurrency_burst_enabled, the account may exceed the normal limit up to concurrency_burst_limit with a surcharge.
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
RELATED TOOLS:
- create_batch_call: Check headroom before sizing a campaign
- list_calls: See which calls are currently occupying capacity
RETURNS: current_concurrency, concurrency_limit, base_concurrency, purchased_concurrency, concurrency_purchase_limit, remaining_purchase_limit, reserved_inbound_concurrency, concurrency_burst_enabled, concurrency_burst_limit.
无需输入参数。
Stop an ongoing call immediately.
WHEN TO USE:
- User wants to end a call in progress
- Call is stuck or behaving unexpectedly
- Emergency stop
COMMON MISTAKES:
- Calling this on an already ended call; use get_call first if unsure
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: call_id not found or no longer active → verify with list_calls/get_call
RELATED TOOLS:
- get_call: Check whether status is "ongoing" before stopping
- list_calls: Find the active call_id
RETURNS: ok, message. Retell returns HTTP 204 on success.
输入参数call_id必填
Create a batch of outbound phone calls (a calling campaign) from one from_number to many recipients.
WHEN TO USE:
- User asks to call a list of people (appointment reminders, follow-ups, re-engagement)
- Scheduled outbound campaigns — trigger_timestamp defers the start, call_time_window restricts calling hours
CRITICAL: Every task in the batch is a real, billed phone call to a real person. The MCP host MUST surface the full recipient list to the user and get explicit confirmation before invoking this tool. A mistake here rings N phones, not one.
WORKFLOW:
1. get_concurrency → confirm the account has headroom for the batch size
2. list_phone_numbers/get_phone_number → confirm from_number has an outbound agent bound
3. update_retell_llm + publish_agent → set and publish the campaign prompt
4. create_batch_call → schedule or start the batch
5. list_calls (filter by agent) → monitor results as calls complete
EXAMPLE:
{ "from_number": "+14155551234", "name": "March reminder campaign", "tasks": [{ "to_number": "+14155559876", "retell_llm_dynamic_variables": { "customer_name": "Jane" } }] }
COMMON MISTAKES:
- Passing dynamic variables the prompt does not reference; they are silently dropped (check get_retell_llm first)
- Forgetting the per-call agent binding: from_number needs an outbound_agents binding (update_phone_number), or each task needs override_agent_id + override_agent_version
- Using seconds for trigger_timestamp; Retell expects milliseconds
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 402: payment required → add a payment method in the Retell dashboard
- 422: invalid task shape → verify every to_number is E.164 and the from_number is registered
RELATED TOOLS:
- get_concurrency: Check capacity before sizing the batch
- list_phone_numbers/update_phone_number: Verify or fix the outbound binding on from_number
- update_retell_llm/publish_agent: Prepare the campaign prompt
- list_calls/get_call: Track individual call outco
输入参数nametasks必填from_number必填call_time_windowtrigger_timestampreserved_concurrency
Get full configuration of a voice agent including voice, LLM, language, and versioning info.
WHEN TO USE:
- Before making a call, to check the agent's retell_llm_id (needed for update_retell_llm)
- To verify which voice, language, or phone number an agent uses
- To check the agent's current version and published state
COMMON MISTAKES:
- Updating the wrong LLM: use response_engine.llm_id from this tool before update_retell_llm
- Assuming draft changes are live: use get_agent_versions/publish_agent to confirm
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: agent_id not found → list_agents and retry with the returned ID
RELATED TOOLS:
- list_agents: Discover agent IDs
- get_agent_versions: Inspect draft/published versions
- update_retell_llm: Update the linked response_engine.llm_id
- create_phone_call: Use this agent after validating config
RETURNS: agent_id, agent_name, voice_id, response_engine.llm_id, language, version, published/versioning fields, phone number bindings when available.
输入参数agent_id必填
List configured voice agents in your Retell account (paginated).
WHEN TO USE:
- Discover available agents before making calls
- Find agent IDs by name
- Inventory check
NOTE: Returns summary records (agent_id, agent_name, channel, response_engine_type, voice_id, voice_name, tags, timestamps). Use get_agent for the full configuration of a specific agent. Results are filtered to voice agents; use list_chat_agents for chat agents.
COMMON MISTAKES:
- Guessing agent IDs from names; use the returned agent_id exactly
- Expecting the full agent config here; the list endpoint returns summaries — call get_agent for response_engine.llm_id and version details
- Not paginating: pass the returned pagination_key while has_more is true
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
RELATED TOOLS:
- get_agent: Inspect full config for a returned agent_id
- list_chat_agents: List chat agents instead of voice agents
- get_agent_versions: Check published versions
- create_phone_call/create_web_call: Use a verified agent_id
RETURNS: agents, count, pagination_key, has_more. Each agent summary includes agent_id, agent_name, channel, response_engine_type, voice_id, voice_name, tags, and user_modified_timestamp.
输入参数limitsort_orderpagination_key
Create a new voice agent with specified voice, LLM, and language settings.
WHEN TO USE:
- Setting up a new voice agent from scratch
- No existing agent fits the use case
WORKFLOW:
1. list_voices → choose voice_id
2. create_retell_llm → create prompt/model config
3. create_agent → point response_engine.llm_id at that LLM
4. publish_agent → make the version live
5. update_phone_number → bind the agent for calls
EXAMPLE:
{ "agent_name": "Sales qualifier", "voice_id": "11labs-Adrian", "response_engine": { "type": "retell-llm", "llm_id": "llm_xxx" }, "language": "en-US" }
COMMON MISTAKES:
- Creating the agent before creating/selecting a Retell LLM
- Forgetting to publish and bind the agent to a phone number before create_phone_call
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: voice_id or llm_id not found → list_voices/list_retell_llms and retry
- 422: invalid config → verify response_engine is { "type": "retell-llm", "llm_id": "..." }
RELATED TOOLS:
- list_voices: Choose a voice_id
- create_retell_llm/list_retell_llms: Choose or create the LLM
- publish_agent: Make the new version live
- update_phone_number: Bind for inbound/outbound calls
RETURNS: agent_id, agent_name, voice_id, response_engine, language, version fields.
输入参数languagevoice_idagent_nameresponse_engine
Update an existing agent's configuration (voice, name, response engine, language, etc.).
WHEN TO USE:
- Change voice, language, response engine, responsiveness, or backchannel behavior
- Point an agent at a different Retell LLM
NOTE: This updates the agent's latest DRAFT version. To make changes live, call publish_agent afterward.
COMMON MISTAKES:
- Updating the agent and immediately calling without publish_agent
- Switching response_engine.llm_id without checking the LLM config first
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: agent_id/voice_id/llm_id not found → use list_agents/list_voices/list_retell_llms
- 422: invalid setting range → check numeric ranges on speed/responsiveness/sensitivity
RELATED TOOLS:
- get_agent: Inspect current config before changing
- publish_agent/get_agent_versions: Publish and verify draft changes
- update_retell_llm: Change prompt/model without replacing the response engine
RETURNS: Updated agent object including agent_id, agent_name, voice_id, response_engine, language, draft/version fields.
输入参数agent_id必填languagevoice_idagent_namevoice_speedambient_soundresponsivenessresponse_engineboosted_keywordsenable_backchannelinterruption_sensitivity
Publish a specific agent version, making it the active/live version.
WHEN TO USE:
- After updating an agent's config or LLM, to make changes live
- When create_phone_call returns 404 because the agent version is unpublished
- When you need to activate a specific version
CRITICAL: Agent updates go to the latest DRAFT version. They are NOT live until published.
If calls fail with 404, check get_agent_versions and publish the correct version.
WORKFLOW:
1. update_agent or update_retell_llm → changes the draft
2. get_agent_versions → find the version number of the draft
3. publish_agent → make it live
COMMON MISTAKES:
- Publishing the wrong version number; call get_agent_versions immediately before this
- Assuming update_retell_llm alone publishes changes
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: agent/version not found → list_agents/get_agent_versions
- 422: version is invalid or not publishable → verify the draft version number
RELATED TOOLS:
- get_agent_versions: Find the version number to publish
- update_agent/update_retell_llm: Make draft changes first
- create_phone_call: Use the published version afterward
RETURNS: ok, message confirming the agent_id and published version.
输入参数version必填agent_id必填version_description
Permanently delete an agent and ALL of its versions.
WHEN TO USE:
- Removing a test/throwaway agent after experiments
- Cleaning up agents that are no longer needed
CRITICAL: This permanently deletes the agent and every version — there is no undo. Any phone numbers bound to it lose their agent binding. Confirm the agent_id with list_agents/get_agent first, and prefer deleting only after checking no phone number still routes to it (list_phone_numbers).
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: agent_id not found → list_agents and retry with a returned ID
RELATED TOOLS:
- list_agents/get_agent: Confirm the exact agent_id before deleting
- list_phone_numbers: Check no number still binds the agent
- create_agent: Create a replacement
RETURNS: ok, message. Retell returns HTTP 204 on success.
输入参数agent_id必填
List all versions of an agent, including draft and published versions.
WHEN TO USE:
- To check which version is currently published/live
- To find the version number of a draft before publishing
- To debug version mismatch issues causing 404 errors on calls
COMMON MISTAKES:
- Using override_agent_id without checking the matching override_agent_version here
- Publishing/calling a stale version after updating the draft
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: agent_id not found → list_agents and retry
RELATED TOOLS:
- publish_agent: Publish a draft version returned here
- create_phone_call: Pass override_agent_version from this list
- get_agent: Inspect the agent tied to these versions
RETURNS: versions, count. Each version includes version number, published/live status, creation/update timestamps, and description when available.
输入参数agent_id必填
Update a Retell LLM response engine's prompt, model, or behavior settings.
WHEN TO USE:
- Before making a call, to set the conversation instructions/prompt
- To change the LLM model or temperature
- To update the agent's opening message
CRITICAL: This is the #1 most important step before any phone call. The general_prompt controls what the agent says. If you skip this, the agent will use the PREVIOUS call's prompt.
WORKFLOW:
1. get_agent → find the agent's retell_llm_id (in response_engine.llm_id)
2. update_retell_llm → set the prompt and behavior
3. get_agent_versions/publish_agent if the agent version needs publishing
4. Wait 2-3 seconds for propagation
5. create_phone_call
MODEL OPTIONS: gpt-4.1, gpt-4.1-mini, gpt-5, gpt-5-mini, 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.
EXAMPLE:
{ "llm_id": "llm_xxx", "general_prompt": "You are calling to confirm tomorrow's appointment. Be concise and polite.", "begin_message": "Hi, this is Alex calling to confirm your appointment.", "model": "gpt-5.5" }
COMMON MISTAKES:
- Skipping this before create_phone_call, causing the previous call's prompt to run
- Updating the wrong llm_id; get it from get_agent.response_engine.llm_id
- Forgetting to publish the agent/version after changing call behavior
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: llm_id not found → get_agent or list_retell_llms
- 422: invalid model/prompt/tools → use a listed model and valid JSON tool config
RELATED TOOLS:
- get_agent: Find the linked response_engine.llm_id
- get_retell_llm: Inspect current prompt/model before changing
- publish_agent/get_agent_versions: Make agent changes live
- create_phone_call/create_web_call: Test the updated behavior
RETURNS: llm_id, general_prompt, begin_message, model, model_temperature, general_tools, updated timestamps.
输入参数modelllm_id必填begin_messagegeneral_toolsgeneral_promptmodel_temperature
Get details of a Retell LLM response engine (prompt, model, tools).
WHEN TO USE:
- Inspect current prompt/model before update_retell_llm
- Confirm which prompt an agent will use before a call
- Debug why an agent said the wrong thing
COMMON MISTAKES:
- Looking at the agent only; the actual call instructions live in the Retell LLM
- Editing a different LLM than the one returned by get_agent.response_engine.llm_id
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: llm_id not found → get_agent/list_retell_llms and retry
RELATED TOOLS:
- get_agent: Find response_engine.llm_id for an agent
- update_retell_llm: Change the prompt/model
- list_retell_llms: Browse available LLM configs
RETURNS: llm_id, general_prompt, begin_message, model, model_temperature, general_tools, timestamps.
输入参数llm_id必填
Create a new Retell LLM response engine with prompt and model settings.
WHEN TO USE:
- Creating a new agent that needs its own prompt/model config
- Separating a new call workflow from an existing agent's LLM
- Testing a new prompt without overwriting a production LLM
WORKFLOW: Create the LLM first, then create_agent with response_engine: { "type": "retell-llm", "llm_id": "<returned llm_id>" }.
EXAMPLE:
{ "general_prompt": "You confirm appointment times and answer basic scheduling questions.", "begin_message": "Hi, I'm calling to confirm your appointment.", "model": "gpt-5.5" }
MODEL OPTIONS: gpt-4.1, gpt-4.1-mini, gpt-5, gpt-5-mini, 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.
COMMON MISTAKES:
- Creating multiple near-identical LLMs instead of updating the existing one
- Creating the LLM but never attaching it to an agent
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 422: invalid model/prompt → use a listed model and non-empty prompt
RELATED TOOLS:
- list_retell_llms/get_retell_llm: Reuse or inspect existing configs
- create_agent/update_agent: Attach the new llm_id to an agent
- update_retell_llm: Modify this config later
RETURNS: llm_id, general_prompt, begin_message, model, model_temperature, general_tools, timestamps.
输入参数modelbegin_messagegeneral_prompt
Permanently delete a Retell LLM response engine and ALL of its versions.
WHEN TO USE:
- Removing a test/throwaway LLM config after experiments
- Cleaning up unused LLM configs
CRITICAL: This permanently deletes the LLM and every version — there is no undo. Any agent whose response_engine.llm_id points at it will break (calls will fail). Check which agents reference it via list_agents/get_agent before deleting.
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: llm_id not found → list_retell_llms and retry with a returned ID
RELATED TOOLS:
- list_retell_llms/get_retell_llm: Confirm the exact llm_id before deleting
- list_agents/get_agent: Check no agent still references the LLM
- create_retell_llm: Create a replacement
RETURNS: ok, message. Retell returns HTTP 204 on success.
输入参数llm_id必填
List all Retell LLM response engine configurations.
WHEN TO USE:
- Find llm_id values before get_retell_llm/update_retell_llm
- Inventory prompt/model configurations
- Decide whether to reuse an LLM or create a new one
COMMON MISTAKES:
- Updating an arbitrary llm_id without checking which agent uses it
- Assuming list order implies which LLM is active; use get_agent to confirm bindings
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 422: invalid pagination params → keep limit between 1 and 1000
RELATED TOOLS:
- get_retell_llm: Inspect one returned llm_id
- update_retell_llm: Change prompt/model
- get_agent/list_agents: See which agents reference each LLM
- create_retell_llm: Create a separate config when reuse is unsafe
RETURNS: llms, count, pagination_key, has_more. Each LLM includes llm_id, prompt/model fields, and timestamps when available.
输入参数limitpagination_key
Browse all available TTS voices in Retell.
WHEN TO USE:
- Find voice IDs when creating or updating an agent
- Compare providers/voice names before selecting a voice
- Verify a voice_id still exists after a 404 from create_agent/update_agent
COMMON MISTAKES:
- Passing the display name instead of the exact voice_id
- Reusing an old voice_id without checking it still exists
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
RELATED TOOLS:
- create_agent: Use a returned voice_id for a new agent
- update_agent: Change an existing agent's voice_id
RETURNS: voices, count. Each voice includes voice_id, voice_name/name, provider, accent/language/gender, and preview metadata when available.
无需输入参数。
List all phone numbers in your Retell account with their agent bindings.
WHEN TO USE:
- Before create_phone_call, to find available from_numbers
- To check which agents are bound to which numbers
- To verify outbound agent configuration
TIP: The phone_number field (E.164 format) is what you pass as from_number in create_phone_call.
The outbound_agents array shows which agent(s) are bound for outbound calls from this number.
Check each outbound agent's agent_version before calling; version mismatches are a common 404 cause.
COMMON MISTAKES:
- Using a number that exists but has no outbound_agents binding
- Ignoring agent_version on the binding and then overriding only agent_id during create_phone_call
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 422: invalid pagination params → keep limit between 1 and 1000
RELATED TOOLS:
- get_phone_number: Inspect one number's bindings
- update_phone_number: Bind or rebind agents
- create_phone_call: Use returned phone_number as from_number
- get_agent_versions: Verify bound versions
RETURNS: phone_numbers, count, pagination_key, has_more. Each number includes phone_number, inbound_agents, outbound_agents, nickname/config when available.
输入参数limitpagination_key
Get details of a specific phone number including its agent bindings.
WHEN TO USE:
- To check which agents are bound (inbound and outbound) to a specific number
- To diagnose why create_phone_call returns 404 (missing outbound agent binding)
- To confirm the bound agent_version before overriding call routing
COMMON MISTAKES:
- Checking only that the number exists; outbound calls require outbound_agents
- Missing that the bound agent_version differs from the version you intend to use
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: phone number not found → list_phone_numbers and use the exact E.164 value
RELATED TOOLS:
- list_phone_numbers: Discover available numbers
- update_phone_number: Add/fix inbound or outbound bindings
- get_agent_versions: Verify bound agent versions
- create_phone_call: Use this phone_number as from_number
RETURNS: phone_number, nickname, inbound_agents, outbound_agents, phone number config fields.
输入参数phone_number必填
Update agent bindings and settings for a phone number.
WHEN TO USE:
- To bind an agent to a phone number for outbound/inbound calls
- To fix "404 Not Found" errors on create_phone_call (the number needs an outbound agent)
- To change which agent handles calls on a number
CRITICAL: After Retell's March 2026 update, phone numbers use weighted agent lists.
Each binding needs agent_id, weight (must sum to 1), and optionally agent_version.
EXAMPLE — bind agent to outbound calls:
{ "phone_number": "+14155551234", "outbound_agents": [{ "agent_id": "agent_xxx", "agent_version": 1, "weight": 1 }] }
COMMON MISTAKES:
- Omitting agent_version and accidentally binding the wrong/latest version
- Setting weights that do not sum to 1
- Updating inbound_agents when the failure is outbound calling
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: phone_number or agent_id not found → list_phone_numbers/list_agents
- 422: invalid binding → include agent_id + weight, ensure weights sum to 1, verify agent_version
RELATED TOOLS:
- get_phone_number/list_phone_numbers: Inspect current bindings first
- get_agent_versions: Choose a valid agent_version
- publish_agent: Make the desired version live before binding
- create_phone_call: Test outbound routing after updating
RETURNS: phone_number, nickname, inbound_agents, outbound_agents, updated config fields.
输入参数nicknamephone_number必填inbound_agentsoutbound_agents
Delete (release) a phone number from your Retell account.
WHEN TO USE:
- Releasing a number that is no longer needed (stops its recurring cost)
- Cleaning up numbers purchased for a finished campaign
CRITICAL: This releases the number back — there is no undo, and you may not be able to get the same number back. Any agents bound to it lose their routing immediately. Confirm with get_phone_number first.
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: phone number not found → list_phone_numbers and use the exact E.164 value
RELATED TOOLS:
- list_phone_numbers/get_phone_number: Confirm the number and its bindings first
- update_phone_number: Rebind agents instead of releasing the number
RETURNS: ok, message. Retell returns HTTP 204 on success.
输入参数phone_number必填
List all knowledge bases in your Retell account.
WHEN TO USE:
- Find knowledge_base_id values before attaching them to an agent or LLM
- Check processing status of a recently created knowledge base (in_progress → complete)
- Inventory check before creating a duplicate
COMMON MISTAKES:
- Creating a new knowledge base when a suitable one already exists; list first
- Attaching a knowledge base whose status is still "in_progress" — wait for "complete"
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
RELATED TOOLS:
- get_knowledge_base: Inspect one knowledge base's sources and status
- create_knowledge_base: Create when nothing suitable exists
- add_knowledge_base_sources: Add documents to an existing knowledge base
RETURNS: knowledge_bases, count. Each includes knowledge_base_id, knowledge_base_name, status, sources (when processed), and chunking config.
无需输入参数。
Get details of a specific knowledge base, including its sources and processing status.
WHEN TO USE:
- Check whether a knowledge base has finished processing (status "complete")
- List the documents/URLs/texts a knowledge base contains
- Verify a source was added before attaching the knowledge base to an agent
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: knowledge_base_id not found → list_knowledge_bases and retry with a returned ID
RELATED TOOLS:
- list_knowledge_bases: Discover knowledge_base_id values
- add_knowledge_base_sources: Add more documents/URLs/texts
RETURNS: knowledge_base_id, knowledge_base_name, status, knowledge_base_sources (type, filename/title/url, source_id), chunking config, auto-refresh settings.
输入参数knowledge_base_id必填
Create a knowledge base (documents/URLs/texts) that agents can ground their answers on via RAG.
WHEN TO USE:
- Ground a voice agent on company docs, FAQs, or policies
- Collect source material before wiring knowledge_base_ids into a Retell LLM or agent
WORKFLOW:
1. create_knowledge_base → with texts, URLs, and/or local files
2. Poll get_knowledge_base until status is "complete"
3. Attach the knowledge_base_id to the agent's Retell LLM (knowledge_base_ids) — attach via update_retell_llm general_tools/config or the Retell dashboard
SOURCES (at least one recommended; a name-only knowledge base is allowed):
- knowledge_base_texts: inline title+text pairs
- knowledge_base_urls: public URLs Retell scrapes (set enable_auto_refresh to re-scrape every 12 hours)
- file_paths: local files to upload. When connected to a host that authorizes file reads, its path permission decision applies to each path. Standalone clients require files inside the workspace sandbox (MCP_WORKSPACE_PATH, or the system temp directory when unset). Max 25 files, 50MB each.
COMMON MISTAKES:
- Standalone clients: passing a file path outside MCP_WORKSPACE_PATH (or the system temp directory when unset); it is rejected by the workspace sandbox before any disk read
- Expecting immediate availability; processing takes time — poll get_knowledge_base for status "complete"
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 422: invalid source shape → check texts have title+text and URLs are valid http(s) URLs
RELATED TOOLS:
- list_knowledge_bases/get_knowledge_base: Verify and inspect
- add_knowledge_base_sources: Add more sources later
RETURNS: knowledge_base_id, knowledge_base_name, status (starts "in_progress").
输入参数file_pathsenable_auto_refreshknowledge_base_name必填knowledge_base_urlsknowledge_base_texts
add_knowledge_base_sources
Add new sources (texts, URLs, or local files) to an existing knowledge base.
WHEN TO USE:
- Extend a knowledge base with new documents without recreating it
- Add a freshly written FAQ/policy file to the agent's grounding material
NOTE: At least one of knowledge_base_texts, knowledge_base_urls, or file_paths is required. After adding, the knowledge base re-processes (status "refreshing_in_progress") — poll get_knowledge_base until "complete".
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: knowledge_base_id not found → list_knowledge_bases and retry
- 422: invalid source shape → check texts have title+text and URLs are valid
RELATED TOOLS:
- get_knowledge_base: Confirm the sources landed and processing finished
- create_knowledge_base: Create a separate knowledge base instead
RETURNS: knowledge_base_id, knowledge_base_name, status, updated sources.
输入参数file_pathsknowledge_base_id必填knowledge_base_urlsknowledge_base_texts
List configured chat agents in your Retell account (paginated).
WHEN TO USE:
- Discover chat agents before reading their chats
- Find chat agent IDs by name
NOTE: Returns summary records (agent_id, agent_name, channel, tags, timestamps). Results are filtered to chat agents; use list_agents for voice agents.
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
RELATED TOOLS:
- list_agents: List voice agents instead
- list_chats/get_chat: Read chat transcripts for a returned agent_id
RETURNS: agents, count, pagination_key, has_more. Each agent summary includes agent_id, agent_name, channel, tags, and user_modified_timestamp.
输入参数limitsort_orderpagination_key
List chat sessions with filtering and pagination. Returns recent chats by default (newest first).
WHEN TO USE:
- Browse chat history for a chat agent
- Find a chat_id before reading its full transcript with get_chat
- Review chat volume over a time range
FILTERING:
- agent_id accepts an array of one or more agent IDs
- filter_criteria timestamps accept Unix milliseconds (number) or a parseable date string (e.g. "2026-01-01"); date strings are converted to milliseconds before the API call
- Example: { "limit": 20, "agent_id": ["agent_xxx"], "filter_criteria": { "after_start_timestamp": 1735689600000 } }
COMMON MISTAKES:
- Passing one agent_id as a string instead of an array
- Using seconds for numeric timestamps; Retell expects milliseconds
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 422: invalid filter shape → check agent_id is an array and numeric timestamps are milliseconds
RELATED TOOLS:
- get_chat: Get the full transcript and analysis for a returned chat_id
- list_chat_agents: Find chat agent IDs for filtering
- list_calls: Voice-call equivalent of this tool
RETURNS: chats, count, pagination_key, has_more. Each chat includes chat_id, chat_status, agent_id, timestamps, and metadata.
输入参数limitagent_idsort_orderpagination_keyfilter_criteria
Get details of a specific chat including full transcript, per-message breakdown, and analysis.
WHEN TO USE:
- After list_chats, to read one chat's full transcript
- To review chat analysis (summary, sentiment, success) for quality checks
ERROR RECOVERY:
- 401: API key is missing or invalid → configure_retell_api_key
- 404: chat_id not found → check the ID returned by list_chats
RELATED TOOLS:
- list_chats: Find chat IDs
- get_call: Voice-call equivalent (transcript, recording, analysis)
RETURNS: chat_id, chat_status, agent_id, transcript, message_with_tool_calls, chat_analysis, start/end timestamps, metadata.
输入参数chat_id必填
Host-managed setup only. The user adds the Retell AI API key in Settings → Connectors in the app. Do not ask for or accept the key in chat.
WHERE TO GET A KEY:
1. Go to https://www.retellai.com/dashboard
2. Navigate to API Keys in settings
3. Create and copy your API key
All other Retell AI tools require a valid API key to work.
输入参数api_key必填