Contract 1.7.0 · Local previewRead Markdown

set_parent_occurrence_status

Marks every sub-behavior Occurrence in one parent Behavior slot Completed or Not Completed in one change, such as a whole skin routine one morning. Name the slot with local_date, plus slot_key from get_timeline parent_groups when the parent has several times that day, or list occurrence_ids. Occurrences that already have the status do not change. To mark one step, use set_occurrence_status.

Permission and annotations

Required scope: cadence.occurrences.write. Contract 1.7.0; available since 1.7.0.

  • title: “Set parent Behavior slot status”
  • readOnlyHint: false
  • destructiveHint: true
  • idempotentHint: true
  • openWorldHint: false

Changes stored statuses of several Occurrences at once, so readOnlyHint is false and destructiveHint is true under Claude’s review criteria, which ask for it on tools that modify data; each status can be set back, so the hint is conservative for ChatGPT. The same arguments always leave the same statuses, so idempotentHint is true. 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
parent_behavior_id yes string Behavior id.; format: uuid
status yes string New status for each sub-behavior Occurrence in the slot.; Values: completed, not_completed
local_date no string Day of the slot, in the account timezone.; format: date
slot_key no string slot_key of one parent group from get_timeline. Needs local_date.; format: date-time
occurrence_ids no array The sub-behavior Occurrences to mark. All must belong to sub-behaviors of this parent on one day.; minItems: 1; maxItems: 50; uniqueItems: true
occurrence_ids[] yes string format: uuid
expected_statuses no array Statuses the client last read. If any stored status differs, the call fails with conflict and changes nothing.; minItems: 1; maxItems: 50
expected_statuses[] yes object
expected_statuses[].occurrence_id yes string Occurrence id.; format: uuid
expected_statuses[].status yes string Status the client last read.; Values: unresolved, completed, not_completed
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._:-]+$

Provide at least one of: local_date, occurrence_ids.

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
parent_behavior_id yes string format: uuid
status yes string New status for each sub-behavior Occurrence in the slot.; Values: completed, not_completed
occurrences yes array The marked Occurrences after the change, in sub-behavior order.; maxItems: 50
occurrences[] yes object An Occurrence: one scheduled instance of a Behavior on one local date.
occurrences[].id yes string format: uuid
occurrences[].behavior_id yes string format: uuid
occurrences[].behavior_title yes string
occurrences[].category_name yes string or null
occurrences[].local_date yes string Calendar date (YYYY-MM-DD) in the account timezone.; format: date
occurrences[].timezone yes string IANA timezone name.; minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_+\-/]+$
occurrences[].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]$
occurrences[].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]$
occurrences[].move yes object or null Set while a per-day move places the Occurrence away from its planned time. Null otherwise.
occurrences[].move.planned_start_at yes string The planned start. It does not change when the item moves.; format: date-time; pattern: [Zz]$
occurrences[].move.start_at yes string The moved start.; format: date-time; pattern: [Zz]$
occurrences[].move.end_at yes string The moved end. A move keeps the item’s length.; format: date-time; pattern: [Zz]$
occurrences[].schedule yes object
occurrences[].schedule.kind yes string Values: exact, range
occurrences[].schedule.preset yes string or null Values: morning, afternoon, evening, night, null
occurrences[].schedule.start_time yes string Local wall-clock time, 24-hour HH:MM.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
occurrences[].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]$
occurrences[].schedule.label yes string
occurrences[].status yes string Stored status.; Values: unresolved, completed, not_completed
occurrences[].status_label yes string Values: Unresolved, Completed, Not Completed
occurrences[].needs_decision yes boolean Derived: true when the status is unresolved and local_date is before today. Never stored.
occurrences[].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
occurrences[].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
occurrences[].completed_at yes string or null format: date-time; pattern: [Zz]$
occurrences[].status_marked_at yes string or null format: date-time; pattern: [Zz]$
occurrences[].note yes string or null
occurrences[].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
occurrences[].parent_title no string or null Parent Behavior title when the Occurrence belongs to a sub-behavior, otherwise null.
occurrences[].updated_at yes string format: date-time; pattern: [Zz]$
occurrences[].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_occurrence_ids yes array Occurrences whose status changed. Empty when all already had the status.
changed_occurrence_ids[] yes string format: uuid
parent_groups yes array The derived rollup of each slot the marked Occurrences belong to.
parent_groups[] yes object A parent Behavior’s slot: its sub-behaviors’ Occurrences at one time on one day, with a derived rollup.
parent_groups[].parent_behavior_id yes string format: uuid
parent_groups[].title yes string Parent Behavior title.
parent_groups[].local_date yes string Calendar date (YYYY-MM-DD) in the account timezone.; format: date
parent_groups[].slot_key yes string Start of the slot: the earliest effective start among its Occurrences. Send it to set_parent_occurrence_status.; format: date-time; pattern: [Zz]$
parent_groups[].scheduled_time_label yes string Display time, for example 7:30 AM or Morning.
parent_groups[].derived_status yes string Derived and never stored: the shared status when every Occurrence has it, otherwise partial.; Values: unresolved, completed, not_completed, partial
parent_groups[].progress_label yes string Completed over scheduled, for example 2/3.
parent_groups[].completed_count yes integer minimum: 0
parent_groups[].not_completed_count yes integer minimum: 0
parent_groups[].unresolved_count yes integer minimum: 0
parent_groups[].total_count yes integer minimum: 1
parent_groups[].needs_decision yes boolean Derived: true when an Occurrence in the slot is Unresolved and before today.
parent_groups[].occurrence_ids yes array The sub-behavior Occurrences in this slot, in sub-behavior order.; minItems: 1
parent_groups[].occurrence_ids[] yes string format: uuid
changed yes boolean False when every Occurrence already had this status.

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": "set_parent_occurrence_status",
  "arguments": {
    "parent_behavior_id": "00000009-1111-4111-8111-000000000009",
    "local_date": "2026-10-18",
    "status": "completed",
    "idempotency_key": "routine-mark-0001"
  }
}

