Cozi MCP Server

Partial-update an appointment

update_appointment

Instructions

Partial-update an appointment. The Cozi PUT semantics replace ALL fields, so this tool first fetches the existing appointment from the (year, month) page and merges your changes — only fields you pass are altered. To switch a timed appointment to all-day pass all_day=true; to switch to timed pass new start/end. Passing end re-spans the event against its (possibly newly set) start day, so an end on a later date makes it multi-day and one on the start day collapses it back; passing start alone moves the event and keeps its length, and all_day=true preserves the span. A bare date (e.g. '2026-06-15') is accepted for start/end when the event is, or is being made, all-day; on a timed event it is an error. A recurring series (recurring: true in get_calendar) needs scope: 'this' changes only the occurrence on occurrence_day (Cozi stores it as its own appointment, returned here), 'this_and_following' changes it and every later one (returned as the new series), 'series' changes every occurrence and keeps the rule unless repeat replaces it. repeat also turns a one-off into a series. Holidays, subscribed calendars and birthdays cannot be changed.

Input Schema

Name	Required	Description
`end`	No
`year`	Yes
`month`	Yes
`notes`	No
`scope`	No	Required for a recurring series: 'this' = only the occurrence on occurrence_day, 'this_and_following' = that occurrence and every later one, 'series' = every occurrence.
`start`	No
`notify`	No	Send Cozi's change notification to the attendees who have notifications on, like the Cozi app's 'notify' option. Off by default; only when the user asks for it.
`repeat`	No	Make it repeat. `interval` 2 = every other day/week/month/year. Weekly: `weekdays` (e.g. ['MO','WE']; default the start's weekday, which must be included). Monthly/yearly: `monthly_by` 'day_of_month' (default, e.g. the 15th) or 'weekday' (e.g. the 2nd Tuesday; a 5th weekday means the last). `until` is the last possible day (YYYY-MM-DD); omit it to repeat forever.
`all_day`	No
`subject`	No
`location`	No
`attendees`	No
`reminders`	No	Reminder lead times in minutes before the start, e.g. [30, 1440]. [] clears them on an update.
`appointment_id`	Yes
`occurrence_day`	No	With scope 'this' or 'this_and_following': the occurrence's `day` as get_calendar lists it.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv2.5.0Oct 14, 2026

addedInput schema / properties / notify

Added value: +{
+  "description": "Send Cozi's change notification to the attendees who have notifications on, like the Cozi app's 'notify' option. Off by default; only when the user asks for it.",
+  "type": "boolean"
+}

addedInput schema / properties / occurrence_day

Added value: +{
+  "description": "With scope 'this' or 'this_and_following': the occurrence's `day` as get_calendar lists it.",
+  "type": "string"
+}

addedInput schema / properties / reminders

Added value: +{
+  "description": "Reminder lead times in minutes before the start, e.g. [30, 1440]. [] clears them on an update.",
+  "items": {
+    "minimum": 0,
+    "type": "integer"
+  },
+  "type": "array"
+}

addedInput schema / properties / repeat

Added value: +{
+  "additionalProperties": false,
+  "description": "Make it repeat. `interval` 2 = every other day/week/month/year. Weekly: `weekdays` (e.g. ['MO','WE']; default the start's weekday, which must be included). Monthly/yearly: `monthly_by` 'day_of_month' (default, e.g. the 15th) or 'weekday' (e.g. the 2nd Tuesday; a 5th weekday means the last). `until` is the last possible day (YYYY-MM-DD); omit it to repeat forever.",
+  "properties": {
+    "frequency": {
+      "enum": [
+        "daily",
+        "weekly",
+        "monthly",
+        "yearly"
+      ],
+      "type": "string"
+    },
+    "interval": {
+      "minimum": 1,
+      "type": "integer"
+    },
+    "monthly_by": {
+      "enum": [
+        "day_of_month",
+        "weekday"
+      ],
+      "type": "string"
+    },
+    "until": {
+      "type": "string"
+    },
+    "weekdays": {
+      "items": {
+        "enum": [
+          "SU",
+          "MO",
+          "TU",
+          "WE",
+          "TH",
+          "FR",
+          "SA"
+        ],
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "frequency"
+  ],
+  "type": "object"
+}

addedInput schema / properties / scope

Added value: +{
+  "description": "Required for a recurring series: 'this' = only the occurrence on occurrence_day, 'this_and_following' = that occurrence and every later one, 'series' = every occurrence.",
+  "enum": [
+    "this",
+    "this_and_following",
+    "series"
+  ],
+  "type": "string"
+}

First observedv2.0.1May 13, 2026

TDQS

A4.5/5.0

Behavior5/5

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses the underlying Cozi PUT-replace semantics and the fetch-and-merge workaround, the exact start/end re-spans and length-preservation behavior, the all_day exceptions, an explicit error condition (bare date on a timed event), and immutable entities. It even notes return behavior for scope 'this' vs 'this_and_following'.

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?

The purpose and merge mechanism are front-loaded, followed by parameter-specific rules in a logical order. It is dense and long, but nearly every clause conveys a distinct behavioral rule rather than restating the name or schema. Slightly heavy, yet the volume is justified by the tool's complexity.

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

Completeness4/5

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

For a 15-parameter mutation tool with no annotations and no output schema, the description is unusually complete on mutation semantics, error cases, and editability limits. The remaining gaps are secondary parameter meanings (notify, attendees, reminders) and auth/permission prerequisites, which keep it just shy of fully self-sufficient.

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

Parameters4/5

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

Schema description coverage is only 33%, so the description must compensate, and it does for the hardest parameters: start, end, all_day, scope, and repeat semantics are spelled out in detail beyond the schema. It does not explain notify, attendees, reminders, subject, location, appointment_id, year, or month, leaving several parameters undocumented in both places, so it stops short of fully closing the gap.

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?

Opens with a specific verb+resource ('Partial-update an appointment'), immediately distinguishing it from create_appointment and delete_appointment. The first sentence also clarifies that it is a merge-update rather than a destructive replace, which is the key differentiator an agent needs. No sibling ambiguity remains.

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

Usage Guidelines4/5

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

Gives rich conditional guidance on when to use which parameters: all_day=true to make all-day, new start/end to make timed, scope required for recurring series, and explicitly states holidays/subscribed calendars/birthdays cannot be changed. However it never names sibling alternatives (e.g. create_appointment, delete_appointment) to route between tools, so it falls short of the explicit-alternatives bar.

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

Deploy Server

Partial-update an appointment

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools