> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dialtu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The calendar tool for agents

> What an AI agent may read and change on the calendar, the event title, and extra questions

A **Calendar Tool** gives a WhatsApp, SMS or voice agent (Aurora engine) a window onto the calendar. The agent reads real free slots — it never invents them — and books, moves or cancels on behalf of the customer it's talking to. Create it from the channel's tool library: **Chat → WhatsApp → Tools**, **Chat → SMS → Tools**, or the voice agent's tools page.

<Frame caption="Selecting the Calendar Tool type">
  <img src="https://mintcdn.com/dialtu-0be120d3/4ZUrsSjBIO2Dd9Ez/images/en/calendar/tool-type-picker.png?fit=max&auto=format&n=4ZUrsSjBIO2Dd9Ez&q=85&s=9c8e5454ab515e4fc785ca7f4c021e65" alt="New tool creation screen named clinic_calendar with the Tool Type list (API Tool, End Chat Tool, Handoff Tool, Send WhatsApp Template, Integration Tool, Calendar Tool selected, Catalog Tool), Calendar Capabilities with List professionals, Check availability and Book an appointment checked, Days to look ahead 7 with a warning about the 14-day 'Dermatology waiting list' horizon, and a 'Required to create' checklist." width="2880" height="1800" data-path="images/en/calendar/tool-type-picker.png" />
</Frame>

## Capabilities

<Frame caption="Choosing what the agent can do on the calendar">
  <img src="https://mintcdn.com/dialtu-0be120d3/4ZUrsSjBIO2Dd9Ez/images/en/calendar/tool-capabilities.png?fit=max&auto=format&n=4ZUrsSjBIO2Dd9Ez&q=85&s=d7ba82cb1b48c7ad796aed07d4ad5491" alt="clinic_calendar Calendar Tool editor (CALENDAR, WHATSAPP) showing 'Calendar Capabilities' with 'Where it can book' service chips, 'Look things up 5/6' cards (List services, List professionals, List appointment types, Check availability, List the customer's appointments checked), 'Change the calendar 3/3' (Book, Reschedule, Cancel), 'Waiting list 2/3', Behaviour fields Times to offer 5 and Days to look ahead 14, and a Summary sidebar." width="2880" height="1800" data-path="images/en/calendar/tool-capabilities.png" />
</Frame>

Tick what this agent may do:

| Group                   | Capabilities                                                                                                                                              | Default                                |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| **Look things up**      | List services · List professionals · List appointment types · Check availability · Check a professional's availability · List the customer's appointments | List professionals, Check availability |
| **Change the calendar** | Book an appointment · Reschedule an appointment · Cancel an appointment                                                                                   | Book an appointment                    |
| **Waiting list**        | Check waiting list · Add to waiting list · Remove from waiting list                                                                                       | off                                    |

<Tip>
  *Booking and rescheduling only work well when the agent can also check availability.* Keep those together.
</Tip>

The agent only ever touches the calling customer's own appointments, matched by phone. Booking rules apply exactly as they do for a human.

## Behaviour

On the right rail:

| Setting               | Range                         | Default       |
| --------------------- | ----------------------------- | ------------- |
| **Slots offered**     | 1–20                          | 5             |
| **Days ahead**        | 1–30                          | 7             |
| **Where it can book** | every service, or a selection | every service |

<Note>
  If a waiting list this agent feeds has a longer horizon than **Days ahead**, the rail warns you.
</Note>

## Event title and extra questions

<Frame caption="Event title template and notes instruction">
  <img src="https://mintcdn.com/dialtu-0be120d3/4ZUrsSjBIO2Dd9Ez/images/en/calendar/tool-title-intake.png?fit=max&auto=format&n=4ZUrsSjBIO2Dd9Ez&q=85&s=4662af0610849ec3f1858acb3b50d094" alt="clinic_calendar tool editor 'Event title' section with the template 'client.name · service.name', placeholder chips such as client.first_name, service.name, professional.name and field.reason, a preview reading 'Ana Pérez · Cardiology', an empty Notes instruction box, and the first Extra question 'Reason for visit' below." width="2880" height="1800" data-path="images/en/calendar/tool-title-intake.png" />
</Frame>

**Event title** — a template rendered into every appointment the agent books, up to 120 characters. Placeholders: `{client.name}` (default), `{client.first_name}`, `{client.last_name}`, `{client.email}`, `{client.phone}`, `{service.name}`, `{event_type.name}`, `{professional.name}`, `{summary}`, and `{field.<key>}` for each extra question. **Summary instruction** tells the agent what to put in `{summary}`; **Notes instruction** what to write in the appointment's notes (default: what the customer said, in 1–3 sentences).

<Frame caption="Intake questions the agent collects">
  <img src="https://mintcdn.com/dialtu-0be120d3/4ZUrsSjBIO2Dd9Ez/images/en/calendar/tool-intake-fields.png?fit=max&auto=format&n=4ZUrsSjBIO2Dd9Ez&q=85&s=ca9f4bec116bac5a5b3bfa188f6a91c5" alt="clinic_calendar tool editor scrolled to 'Extra questions 3/12' showing three intake fields: 'Reason for visit' (Text, required, field.reason, 'Why the patient wants to see the doctor.'), 'Insurance' (Choice, required, field.insurance, options Blue Cross, Aetna, Cigna, UnitedHealthcare, Humana, Self-pay) and 'First visit' (Yes / no, optional)." width="2880" height="1800" data-path="images/en/calendar/tool-intake-fields.png" />
</Frame>

**Extra questions** — up to 12 fields the agent collects before booking:

| Property        | Rules                                                                             |
| --------------- | --------------------------------------------------------------------------------- |
| **Label**       | ≤ 60 chars, shown in the appointment detail                                       |
| **Key**         | `a-z`, digits, `_`; must start with a letter; ≤ 40 chars; some names are reserved |
| **Type**        | Text · Email · Phone · ID document · Yes-no · Choice (≤ 20 options)               |
| **Description** | ≤ 300 chars — the hint the agent uses to ask                                      |
| **Required**    | A required answer can refuse the booking; an optional one never blocks it         |

Answers appear on the appointment under **Appointment data**, and the booking is marked **AI · WhatsApp** (or SMS / call) with a **View conversation** link.

## What doesn't exist

* **Atlas building calendar tools** — Atlas can attach an existing one, not create it.
* **A calendar tool on the Solara voice engine.**
* **Booking for a different phone number** than the one in the conversation.

## Next step

<Card title="Troubleshooting" icon="wrench" href="/en/calendar/troubleshooting">
  When a booking doesn't land.
</Card>