In the previous section, we showed what’s tools. In this section, we will show you how to add them to your agent.Documentation Index
Fetch the complete documentation index at: https://docs.retellai.com/llms.txt
Use this file to discover all available pages before exploring further.
Define Functions (Common Part)
No matter what type of tool you are using, there are some fields you have to define.-
tool name: the unique identifier of the tool.- Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
- it has to be unique across all tools available to the model at any given time.
- best to be a natural language string that LLM can understand like transfer_to_support.
-
description: a clear description of what this tool does, sometimes you can also include when to call the tool in this field.- This can be optional for some pre-defined tools, as we have some default values (see below for details).
- IMPORTANT: generally you would write what this tool does here, and write in prompt explicitly when you want to call this tool. (for example: “step 6. After all questions answered, call function end_call to hang up.”)
Pre-defined Tools
There are several pre-defined tools we already provide for your convenience.Pre-defined Tool Types
End Call
This tool is used to end the call, no matter if it’s web or phone call, no matter if it’s a Retell number or your own Twilio. You can specify a description about when to end the call. If description omitted, it would use the defaultEnd the call with user.
When end call is triggered, it would always say a farewell sentence like to user before hanging up.
Transfer Call
This tool is used to transfer the call to another number, and it can even be another phone associated with Retell agent. You can specify a description about when to transfer the call. If description omitted, it would use the defaultTransfer the call to another number.
When transfer call is triggered, it would always say a sentence like “Transferring you to… one moment” to user before actual transferring.
When you need to have multiple numbers to transfer to (for example, transfer to support department, transfer to sales department),
you need to define multiple transfer tools with different names, and in prompt explicitly write when to invoke which tool.
Press Digit
This tool is used to press digit or digits, mainly to navigate IVR. If description omitted, it would use the defaultThe digit to press, can be a single digit, or a combination of digits like '1234*'. Usually either selecting an option in IVR or entering information like phone number.
Since IVR is usually speaks slowly, this tool tends to wait for a bit longer before actually pressing the digit.
Check Availability with cal.com
This tool is used to check the availability of an event on cal.com. You can specify a description about when to check the availability. It will automatically handle relative date time references like “tomorrow”, “next week”, “next month” for you ,and automatically deduces a range out of it (for example, “tomorrow” would be from 00:00 to 23:59 of tomorrow). If there’re no nearby availability, it can also retrieve the availability nearby that range. The returned result is parsed based on timezone specified. If no timezone specified, it would uses the timezone of the Retell server. When this tool is triggered, it would always say a sentence like “Checking the availability of event…” to user. The tool requires a Cal.com API key, a cal event type id (retrieved in the url when you configure a cal event, for example: https://app.cal.com/event-types/654321 event type id is 654321). This tool is commonly used in conjunction with the book appointment cal.com tool.Book Appointment with cal.com
This tool is used to book an appointment with specified event on cal.com. You can specify a description about when to book the appointment. It will automatically handle relative date time references like “tomorrow 5pm”, “next Tuesday 2pm” for you. It would utilize the timezone specified to parse the time reference to the ISO8601 format to use in the API call. When this tool is triggered, it would always say a sentence like “Booking an appointment for you…” to user. The tool requires a Cal.com API key, a cal event type id (retrieved in the url when you configure a cal event, for example: https://app.cal.com/event-types/654321 event type id is 654321). This tool is commonly used in conjunction with the check appointment cal.com tool. If user selected a time that’s not available, this tool would return message like “cannot book appointment at this time”. Therefore it’s recommended to retrieve availability first before booking an appointment.Add via Dashboard
Step 1 - Add end call tool
Click ”+ Add” and select “End Call”.
Step 2 - Provide more details to the tool
- Clarify the conditions under which the call should be terminated.

- It’s advisable to reiterate the requirements in the prompt to ensure optimal precision.

- Don’t forget clicking “Save LLM” on the top right.
Add via API
You can also add predefined tools programmatically.Custom Tools
For tasks not covered by pre-defined tools, you can define your custom tool to execute external APIs, provide knowledge to agent, etc. For custom tools, apart from the usual name and description you would define a URL and the parameters for it. Once the LLM decides to call this tool, we willPOST to the URL defined with the function name and parameters, and the call information.
Add via Dashboard

Add via API
You can also add the tool programmatically, similar to how you added it for pre-defined tools.Define Parameters for Custom Tool
This is a JSON schema to let the LLM know what inputs this tool would need. For example, for the followingget-weather custom tool, we defined the parameters to be a city name.
POST the a JSON body data like the following to the URL specified:
Verify and Handle the Request
Now you’ve got the tool call request, you need to verify the request is from Retell and handle it.You can secure your server from public network by only allowlisting Retell IP addresses:
100.20.5.228