add_opportunity_occurrence
Adds one of the user’s opportunity Behaviors (is_opportunity true, running, not archived) to today: at an exact start_time, in a time range (start_time and end_time, or a preset), or, with mark_completed, as done now, marked Completed at the current minute. It adds a new Occurrence and changes no schedule. When a rule stops it, nothing changes and refusal says why. remove_opportunity_occurrence takes back an item added by mistake.
Permission and annotations
Required scope: cadence.occurrences.write. Contract 1.7.0; available since 1.6.0.
title: “Add opportunity to today”readOnlyHint: falsedestructiveHint: falseidempotentHint: falseopenWorldHint: false
Adds a new Occurrence and changes no existing record, like create_behavior, so destructiveHint is false under both Claude’s and OpenAI’s guidance; readOnlyHint is false, so clients still treat it as a write. Calling it twice without an idempotency_key adds two items, so idempotentHint is false. openWorldHint is false: only the user’s own Cadence account is touched.
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 |
|---|---|---|---|
behavior_id |
yes | string | Behavior id.; format: uuid |
start_time |
no | string | Start today in the Behavior’s timezone. Alone it is an exact time; with end_time it starts a range.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
end_time |
no | string | End of a custom range today. Needs start_time and must differ from it; an earlier end runs past midnight.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
preset |
no | string | A time-of-day range instead of start_time: Morning 06:00-12:00, Afternoon 12:00-18:00, Evening 18:00-00:00, Night 00:00-06:00.; Values: morning, afternoon, evening, night |
mark_completed |
no | boolean | Done now: add it at the current minute and mark it Completed. Send no time with it.; default: false |
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 |
|---|---|---|---|
outcome |
yes | string | added placed it on today; logged added it and marked it Completed; refused changed nothing.; Values: added, logged, refused |
occurrence |
yes | object or null | The added Occurrence. Null when refused. |
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._:-]+$ |
refusal |
yes | object or null | Set when nothing changed because a rule refused the request. Null when the change was made. |
refusal.reason |
yes | string | Values: not_available, not_running, not_today, invalid_time, slot_taken, calendar_busy |
refusal.message |
yes | string | Plain-language reason to show the user. |
refusal.alternatives |
yes | array | Up to three free start times today, nearest the requested time first. Empty unless the time was taken.; maxItems: 3 |
refusal.alternatives[] |
yes | object | |
refusal.alternatives[].start_at |
yes | string | format: date-time; pattern: [Zz]$ |
refusal.alternatives[].start_time |
yes | string | Local start time in the Behavior’s timezone.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$ |
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": "add_opportunity_occurrence",
"arguments": {
"behavior_id": "00000002-1111-4111-8111-000000000002",
"start_time": "15:00",
"idempotency_key": "add-stretch-1500"
}
}
Example result
Synthetic success data from a contract fixture, shown as structuredContent. Input and output examples validate independently; they are not a recorded transaction.
{
"outcome": "added",
"occurrence": {
"id": "00000006-1111-4111-8111-000000000006",
"behavior_id": "00000002-1111-4111-8111-000000000002",
"behavior_title": "Stretch",
"category_name": null,
"local_date": "2026-10-18",
"timezone": "America/New_York",
"scheduled_for": "2026-10-18T19:00:00Z",
"effective_start_at": "2026-10-18T19:00:00Z",
"move": null,
"schedule": {
"kind": "exact",
"preset": null,
"start_time": "15:00",
"end_time": null,
"label": "3:00 PM"
},
"status": "unresolved",
"status_label": "Unresolved",
"needs_decision": false,
"origin": "opportunity",
"added_by": "mcp",
"completed_at": null,
"status_marked_at": null,
"note": null,
"updated_at": "2026-10-18T18:40:00Z",
"revision": "2026-10-18T18:40:00Z"
},
"refusal": null
}
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.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.