Contract 1.7.0 · Local previewRead Markdown

update_behavior

Edits a Behavior’s title, description, place, category, schedules, reminders, length, end, opportunity flag or sub-behavior link. Only the fields sent change; schedules replaces the whole list and may be empty only for an opportunity Behavior. parent_behavior_id groups it under a parent, or null makes it top-level; sub_behavior_sort_order moves it among its siblings. An opportunity Behavior is never part of a routine. A parent’s schedule change also reaches the sub-behaviors that follow it. Past and resolved Occurrences are kept. Read get_behavior first for the revision.

Permission and annotations

Required scope: cadence.behaviors.write. Contract 1.7.0; available since 1.0.0.

  • title: “Update Behavior”
  • readOnlyHint: false
  • destructiveHint: true
  • idempotentHint: true
  • openWorldHint: false

Overwrites Behavior fields, and a schedule change can remove future Unresolved Occurrences, so destructiveHint is true under both Claude’s and OpenAI’s guidance. Repeating the same arguments leaves the same definition, 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
behavior_id yes string Behavior id.; format: uuid
expected_revision yes string Revision from get_behavior. If the Behavior changed since, the call fails with conflict and changes nothing.; minLength: 1; maxLength: 128; pattern: ^[A-Za-z0-9._:-]+$
title no string Behavior name.; minLength: 1; maxLength: 160; pattern: ^(?=.*\S)[^\u0000-\u001f\u007f]*$
description no string or null New description, or null to clear it.; maxLength: 1000; pattern: ^[^\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]*$
location_text no string or null New location, or null to clear it.; maxLength: 500; pattern: ^[^\u0000-\u001f\u007f]*$
category_id no string or null New category id, or null for no category.; format: uuid
schedules no array Complete list of schedules. Each schedule has one recurrence rule and one or more time entries. It may be empty only for a Behavior available as an opportunity.; maxItems: 6
schedules[] yes object
schedules[].id no string Existing schedule id. Omit for a new schedule.; format: uuid
schedules[].recurrence yes one of several shapes Structured recurrence rule. Natural-language rules and cron syntax are not accepted.
schedules[].recurrence.frequency yes string Value: daily
schedules[].recurrence.interval yes integer Repeat every N days. 1 means every day.; minimum: 1; maximum: 999
schedules[].recurrence.frequency yes string Value: interval_days
schedules[].recurrence.interval_days yes integer Repeat every N days counted from the start date.; minimum: 1; maximum: 999
schedules[].recurrence.frequency yes string Value: weekly
schedules[].recurrence.interval yes integer Repeat every N weeks. 1 means every week.; minimum: 1; maximum: 999
schedules[].recurrence.days_of_week yes array minItems: 1; maxItems: 7; uniqueItems: true
schedules[].recurrence.days_of_week[] yes string Values: monday, tuesday, wednesday, thursday, friday, saturday, sunday
schedules[].recurrence.frequency yes string Value: monthly
schedules[].recurrence.interval yes integer Repeat every N months.; minimum: 1; maximum: 999
schedules[].recurrence.day_of_month yes integer Day of the month. In months without this day, the last day of the month is used.; minimum: 1; maximum: 31
schedules[].time_entries yes array minItems: 1; maxItems: 8
schedules[].time_entries[] yes one of several shapes
schedules[].time_entries[].id no string Existing time entry id. Omit for a new entry.; format: uuid
schedules[].time_entries[].kind yes string Value: exact
schedules[].time_entries[].start_time yes string Exact time of day.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
schedules[].time_entries[].id no string Existing time entry id. Omit for a new entry.; format: uuid
schedules[].time_entries[].kind yes string Value: range
schedules[].time_entries[].preset yes string 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
schedules[].time_entries[].id no string Existing time entry id. Omit for a new entry.; format: uuid
schedules[].time_entries[].kind yes string Value: range
schedules[].time_entries[].start_time yes string Range start.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
schedules[].time_entries[].end_time yes string Range end. A range may end after midnight, for example 22:00-01:00.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
is_opportunity no boolean Available as an opportunity, or not. Turning it off needs at least one schedule (contract 1.6.0).
reminders no object Per-Behavior reminder settings. Omitted fields keep their current or default value.
reminders.browser_enabled no boolean Browser reminders. On by default.
reminders.email_enabled no boolean Email reminders. Off by default.
reminders.offset_minutes no integer Minutes before the scheduled time: 0, 15, 60, 1440 (1 day), or 4320 (3 days). Default 0.; Values: 0, 15, 60, 1440, 4320
default_duration_minutes no integer or null New duration in minutes, or null to clear it.; minimum: 1; maximum: 1440
end_on no string or null New last local day, or null to clear the end. It must be later than now. To stop right away, use end_behavior.; format: date
end_time no string or null New local stop time on end_on, or null to stop at the end of that day.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
end_date no string or null Deprecated: send end_on. The first day without the Behavior, or null to clear the end.; format: date
parent_behavior_id no string or null New parent Behavior, or null to make this a top-level Behavior. The parent must be active and top-level, and a Behavior with sub-behaviors can’t get a parent (contract 1.7.0).; format: uuid
inherit_parent_schedule no boolean For a sub-behavior: true follows the parent’s schedule and takes no schedules; false keeps its current schedules unless schedules is sent. A Behavior newly given a parent follows it unless this is false.
sub_behavior_sort_order no integer For a sub-behavior: new position among its siblings, 0 first. The other sub-behaviors shift to make room.; minimum: 0; maximum: 9999
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: title, description, location_text, category_id, schedules, reminders, default_duration_minutes, end_on, end_time, end_date, is_opportunity, parent_behavior_id, inherit_parent_schedule, sub_behavior_sort_order.

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
behavior yes object A Behavior: a recurring thing the user tracks (a habit, routine, or recurring task).
behavior.id yes string format: uuid
behavior.title yes string
behavior.description yes string or null
behavior.location_text yes string or null
behavior.category yes object or null
behavior.category.id yes string format: uuid
behavior.category.name yes string
behavior.state yes string Archived Behaviors keep their history but schedule no new Occurrences.; Values: active, archived
behavior.archived_at yes string or null format: date-time; pattern: [Zz]$
behavior.auto_archived_at yes string or null Set on Behaviors that an end date archived automatically before Cadence stopped archiving on an end. New ends never set it.; format: date-time; pattern: [Zz]$
behavior.run_state yes string running schedules Occurrences; ended has passed its end and paused is inside a pause, both still active and shown under Not running; archived is archived.; Values: running, ended, paused, archived
behavior.is_opportunity yes boolean True when the Behavior is available as an opportunity: the person can add it to today when there is room, with or without a schedule (contract 1.6.0).
behavior.end_on yes string or null Last local day the Behavior runs. Null when it has no end.; format: date
behavior.end_time yes string or null Local time on end_on when it stops. Null means it stops at the end of that day.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
behavior.pause yes object or null The current or upcoming pause. Null when none is set or the pause is over.
behavior.pause.from_on yes string First paused local day.; format: date
behavior.pause.from_time yes string or null Local time on from_on when the pause starts. Null means the start of that day.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
behavior.pause.back_on yes string Local day the Behavior runs again by itself, from the start of the day.; format: date
behavior.end_date yes string or null Deprecated: read end_on. The day after end_on, kept for one minor version.; format: date
behavior.default_duration_minutes yes integer or null minimum: 1
behavior.timezone yes string IANA timezone name.; minLength: 1; maxLength: 64; pattern: ^[A-Za-z0-9_+\-/]+$
behavior.schedules yes array
behavior.schedules[] yes object
behavior.schedules[].id yes string format: uuid
behavior.schedules[].recurrence yes one of several shapes Structured recurrence rule. Natural-language rules and cron syntax are not accepted.
behavior.schedules[].recurrence.frequency yes string Value: daily
behavior.schedules[].recurrence.interval yes integer Repeat every N days. 1 means every day.; minimum: 1
behavior.schedules[].recurrence.frequency yes string Value: interval_days
behavior.schedules[].recurrence.interval_days yes integer Repeat every N days counted from the start date.; minimum: 1
behavior.schedules[].recurrence.frequency yes string Value: weekly
behavior.schedules[].recurrence.interval yes integer Repeat every N weeks. 1 means every week.; minimum: 1
behavior.schedules[].recurrence.days_of_week yes array minItems: 1; maxItems: 7; uniqueItems: true
behavior.schedules[].recurrence.days_of_week[] yes string Values: monday, tuesday, wednesday, thursday, friday, saturday, sunday
behavior.schedules[].recurrence.frequency yes string Value: monthly
behavior.schedules[].recurrence.interval yes integer Repeat every N months.; minimum: 1
behavior.schedules[].recurrence.day_of_month yes integer Day of the month. In months without this day, the last day of the month is used.; minimum: 1; maximum: 31
behavior.schedules[].recurrence_summary yes string Plain-language recurrence, for example Weekly on Monday and Thursday.
behavior.schedules[].time_entries yes array
behavior.schedules[].time_entries[] yes object
behavior.schedules[].time_entries[].id yes string format: uuid
behavior.schedules[].time_entries[].kind yes string Values: exact, range
behavior.schedules[].time_entries[].preset yes string or null Values: morning, afternoon, evening, night, null
behavior.schedules[].time_entries[].start_time yes string Local wall-clock time, 24-hour HH:MM.; pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
behavior.schedules[].time_entries[].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]$
behavior.schedules[].time_entries[].label yes string Display label, for example 7:30 AM or Morning.
behavior.schedules[].time_summary yes string
behavior.schedule_summary yes string
behavior.reminders yes object
behavior.reminders.browser_enabled yes boolean
behavior.reminders.email_enabled yes boolean
behavior.reminders.offset_minutes yes integer minimum: 0
behavior.reminders.summary yes string
behavior.archive_notes yes array
behavior.archive_notes[] yes object
behavior.archive_notes[].id yes string format: uuid
behavior.archive_notes[].archived_at yes string format: date-time; pattern: [Zz]$
behavior.archive_notes[].note yes string or null
behavior.archive_notes[].updated_at yes string format: date-time; pattern: [Zz]$
behavior.external_ref yes string or null This client’s external record id, when it set one at creation.
behavior.parent_behavior_id yes string or null Parent Behavior id when this is a sub-behavior. Null for a top-level Behavior (contract 1.7.0).; format: uuid
behavior.sub_behavior_sort_order yes integer Position among the parent’s sub-behaviors, 0 first. 0 for a top-level Behavior.; minimum: 0; maximum: 9999
behavior.inherit_parent_schedule yes boolean True when this sub-behavior follows its parent’s schedule; its schedules then mirror the parent’s. Always false for a top-level Behavior.
behavior.sub_behaviors yes array This Behavior’s sub-behaviors in display order, archived ones included. Empty for a sub-behavior or a Behavior without any.
behavior.sub_behaviors[] yes object
behavior.sub_behaviors[].id yes string format: uuid
behavior.sub_behaviors[].title yes string
behavior.sub_behaviors[].sub_behavior_sort_order yes integer Position among the parent’s sub-behaviors, 0 first.; minimum: 0; maximum: 9999
behavior.sub_behaviors[].inherit_parent_schedule yes boolean True when the sub-behavior follows its parent’s schedule.
behavior.sub_behaviors[].active yes boolean False when the sub-behavior is archived.
behavior.sub_behaviors[].run_state yes string Values: running, ended, paused, archived
behavior.created_at yes string format: date-time; pattern: [Zz]$
behavior.updated_at yes string format: date-time; pattern: [Zz]$
behavior.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 sent values matched the stored ones.

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_behavior",
  "arguments": {
    "behavior_id": "00000001-1111-4111-8111-000000000001",
    "expected_revision": "b1.2026-10-18T13:00:00Z",
    "title": "Evening walk"
  }
}

Example result

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

{
  "behavior": {
    "id": "00000001-1111-4111-8111-000000000001",
    "title": "Morning walk",
    "description": "Twenty minutes outside.",
    "location_text": null,
    "category": {
      "id": "00000003-1111-4111-8111-000000000003",
      "name": "Fitness"
    },
    "state": "active",
    "archived_at": null,
    "auto_archived_at": null,
    "run_state": "running",
    "is_opportunity": false,
    "end_on": null,
    "end_time": null,
    "pause": null,
    "end_date": null,
    "default_duration_minutes": 20,
    "timezone": "America/New_York",
    "schedules": [
      {
        "id": "00000006-1111-4111-8111-000000000006",
        "recurrence": {
          "frequency": "weekly",
          "interval": 1,
          "days_of_week": [
            "monday",
            "thursday"
          ]
        },
        "recurrence_summary": "Weekly on Monday and Thursday",
        "time_entries": [
          {
            "id": "00000007-1111-4111-8111-000000000007",
            "kind": "exact",
            "preset": null,
            "start_time": "07:30",
            "end_time": null,
            "label": "7:30 AM"
          },
          {
            "id": "00000008-1111-4111-8111-000000000008",
            "kind": "range",
            "preset": "evening",
            "start_time": "18:00",
            "end_time": "00:00",
            "label": "Evening"
          }
        ],
        "time_summary": "7:30 AM, Evening"
      }
    ],
    "schedule_summary": "Weekly on Monday and Thursday at 7:30 AM and Evening",
    "reminders": {
      "browser_enabled": true,
      "email_enabled": false,
      "offset_minutes": 0,
      "summary": "Browser reminder at the scheduled time"
    },
    "archive_notes": [],
    "external_ref": null,
    "parent_behavior_id": null,
    "sub_behavior_sort_order": 0,
    "inherit_parent_schedule": false,
    "sub_behaviors": [],
    "created_at": "2026-09-01T12:00:00Z",
    "updated_at": "2026-10-18T13:00:00Z",
    "revision": "b1.2026-10-18T13:00:00Z"
  },
  "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.