icloud-mcp

calendar_update_event

Idempotent

Edit specific details of an existing calendar event, such as time, title, location, or guests, without altering other fields. Change one occurrence or the entire repeating series.

Instructions

Change chosen fields of an existing event, or of one date of a repeating event, leaving every field you do not pass as it is.

Use when: the owner wants to reschedule, rename, relocate, re-alarm or change the guests of an event. Not for putting it on another calendar (use calendar_move_event), cancelling it (use calendar_delete_event), answering an invitation (use calendar_respond_to_event) or making a new one (use calendar_create_event). Parameters:

uid comes from calendar_list_events.
occurrence_start (that date's recurrence_id, else its start) limits the change to one date; omitted, the whole series changes. rrule cannot be combined with it.
Changing only start keeps the duration; start and end must both be dates or both date-times.
attendees replaces the guest list (people kept keep their answers; [] removes everyone). add_attendees / remove_attendees change single people and cannot be combined with attendees.
alarms_minutes_before replaces all alarms.
'' clears location, description, url or rrule. Behavior:
When the event has or gets guests, iCloud emails them the update and removed guests get a cancellation.
That is refused unless the server allows calendar invites (ALLOW_CALENDAR_INVITES), so on such servers an event with guests cannot be edited here at all.
The write only lands if the event is unchanged since it was read.
Repeating the same call leaves the event in the same state. Returns: {updated, uid, calendar, event}, plus occurrence_only for one date and, when guests are set, delivery [{address, meaning, ok}] (ok=false = iCloud did not deliver). Errors: "No event with uid" (list again), "changed on the server since it was read" (read it again and re-apply), "no occurrence starting at ..." (use the listed recurrence_id or start), invitations blocked by settings.

Input Schema

TableJSON Schema

Name	Required	Description
`end`	No	New end (ISO 8601).
`uid`	Yes	Event uid (from calendar_list_events).
`url`	No	New link. '' clears it.
`rrule`	No	New repeat rule. '' removes the repetition.
`start`	No	New start (ISO 8601). Changing only the start keeps the event's duration.
`summary`	No	New title.
`calendar`	No	Calendar name (calendar_list_calendars); omit for all.
`location`	No	New location. '' clears it.
`timezone`	No	IANA timezone for times without an offset, e.g. 'Europe/Berlin'; default the owner's.
`attendees`	No	The COMPLETE guest list: it replaces the current one, so include everyone who should stay invited. iCloud emails newly added people.
`description`	No	New notes. '' clears them.
`location_geo`	No	'lat,lon' for the map card and travel routing. '' removes it; omit to leave it alone.
`add_attendees`	No	People to add; everyone else stays as they are. Not together with attendees.
`travel_origin`	No	New starting address. Omit to keep the current one.
`travel_minutes`	No	New Apple travel time in minutes before the start; 0 removes it. Omit to leave it alone. Changing only this keeps the existing starting point.
`travel_routing`	No	BICYCLE, WALKING, AUTOMOBILE or TRANSIT.
`occurrence_start`	No	ONE occurrence of a repeating event (listed with recurring or recurrence_id) to change: its 'recurrence_id' if set, else its 'start'. Omit to change the whole series.
`remove_attendees`	No	People to take off; iCloud emails them a cancellation. Not together with attendees.
`travel_origin_geo`	No	Coordinates of travel_origin as 'lat,lon'.
`alarms_minutes_before`	No	The complete list of reminders, minutes before the start; replaces the current ones.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 30, 2026

changedInput schema / properties / occurrence_start / description

Previous value: -"ONE occurrence of a repeating event to change: its 'recurrence_id' if set, else its 'start'. Omit to change the whole series."New value: +"ONE occurrence of a repeating event (listed with recurring or recurrence_id) to change: its 'recurrence_id' if set, else its 'start'. Omit to change the whole series."

changedOutput schema / (root)

Previous value: -{
-  "additionalProperties": true,
-  "title": "calendar_update_eventDictOutput",
-  "type": "object"
-}New value: +null

Changed79 schema fields changedv0.7.0Sep 24, 2026

addedInput schema / properties / add_attendees

Added value: +{
+  "description": "People to add; everyone else stays as they are. Not together with attendees.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

removedInput schema / properties / alarms_minutes_before / anyOf

Removed value: -[
-  {
-    "items": {
-      "type": "integer"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / alarms_minutes_before / default
```
Removed value: -null
```
addedInput schema / properties / alarms_minutes_before / items
```
Added value: +{
+  "type": "integer"
+}
```
removedInput schema / properties / alarms_minutes_before / title
```
Removed value: -"Alarms Minutes Before"
```
addedInput schema / properties / alarms_minutes_before / type
```
Added value: +"array"
```

removedInput schema / properties / attendees / anyOf

Removed value: -[
-  {
-    "items": {
-      "type": "string"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / attendees / default
```
Removed value: -null
```
addedInput schema / properties / attendees / items
```
Added value: +{
+  "type": "string"
+}
```
removedInput schema / properties / attendees / title
```
Removed value: -"Attendees"
```
addedInput schema / properties / attendees / type
```
Added value: +"array"
```

removedInput schema / properties / calendar / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / calendar / default
```
Removed value: -null
```

changedInput schema / properties / calendar / description

Previous value: -"Calendar name from calendar_list_calendars. Omit to search all calendars."New value: +"Calendar name (calendar_list_calendars); omit for all."

removedInput schema / properties / calendar / title
```
Removed value: -"Calendar"
```
addedInput schema / properties / calendar / type
```
Added value: +"string"
```

removedInput schema / properties / description / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / description / default
```
Removed value: -null
```
removedInput schema / properties / description / title
```
Removed value: -"Description"
```
addedInput schema / properties / description / type
```
Added value: +"string"
```

removedInput schema / properties / end / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / end / default
```
Removed value: -null
```
removedInput schema / properties / end / title
```
Removed value: -"End"
```
addedInput schema / properties / end / type
```
Added value: +"string"
```

removedInput schema / properties / location / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / location / default
```
Removed value: -null
```
removedInput schema / properties / location / title
```
Removed value: -"Location"
```
addedInput schema / properties / location / type
```
Added value: +"string"
```

removedInput schema / properties / location_geo / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / location_geo / default
```
Removed value: -null
```

changedInput schema / properties / location_geo / description

Previous value: -"Coordinates of the location as 'lat,lon'. Apple needs these for the map card and to route travel time. '' removes it; omit to leave it alone."New value: +"'lat,lon' for the map card and travel routing. '' removes it; omit to leave it alone."

removedInput schema / properties / location_geo / title
```
Removed value: -"Location Geo"
```
addedInput schema / properties / location_geo / type
```
Added value: +"string"
```

removedInput schema / properties / occurrence_start / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / occurrence_start / default
```
Removed value: -null
```

changedInput schema / properties / occurrence_start / description

Previous value: -"For a repeating event: the start of the ONE occurrence to change, taken from calendar_list_events (its 'recurrence_id' if set, otherwise its 'start'). Omit to change the whole series."New value: +"ONE occurrence of a repeating event to change: its 'recurrence_id' if set, else its 'start'. Omit to change the whole series."

removedInput schema / properties / occurrence_start / title
```
Removed value: -"Occurrence Start"
```
addedInput schema / properties / occurrence_start / type
```
Added value: +"string"
```

addedInput schema / properties / remove_attendees

Added value: +{
+  "description": "People to take off; iCloud emails them a cancellation. Not together with attendees.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

removedInput schema / properties / rrule / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / rrule / default
```
Removed value: -null
```
removedInput schema / properties / rrule / title
```
Removed value: -"Rrule"
```
addedInput schema / properties / rrule / type
```
Added value: +"string"
```

removedInput schema / properties / start / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / start / default
```
Removed value: -null
```
removedInput schema / properties / start / title
```
Removed value: -"Start"
```
addedInput schema / properties / start / type
```
Added value: +"string"
```

removedInput schema / properties / summary / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / summary / default
```
Removed value: -null
```
removedInput schema / properties / summary / title
```
Removed value: -"Summary"
```
addedInput schema / properties / summary / type
```
Added value: +"string"
```

removedInput schema / properties / timezone / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / timezone / default
```
Removed value: -null
```

changedInput schema / properties / timezone / description

Previous value: -"IANA timezone for start/end without an offset, e.g. 'Europe/Berlin'. Omit to use the server timezone."New value: +"IANA timezone for times without an offset, e.g. 'Europe/Berlin'; default the owner's."

removedInput schema / properties / timezone / title
```
Removed value: -"Timezone"
```
addedInput schema / properties / timezone / type
```
Added value: +"string"
```

removedInput schema / properties / travel_minutes / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / travel_minutes / default
```
Removed value: -null
```
removedInput schema / properties / travel_minutes / title
```
Removed value: -"Travel Minutes"
```
addedInput schema / properties / travel_minutes / type
```
Added value: +"integer"
```

removedInput schema / properties / travel_origin / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / travel_origin / default
```
Removed value: -null
```
removedInput schema / properties / travel_origin / title
```
Removed value: -"Travel Origin"
```
addedInput schema / properties / travel_origin / type
```
Added value: +"string"
```

removedInput schema / properties / travel_origin_geo / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / travel_origin_geo / default
```
Removed value: -null
```
removedInput schema / properties / travel_origin_geo / title
```
Removed value: -"Travel Origin Geo"
```
addedInput schema / properties / travel_origin_geo / type
```
Added value: +"string"
```

removedInput schema / properties / travel_routing / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / travel_routing / default
```
Removed value: -null
```
removedInput schema / properties / travel_routing / title
```
Removed value: -"Travel Routing"
```
addedInput schema / properties / travel_routing / type
```
Added value: +"string"
```

changedInput schema / properties / uid / description

Previous value: -"Event uid from calendar_list_events, calendar_get_event or calendar_create_event results."New value: +"Event uid (from calendar_list_events)."

removedInput schema / properties / uid / title
```
Removed value: -"Uid"
```

removedInput schema / properties / url / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / url / default
```
Removed value: -null
```
removedInput schema / properties / url / title
```
Removed value: -"Url"
```
addedInput schema / properties / url / type
```
Added value: +"string"
```

removedInput schema / title

Removed value: -"calendar_update_eventArguments"

Changed1 schema field changedv0.4.0Sep 24, 2026

addedInput schema / properties / occurrence_start

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "For a repeating event: the start of the ONE occurrence to change, taken from calendar_list_events (its 'recurrence_id' if set, otherwise its 'start'). Omit to change the whole series.",
+  "title": "Occurrence Start"
+}

First observedv0.1.0Sep 23, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well past the annotations: discloses that guests get emailed and removed guests receive cancellations, that edits are refused unless ALLOW_CALENDAR_INVITES is set, that the write is optimistic-concurrency guarded ('only lands if the event is unchanged since it was read'), and that repeat calls are idempotent (matching idempotentHint=true). It also enumerates concrete error strings and their remedies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well front-loaded with the core behavior in the first sentence, then cleanly sectioned into Use when / Parameters / Behavior / Returns. It is dense and runs long, with some restatement of schema-level detail (e.g. the '' clear semantics appear both here and in the schema), which keeps it just short of immaculate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 20-parameter mutation tool with no output schema, the description supplies the missing pieces: the return shape ({updated, uid, calendar, event}, occurrence_only, delivery), the failure modes and their recovery steps, and the invite-permission precondition. Nothing an agent needs to call it correctly is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, but the description adds cross-parameter semantics the schema cannot express: rrule cannot be combined with occurrence_start, start and end must both be dates or both date-times, attendees/add_attendees/remove_attendees are mutually exclusive, and alarms_minutes_before replaces the whole list. The '' clearing convention and the uid provenance are also spelled out.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Change chosen fields of an existing event'), and adds the non-obvious scope distinction that it works on one date of a repeating event. It explicitly names the siblings it is not (calendar_move_event, calendar_delete_event, calendar_respond_to_event, calendar_create_event), so an agent can disambiguate without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit 'Use when' trigger list (reschedule, rename, relocate, re-alarm, change guests) and an explicit 'Not for' list routing five alternative intents to the correct sibling tools. Both when-to-use and when-not-to-use are covered with no inference required.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

calendar_update_event

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools