# Calendar — Tool reference

All times on the wire are ISO-8601 with an offset or `Z`. Calendar refs accept an id (`cal_…`) or a slug.

## Convention
- `guide` — read first. `whoami` — session + YOUR timezone + whether the call is attended. `docs`.

## Calendars
- `list_calendars` — everything, with `yourTimezone`.
- `create_calendar { name, slug?, description?, color?, tz?, bookable?, hours?, slotMinutes?, bufferMinutes?, minNoticeMinutes?, maxDaysAhead? }` — 25 per project.
- `update_calendar { calendar, …same fields… }` — pass only what changes; `hours: null` clears.

`hours` is `{ "mon": [["09:00","17:00"], …], … }` in the calendar's zone. Missing day = closed.

## Events
- `list_events { calendar, from?, to?, includeCancelled? }` — occurrences (recurring expanded), each with `local` in its zone. Window ≤ 400 days; default 14.
- `get_event { eventId }`.
- `create_event { calendar, title, start, end? | durationMinutes?, allDay?, date?, endDate?, tz?, rrule?, description?, location?, status? }`.
- `update_event { eventId, …any of the above… }` — bumps SEQUENCE.
- `cancel_event { eventId, reason? }` — stays in the feed as CANCELLED for 30 days.

Recurrence (`rrule`): `FREQ=DAILY|WEEKLY|MONTHLY|YEARLY`, `INTERVAL`, `COUNT` or `UNTIL`, `BYDAY` (weekly, plain weekdays), `BYMONTHDAY` (monthly). Anything else is refused.

## Booking (the receptionist's two tools)
- `find_free { calendar, from?, to?, durationMinutes?, limit? }` — open slots on a **bookable** calendar. Default window 7 days.
- `book { calendar, start, durationMinutes?, name, phone?, email?, note?, title? }` — re-validates the slot; sends SMS/email confirmation as a RESULT (`confirmation.sms: sent|failed|skipped`); returns `sayToCaller`.

Unattended callers (phone lines, channels, schedulers) may use ONLY these two, and only on bookable calendars.

## Feeds
- `create_feed_link { calendar, label? }` → `{ url, webcal }`. The URL is the credential; shown once.
- `list_feed_links { calendar }` — labels, fetch counts, revoked.
- `revoke_feed_link { feedId, confirm: true }`.

## Limits
25 calendars/project · 10,000 events/calendar · 500 events created per actor per UTC day · 400-day windows · 200 slots per `find_free`.