Example result

Synthetic success data from a contract fixture, shown as structuredContent. Input and output examples validate independently; they are not a recorded transaction.

{
  "parent_behavior_id": "00000009-1111-4111-8111-000000000009",
  "status": "completed",
  "occurrences": [
    {
      "id": "0000000c-1111-4111-8111-00000000000c",
      "behavior_id": "0000000a-1111-4111-8111-00000000000a",
      "behavior_title": "Cleanser",
      "category_name": "Fitness",
      "local_date": "2026-10-18",
      "timezone": "America/New_York",
      "scheduled_for": "2026-10-18T11:00:00Z",
      "effective_start_at": "2026-10-18T11:00:00Z",
      "move": null,
      "schedule": {
        "kind": "exact",
        "preset": null,
        "start_time": "07:00",
        "end_time": null,
        "label": "7:00 AM"
      },
      "status": "completed",
      "origin": "scheduled",
      "added_by": null,
      "status_label": "Completed",
      "needs_decision": false,
      "completed_at": "2026-10-18T11:05:00Z",
      "status_marked_at": "2026-10-18T11:05:00Z",
      "note": "Felt good.\nCold out.",
      "updated_at": "2026-10-18T13:00:00Z",
      "revision": "o1.3",
      "parent_behavior_id": "00000009-1111-4111-8111-000000000009",
      "parent_title": "Skin routine"
    },
    {
      "id": "0000000d-1111-4111-8111-00000000000d",
      "behavior_id": "0000000b-1111-4111-8111-00000000000b",
      "behavior_title": "Retinol",
      "category_name": "Fitness",
      "local_date": "2026-10-18",
      "timezone": "America/New_York",
      "scheduled_for": "2026-10-18T11:00:00Z",
      "effective_start_at": "2026-10-18T11:00:00Z",
      "move": null,
      "schedule": {
        "kind": "exact",
        "preset": null,
        "start_time": "07:00",
        "end_time": null,
        "label": "7:00 AM"
      },
      "status": "completed",
      "origin": "scheduled",
      "added_by": null,
      "status_label": "Completed",
      "needs_decision": false,
      "completed_at": "2026-10-18T11:05:00Z",
      "status_marked_at": "2026-10-18T11:05:00Z",
      "note": "Felt good.\nCold out.",
      "updated_at": "2026-10-18T13:00:00Z",
      "revision": "o1.3",
      "parent_behavior_id": "00000009-1111-4111-8111-000000000009",
      "parent_title": "Skin routine"
    }
  ],
  "changed_occurrence_ids": [
    "0000000d-1111-4111-8111-00000000000d"
  ],
  "parent_groups": [
    {
      "parent_behavior_id": "00000009-1111-4111-8111-000000000009",
      "title": "Skin routine",
      "local_date": "2026-10-18",
      "slot_key": "2026-10-18T11:00:00Z",
      "scheduled_time_label": "7:00 AM",
      "derived_status": "completed",
      "progress_label": "2/2",
      "completed_count": 2,
      "not_completed_count": 0,
      "unresolved_count": 0,
      "total_count": 2,
      "needs_decision": false,
      "occurrence_ids": [
        "0000000c-1111-4111-8111-00000000000c",
        "0000000d-1111-4111-8111-00000000000d"
      ]
    }
  ],
  "changed": true
}

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.
  • conflict: The record changed since it was read: expected_status or expected_revision is stale. Nothing changed.
  • idempotency_key_reused: The idempotency_key was already used with a different input. Use a new key for a new request.
  • invalid_state: The record’s current state does not allow this change.

Output size limits can also return limit_exceeded. See error handling, limits, and safe retries.