calendar_create_event
Book one iCloud calendar event with location, notes, alarms, travel time, or guests in a single call. Use when scheduling or adding an event, not for updates or to-dos.
Instructions
Create one calendar event, optionally repeating, with location, notes, alarms, travel time and invited guests, all in a single call.
Use when: the owner asks to book, schedule or add something to the calendar. Not for changing an event (use calendar_update_event), a to-do without a time slot (use reminders_create_reminder), answering someone else's invitation (use calendar_respond_to_event) or finding a time (use calendar_find_free_time first). For a booking found in mail, mail_extract_bookings supplies ready arguments. Parameters:
Convert relative dates ('tomorrow at 3pm') to ISO 8601 yourself.
start and end must both be dates (all-day) or both date-times, end after start.
Omitting calendar uses DEFAULT_CALENDAR, else 'Calendar' or 'Home', else the first.
travel_origin and travel_routing need travel_minutes (1 to 1440), taken from the owner or maps_get_travel_time, never guessed.
location_geo needs location.
rrule may fire at most 48 times a day.
Example: summary='Lunch with Anna', start='2026-09-21T12:30', end='2026-09-21T13:30', location='Cafe X', attendees=['anna@example.org'], alarms_minutes_before=[30]. Behavior:
The owner is the organizer and iCloud emails each attendee an invitation itself, so send no separate mail.
Attendees are refused unless the server allows calendar invites (ALLOW_CALENDAR_INVITES), and are limited by INVITE_ALLOWLIST and MAX_ATTENDEES (default 10).
Before writing it checks all calendars for overlaps (travel counted; all-day events never conflict) and the target calendar for the same title at the same start; on_conflict / on_duplicate='refuse' then create nothing.
With request_id a retry returns the first event, never a second copy; without it a repeat creates another event. Returns: {created, uid, calendar, event, conflicts, possible_duplicate, now}; with guests also invited and delivery [{address, meaning, ok}]: ok=false means iCloud did not deliver, so do not tell the owner that person was invited. created=false (with already_existed, conflicts or possible_duplicate) means nothing was written. Tell the owner about any conflicts. Errors: invitations blocked by settings, an unusable address (look it up with contacts_search_contacts or mail_find_correspondent), invalid dates or rrule; each message says what to change.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"summary": "<summary>",
"start": "<start>"
},
"name": "calendar_create_event"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | End, same format as start. Omit for a 1-hour event (1 day if all-day). A date-only end is inclusive. | |
| url | No | A link to attach to the event. | |
| rrule | No | Repeat rule (RFC 5545), e.g. 'FREQ=WEEKLY;BYDAY=MO,WE;COUNT=10'. Omit for a one-off event. | |
| start | Yes | Start: ISO 8601 date-time such as 2026-09-21T15:00 (no offset = 'timezone'), or a date such as 2026-09-21 for an all-day event. | |
| summary | Yes | Event title. | |
| calendar | No | Calendar name (calendar_list_calendars); omit for the default. | |
| location | No | Place name or address. | |
| timezone | No | IANA timezone for times without an offset, e.g. 'Europe/Berlin'; default the owner's. | |
| attendees | No | People to invite: ['anna@example.org'] or ['Anna <anna@example.org>']. iCloud emails each one an invitation, so do not send a separate email. Only a name? Look it up with contacts_search_contacts, then mail_find_correspondent. | |
| request_id | No | Retry key unique to this request (e.g. 'lunch-anna-2026-09-24'): a repeat with the same key returns the first result, never a second copy. | |
| description | No | Notes for the event. Links in the text stay clickable. | |
| on_conflict | No | 'refuse' = create nothing when it overlaps another event; the result lists 'conflicts' either way. | warn |
| location_geo | No | 'lat,lon'. Not needed: Apple maps the location text itself. Only to pin an exact spot; '' removes the map. | |
| on_duplicate | No | 'refuse' = create nothing when the same title at the same time is already on that calendar. | warn |
| travel_origin | No | Starting address for the travel time, e.g. 'Unter den Linden 1, 10117 Berlin'. Optional. | |
| travel_minutes | No | Apple travel time in minutes before the start: a travel block plus an alarm at leave-by, so do not move the start or write a leave-by time. 0 removes it. | |
| travel_routing | No | How they travel: BICYCLE (default), WALKING, AUTOMOBILE or TRANSIT. Only used when travel_origin is given. | |
| travel_origin_geo | No | Coordinates of travel_origin as 'lat,lon', e.g. '52.5163,13.3777'. Optional, and only meaningful with travel_origin. | |
| alarms_minutes_before | No | Reminders, as minutes before the start: [60, 15]. Use 0 for at start time. |