list_categories
Lists the user’s Behavior categories in display order. Use it to choose a category id when creating or editing a Behavior.
Permission and annotations
Required scope: cadence.read. Contract 1.7.0; available since 1.0.0.
title: “List categories”readOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false
Reads account data and changes nothing, so readOnlyHint is true. Claude runs read-only tools without per-call confirmation, and OpenAI asks for readOnlyHint on every read. openWorldHint is false because the tool reaches only the user’s own Cadence account.
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 |
|---|---|---|---|
updated_since |
no | string | Return only records changed at or after this instant. Use it for incremental reads.; format: date-time |
page_size |
no | integer | Items per page.; minimum: 1; maximum: 100; default: 50 |
cursor |
no | string | Opaque next_cursor from the previous page.; minLength: 1; maxLength: 512; 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 |
|---|---|---|---|
categories |
yes | array | |
categories[] |
yes | object | |
categories[].id |
yes | string | format: uuid |
categories[].name |
yes | string | |
categories[].description |
yes | string or null | |
categories[].sort_order |
yes | integer | |
categories[].created_at |
yes | string | format: date-time; pattern: [Zz]$ |
categories[].updated_at |
yes | string | format: date-time; pattern: [Zz]$ |
next_cursor |
yes | string or null | Cursor for the next page, or null when this is the last page.; minLength: 1; maxLength: 512; pattern: ^[A-Za-z0-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.
{
"name": "list_categories",
"arguments": {}
}
Example result
Synthetic success data from a contract fixture, shown as structuredContent. Input and output examples validate independently; they are not a recorded transaction.
{
"categories": [
{
"id": "00000003-1111-4111-8111-000000000003",
"name": "Fitness",
"description": null,
"sort_order": 2,
"created_at": "2026-09-01T12:00:00Z",
"updated_at": "2026-09-01T12:00:00Z"
}
],
"next_cursor": null
}
Errors
invalid_input: The input does not match the tool’s schema or rules.field_errorsnames 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 afterretry_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 sameidempotency_key.
Output size limits can also return limit_exceeded. See error handling, limits, and safe retries.