---
title: "add_opportunity_occurrence"
description: "Add opportunity to today: inputs, outputs, permissions, examples, and errors."
canonical_url: https://cadence-me.com/developers/tools/add_opportunity_occurrence
last_updated: 2026-10-18
status: stable
source: src/data/developer-reference.json
---

# 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: <code>&#94;&#91;&#65;&#45;&#90;&#97;&#45;&#122;&#48;&#45;&#57;&#95;&#43;&#92;&#45;&#47;&#93;&#43;&#36;</code> |
| ` 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.

```json
{
  "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.

```json
{
  "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](/developers/errors), [limits](/developers/limits), and [safe retries](/developers/idempotency).
