Agent Tools
The actions the AI agent can take during a conversation.
Overview
The agent uses tool calling to take actions — it never fabricates a booking or invents availability. Every booking, lead record, and slot list comes from a real API call to the Empfio backend.
All tools are available at every step of the conversation. The agent's prompt guides which tools to use at each step, but none are artificially restricted.
How tools work
- The AI model decides an action is needed (e.g. "I need to check availability")
- It generates a tool call with the appropriate arguments
- The tool executes — making an HTTP call to the Empfio backend
- The result is returned to the AI model as a message
- The model uses the result to generate its reply to the customer
Two parameters — channel and channel_id — are automatically injected into every tool call from the conversation state. The AI model never sees or provides these values, which keeps the tool schemas smaller and prevents the model from sending messages to the wrong channel.
Available tools
create_lead
Registers a new customer contact in the CRM.
- When called: At the greeting step, when the customer first interacts
- What it does: Creates a lead record linked to the customer's channel and ID. The backend handles deduplication — if a lead with this channel ID already exists, the existing lead is returned
- Parameters: None (channel and channel_id are injected from state)
update_lead_status
Updates the customer's information and conversation progress.
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | Yes | Lead status: contacted, booking_offered, booked |
name | string | No | Customer's full name |
email | string | No | Customer's email address |
phone | string | No | Customer's phone number |
- When called: After collecting contact information (name, email, phone)
- What it does: Saves the customer's details and updates the lead's status in the CRM
get_available_slots
Checks your calendar for open appointment times.
| Parameter | Type | Default | Description |
|---|---|---|---|
days | string | "3" | How many days ahead to check |
service_duration | string | "30" | Appointment duration in minutes |
start_date | string | empty | Specific start date (YYYY-MM-DD) |
end_date | string | empty | Specific end date (YYYY-MM-DD) |
- When called: When the customer is ready to pick a time
- What it does: Fetches available slots from Cal.com and automatically presents them as interactive buttons — the agent does not need to call
present_optionsseparately for slots - Returns: Up to 6 slots, grouped by day, as tappable time buttons
create_booking
Books an appointment for the customer.
| Parameter | Type | Required | Description |
|---|---|---|---|
start_time | string | Yes | ISO 8601 start time (e.g. 2026-03-02T10:00:00) |
end_time | string | Yes | ISO 8601 end time |
lead_name | string | Yes | Customer's full name |
lead_email | string | Yes | Customer's email |
service | string | Yes | Service being booked |
notes | string | No | Additional notes from the conversation |
duration_min | string | No | Duration in minutes (default: 30) |
price_eur | string | No | Price in euros (salon) |
staff_preference | string | No | Preferred staff member (salon) |
address | string | No | Customer address (trades) |
urgency | string | No | normal or high (trades) |
problem_description | string | No | Issue description (trades) |
access_notes | string | No | Access instructions (trades) |
- When called: Only after the customer has explicitly confirmed the booking details
- What it does: Creates the booking in Cal.com and records it in Empfio. Sends a confirmation email to the business owner
get_my_bookings
Looks up existing bookings for the current customer.
- Parameters: None (channel_id is injected from state)
- When called: When a customer asks about their existing appointments
- Returns: A list of the customer's bookings with service name, date, and time
present_options
Presents interactive options to the customer as buttons or a selectable list.
| Parameter | Type | Required | Description |
|---|---|---|---|
action_type | string | Yes | buttons (up to 3 options) or list (up to 10 options) |
options | string | Yes | JSON string describing the options |
button_text | string | No | Label on the list-open button (list type only, max 20 chars) |
- When called: For service selection, confirmations, and any multi-choice question
- What it does: Renders tappable buttons in WhatsApp, inline keyboard in Telegram, or clickable buttons in web chat
- Note: Do not call this for time slots —
get_available_slotshandles slot presentation automatically
escalate_to_human
Hands the conversation off to a human team member.
| Parameter | Type | Required | Description |
|---|---|---|---|
reason | string | Yes | Brief explanation (e.g. "Customer requested human agent") |
- When called: When the agent cannot help, or the customer asks for a person
- What it does: Marks the conversation as
escalated, notifies the business owner via email, and tells the customer a team member will follow up