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

# 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: <code>&#94;&#40;&#63;&#61;&#46;&#42;&#92;&#83;&#41;&#91;&#94;&#92;&#117;&#48;&#48;&#48;&#48;&#45;&#92;&#117;&#48;&#48;&#49;&#102;&#92;&#117;&#48;&#48;&#55;&#102;&#93;&#42;&#36;</code> |
| ` description ` | no | string or null | New description, or null to clear it.; maxLength: ` 1000 `; pattern: <code>&#94;&#91;&#94;&#92;&#117;&#48;&#48;&#48;&#48;&#45;&#92;&#117;&#48;&#48;&#48;&#56;&#92;&#117;&#48;&#48;&#48;&#98;&#92;&#117;&#48;&#48;&#48;&#99;&#92;&#117;&#48;&#48;&#48;&#101;&#45;&#92;&#117;&#48;&#48;&#49;&#102;&#92;&#117;&#48;&#48;&#55;&#102;&#93;&#42;&#36;</code> |
| ` location_text ` | no | string or null | New location, or null to clear it.; maxLength: ` 500 `; pattern: <code>&#94;&#91;&#94;&#92;&#117;&#48;&#48;&#48;&#48;&#45;&#92;&#117;&#48;&#48;&#49;&#102;&#92;&#117;&#48;&#48;&#55;&#102;&#93;&#42;&#36;</code> |
| ` 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: <code>&#94;&#91;&#65;&#45;&#90;&#97;&#45;&#122;&#48;&#45;&#57;&#95;&#43;&#92;&#45;&#47;&#93;&#43;&#36;</code> |
| ` 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.

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

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