Tools

Tools enable your assistant to connect to external data and systems. You can define a set of tools that the assistant has access to, and the assistant will use them where appropriate based on the conversation.

Overview

Many applications require assistants to call external APIs to get real-time information. Tools give your assistant the ability to make external function calls to third party apps so you can get real-time information.

Here are a few examples where tools can be useful:

• Fetching data: enable an assistant to retrieve real-time data from any REST-enabled database or 3rd party integration before responding to the user.
• Taking action: allow an assistant to trigger authenticated actions based on the conversation, like scheduling meetings or initiating order returns.

Tool configuration

Conversational AI assistants can be equipped with tools to interact with external APIs. Unlike traditional requests, the assistant generates query, body, and path parameters dynamically based on the conversation and parameter descriptions you provide.

All tool configurations and parameter descriptions help the assistant determine when and how to use these tools. To orchestrate tool usage effectively, update the assistant’s system prompt to specify the sequence and logic for making these calls. This includes:

• Which tool to use and under what conditions.
• What parameters the tool needs to function properly.
• How to handle the responses.

Configuration

Secrets

Headers

Path parameters

Body parameters

Query parameters

Define a high-level Name and Description to describe the tool’s purpose. This helps the LLM understand the tool and know when to call it.

If the API requires path parameters, include variables in the URL path by wrapping them in curly braces {}, for example: /api/resource/{id} where id is a path parameter.

Guide

In this guide, we will walk through integrating tools into an assistant, booking calendar meetings through the Cal.com API as an example.

1

Store a secret

To make authenticated requests to external APIs like Cal.com, you need to store your API keys securely. Start by generating a new Cal.com API key.

Not all APIs have the same authentication structure. For example, the Cal.com API expects the following authentication header:

Cal request header structure

'Authorization': 'Bearer YOUR_API_KEY'

Once you have your API key, store it in the assistant’s secret storage. This ensures that your key is kept secure and accessible when making requests.

To match the expected authentication structure of Cal.com, remember to prepend the API key with Bearer when creating the secret.

2

Adding tools to the assistant

To enable your assistant to manage calendar bookings, we’ll create two tools:

1. get_available_slots: When a user asks, “Is Louis free at 10:30 AM on Tuesday?”, the assistant should use Cal.com’s “Get available slots” endpoint to check for available time slots.

2. book_meeting: After identifying a suitable time, the assistant can proceed to book the meeting using Cal.com’s “Create a booking” endpoint.

First, head to the Tools section of your dashboard and choose Add Tool. Select Webhook as the Tool Type, then fill in the following sections:

Tool 1: get_available_slots

Configuration

Headers

Query parameters

Metadata used by the assistant to determine when the tool should be called:

Field	Value
Name	get_available_slots
Description	This tool checks if a particular time slot is available in the calendar.
Method	GET
URL	https://api.cal.com/v2/slots/available

Tool 2: book_meeting

Configuration

Headers

Body Parameters

Metadata used by the assistant to determine when the tool should be called:

Field	Value
Name	book_meeting
Description	This tool books a meeting in the calendar once a time is agreed.
Method	POST
URL	https://api.cal.com/v2/bookings

3

Orchestration

Now that your assistant is equipped with tools, you need to instruct it on when and how to use them effectively. This involves updating the system prompt to orchestrate the interaction.

System prompt

You are my receptionist, handling meeting bookings.
- Always use the `get_available_slots` tool to verify my availability before scheduling any meeting. This tool requires a start and end date/time and returns available slots. If no date/time is specified, check for slots tomorrow and continue daily until availability is found.
- Once a time is agreed upon, use the `book_meeting` tool to finalize the booking. Collect the caller's full name, desired meeting time, duration (15, 30, or 60 minutes), and other required details.
- Do not share or leak any meeting details, attendee information, or IDs.
- If `book_meeting` fails, it may be due to an invalid email format or an unavailable time slot.

Test your new assistant by pressing the Test AI agent button to ensure everything is working as expected. Feel free to fine-tune the system prompt.

4

Enhancements

By default, the assistant does not have knowledge of the current date or time. To enhance its capabilities, consider implementing one of the following solutions:

1. Create a time retrieval tool: Add another tool that fetches the current date and time.

2. Overrides: Use the overrides functionality to inject the current date and time into the system prompt at the start of each conversation.

Best practices

Name tools intuitively, with detailed descriptions

If you find the assistant does not make calls to the correct tools, you may need to update your tool names and descriptions so the assistant more clearly understands when it should select each tool. Avoid using abbreviations or acronyms to shorten tool and argument names.

You can also include detailed descriptions for when a tool should be called. For complex tools, you should include descriptions for each of the arguments to help the assistant know what it needs to ask the user to collect that argument.

Name tool parameters intuitively, with detailed descriptions

Use clear and descriptive names for tool parameters. If applicable, specify the expected format for a parameter in the description (e.g., YYYY-mm-dd or dd/mm/yy for a date).

Consider providing additional information about how and when to call tools in your assistant’s system prompt

Providing clear instructions in your system prompt can significantly improve the assistant’s tool calling accuracy. For example, guide the assistant with instructions like the following:

Use `check_order_status` when the user inquires about the status of their order, such as 'Where is my order?' or 'Has my order shipped yet?'.

Provide context for complex scenarios. For example:

Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts.

LLM selection

It’s important to note that the choice of LLM matters to the success of function calls. Some LLMs can struggle with extracting the relevant parameters from the conversation.