Contract 1.7.0 · Local previewRead Markdown

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: true
  • destructiveHint: false
  • idempotentHint: true
  • openWorldHint: 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_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.

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