update_occurrence_note
Adds, replaces, or clears the note on one Occurrence. Use it when the user wants to record context about a specific scheduled instance, such as how a workout went.
Permission and annotations
Required scope: cadence.occurrences.write. Contract 1.7.0; available since 1.0.0.
title: “Update Occurrence note”readOnlyHint: falsedestructiveHint: trueidempotentHint: trueopenWorldHint: false
Replaces the previous note text, which Cadence does not keep in history, so destructiveHint is true under both Claude’s and OpenAI’s guidance. The same arguments produce the same note, so idempotentHint is true. openWorldHint is false.
Input
Required means required within the containing object. Variant fields apply only to that variant; children of nullable values apply when non-null. Unknown fields are rejected.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
occurrence_id |
yes | string | Occurrence id.; format: uuid |
note |
yes | string | Note text. An empty string clears the note.; maxLength: 2000; pattern: ^[^\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]*$ |
expected_revision |
no | string | Revision the client last read. If the Occurrence changed since, the call fails with conflict.; minLength: 1; maxLength: 128; pattern: ^[A-Za-z0-9._:-]+$ |
idempotency_key |
no | string | Optional client-chosen key. Repeating a call with the same key and input within 24 hours returns the first result and changes nothing.; minLength: 8; maxLength: 128; pattern: ^[A-Za-z0-9._:-]+$ |
Output
Required means required within the containing object. Variant fields apply only to that variant; children of nullable values apply when non-null. Unknown fields are rejected.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
occurrence |
yes | object | An Occurrence: one scheduled instance of a Behavior on one local date. |
occurrence.id |
yes | string | format: uuid |
occurrence.behavior_id |
yes | string | format: uuid |
occurrence.behavior_title |
yes | string | |
occurrence.category_name |
yes | string or null | |
occurrence.local_date |
yes | string | Calendar date (YYYY-MM-DD) in the account timezone.; format: date |
occurrence.timezone |
yes | string | IANA timezone name.; minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_+\-/]+$ |
occurrence.scheduled_for |
yes | string | Planned start as a UTC instant. It never changes when the Occurrence is moved for the day.; format: date-time; pattern: [Zz]$ |
occurrence.effective_start_at |
yes | string | Where the Occurrence sits today: its moved start when move is set, otherwise the planned start. Show, remind and match by this time.; format: date-time; pattern: [Zz]$ |
occurrence.move |
yes | object or null | Set while a per-day move places the Occurrence away from its planned time. Null otherwise. |
occurrence.move.planned_start_at |
yes | string | The planned start. It does not change when the item moves.; format: date-time; pattern: [Zz]$ |
occurrence.move.start_at |
yes | string | The moved start.; format: date-time; pattern: [Zz]$ |
occurrence.move.end_at |
yes | string | The moved end. A move keeps the item’s length.; format: date-time; pattern: [Zz]$ |
occurrence.schedule |
yes | object | |
occurrence.schedule.kind |
yes | string | Values: exact, range |
occurrence.schedule.preset |
yes | string or null | Values: morning, afternoon, evening, night, null |
occurrence.schedule.start_time |
yes | string | Local wall-clock time, 24-hour HH:MM.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
occurrence.schedule.end_time |
yes | string or null | Local wall-clock time, 24-hour HH:MM.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
occurrence.schedule.label |
yes | string | |
occurrence.status |
yes | string | Stored status.; Values: unresolved, completed, not_completed |
occurrence.status_label |
yes | string | Values: Unresolved, Completed, Not Completed |
occurrence.needs_decision |
yes | boolean | Derived: true when the status is unresolved and local_date is before today. Never stored. |
occurrence.origin |
yes | string | scheduled comes from the Behavior’s schedule; opportunity was added to its day from the person’s opportunities (contract 1.6.0).; Values: scheduled, opportunity |
occurrence.added_by |
yes | string or null | Who added an opportunity Occurrence: user, daily_brief, chat or mcp. Null for scheduled Occurrences.; Values: user, daily_brief, chat, mcp, null |
occurrence.completed_at |
yes | string or null | format: date-time; pattern: [Zz]$ |
occurrence.status_marked_at |
yes | string or null | format: date-time; pattern: [Zz]$ |
occurrence.note |
yes | string or null | |
occurrence.parent_behavior_id |
no | string or null | Parent Behavior id when the Occurrence belongs to a sub-behavior, otherwise null. Present on reads and on set_parent_occurrence_status (contract 1.7.0).; format: uuid |
occurrence.parent_title |
no | string or null | Parent Behavior title when the Occurrence belongs to a sub-behavior, otherwise null. |
occurrence.updated_at |
yes | string | format: date-time; pattern: [Zz]$ |
occurrence.revision |
yes | string | Opaque version token of this record. Send it back as expected_revision to avoid overwriting a newer change.; minLength: 1; maxLength: 128; pattern: ^[A-Za-z0-9._:-]+$ |
changed |
yes | boolean | False when the note already had this text. |
Example call
Synthetic contract fixture. Replace identifiers and dates with records returned for your account. This is the SDK tools/call payload, not a complete HTTP request.
{
"name": "update_occurrence_note",
"arguments": {
"occurrence_id": "00000005-1111-4111-8111-000000000005",
"note": "Felt good.\nCold out.",
"expected_revision": "o1.3"
}
}
Example result
Synthetic success data from a contract fixture, shown as structuredContent. Input and output examples validate independently; they are not a recorded transaction.
{
"occurrence": {
"id": "00000005-1111-4111-8111-000000000005",
"behavior_id": "00000001-1111-4111-8111-000000000001",
"behavior_title": "Morning walk",
"category_name": "Fitness",
"local_date": "2026-10-18",
"timezone": "America/New_York",
"scheduled_for": "2026-10-18T11:30:00Z",
"effective_start_at": "2026-10-18T11:30:00Z",
"move": null,
"schedule": {
"kind": "exact",
"preset": null,
"start_time": "07:30",
"end_time": null,
"label": "7:30 AM"
},
"status": "completed",
"status_label": "Completed",
"needs_decision": false,
"origin": "scheduled",
"added_by": null,
"completed_at": "2026-10-18T11:41:00Z",
"status_marked_at": "2026-10-18T11:41:00Z",
"note": "Felt good.\nCold out.",
"updated_at": "2026-10-18T13:00:00Z",
"revision": "o1.3"
},
"changed": false
}
Errors
invalid_input: The input does not match the tool’s schema or rules.field_errorsnames each problem.authentication_required: The access token is missing, expired, revoked, or issued for another resource. Reconnect Cadence.rate_limited: Too many requests for this connection. Retry afterretry_after_seconds.service_unavailable: Cadence integrations are temporarily unavailable.internal_error: Cadence could not complete the request. Nothing is assumed to have changed; retry once with the sameidempotency_key.insufficient_scope: The connection does not include the permission this tool needs.required_scopeslists it.not_found: No record with that id exists for this account.conflict: The record changed since it was read:expected_statusorexpected_revisionis stale. Nothing changed.idempotency_key_reused: Theidempotency_keywas already used with a different input. Use a new key for a new request.
Output size limits can also return limit_exceeded. See error handling, limits, and safe retries.