Functions and tools overview

Functions (tools) let an agent act during a call: hang up, transfer, press keypad digits, text the caller, call your API, run JavaScript, call an MCP server or run an action in a connected app. The LLM decides when to call a function from its name, its description and the conversation so far. The voice worker then runs the function, records the call and the result in the transcript, and (for most types) feeds the result back to the LLM so the agent can reply.

Tool types#

Every tool is one entry in the Tool discriminated union in packages/shared. The type field selects the shape.

Bridge Transfer and Cancel Transfer only appear in the Add menu when the agent has Transfer agent turned on under Agent Settings.

Where tools live#

In the dashboard, open the agent and expand Functions in the settings column next to the prompt. Click Add, pick a type, fill in the modal and click Save. Each saved tool shows as a row with an edit (pencil) and a delete button. In a conversation flow, the same Functions section sits under Global settings.

How a function call runs#

Both events appear in transcript_with_tool_calls on the call object and in the test panel as Tool Invocation rows.

Name and description#

The dashboard pre-fills a name per type (end_call, transfer_call, press_digit, custom_function, extract_variables, send_sms, run_code, agent_transfer, mcp_tool, app_action) and appends _2, _3 when the name is taken.

Execution options#

These fields exist on every tool type (toolBase in packages/shared). In the modal they are grouped under While it runs. The group is hidden for End Call, Bridge Transfer and Cancel Transfer.

Which types reply after running#

Parameters (JSON schema)#

custom, code, mcp and integration_app tools take a parameters object: a JSON schema of type object whose properties are the arguments the LLM fills in.

The Parameters editor has two modes:

• Form: one row per argument with a name, a type (Text, Number, Integer, Boolean, Choice), Description for the LLM, Required and Pin value.
• JSON schema: the raw schema. Invalid JSON blocks Save and shows "Invalid JSON".

The Custom Function modal also offers Example 1 and Example 2 buttons that load sample schemas.

{
  "type": "object",
  "properties": {
    "date": { "type": "string", "description": "Appointment date (YYYY-MM-DD)" },
    "time": { "type": "string", "description": "Time in 24h format" },
    "source": { "type": "string", "const": "phone" }
  },
  "required": ["date", "time"]
}

Pinned values#

Pin value writes a JSON schema const on the property. For Custom Function tools the worker removes const properties from the schema the LLM sees and injects the pinned value (rendered with {{variables}}) into the arguments at call time. Pinned properties are never marked required.

Strict mode#

tool_call_strict_mode on the Retell LLM (default true) and on the flow (optional, off when unset) sends the tool schemas to the model in strict mode, so arguments follow the schema exactly.

Response variables#

custom, code, mcp and integration_app tools can save parts of the result as dynamic variables with response_variables: a map of variable name to JSON path. Saved values are added to collected_dynamic_variables, can be used as {{name}} in later prompts and tools, and can drive equation transitions in flows. Objects and arrays are stored as JSON strings.

{ "response_variables": { "slot": "$.data.slots[0]", "booking_id": "$.booking.uid" } }

Results and limits#

Testing tools#

In the test panel, Test LLM shows each Tool Invocation with its arguments. Test LLM does not call your endpoints: add a canned output under Mocks (the wrench tab) and the chat feeds it back to the agent as the result, marked Mocked. Use Test Audio or a real phone call to run the tools for real.

Related#