Concepts
Behaviors and Occurrences
A Behavior is a recurring thing a person tracks. Its schedules define recurrence and exact times or time ranges. An Occurrence is one scheduled instance. Categories organize Behaviors. Archive and restore change future scheduling without deleting history.
Editable records carry opaque revision values. Use the actual record ID and revision returned by a read. A title is not a unique identifier.
Status and Needs decision
The stored values are unresolved, completed and not_completed. Their display labels are Unresolved, Completed and Not Completed. Only an explicit user decision changes the status. Silence never becomes failure.
Needs decision is a derived group: unresolved Occurrences with local_date before today. It is not a status you can write. A resolved status can be corrected later; note edits do not imply a status decision. Status history records decisions, not proof of actual start or finish times.
Dates and timezones
Use get_account_context for the account’s IANA timezone, today_local_date and freshness. Local dates use YYYY-MM-DD; they are calendar dates, not UTC instants. The day boundary is local midnight. The default timezone is America/New_York.
Inputs accept RFC 3339 timestamp offsets where an instant is required. Outputs use UTC timestamps ending in Z. Keep local_date and timezone when moving records between systems. Do not parse a local date as a JavaScript Date or assume every local day lasts 24 hours.
Recurrence
Supported rules are daily, every N days, weekly on selected weekdays, every N weeks on selected weekdays, and monthly on day N. When a month lacks the requested day, Cadence uses that month’s last day. Structured schedules define these rules; the server does not parse natural-language recurrence or cron syntax.
See create_behavior for each recurrence variant and time-entry shape. Reminder settings are returned with Behaviors. MCP does not send reminders itself or expose delivery logs.
Adherence
Adherence is Completed divided by Completed plus Not Completed. Multiply by 100 to display a percentage. Unresolved and Needs decision stay separate. If nothing is resolved, adherence is null.
For example, 3 Completed, 1 Not Completed and 2 Unresolved gives 0.75 adherence. Do not divide by all six Occurrences. Cadence exposes no streak metric and no clinical interpretation.