Contract 1.7.0 · Local previewRead Markdown

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: false
  • destructiveHint: false
  • idempotentHint: false
  • openWorldHint: 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_errors names 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 after retry_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 same idempotency_key.
  • insufficient_scope: The connection does not include the permission this tool needs. required_scopes lists it.
  • not_found: No record with that id exists for this account.
  • idempotency_key_reused: The idempotency_key was 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.