Contract 1.7.0 · Local previewRead Markdown

fetch

Returns the full text of one search result: a Behavior’s definition, an Occurrence and its note, or a day note. Use it after search to read a result. A day note is the user’s one note about a whole calendar date (for example “Travel day” or “Sick”). It is not an Occurrence note, has no status, and never changes Completed, Not Completed, Unresolved, Needs decision, adherence, or reminders.

Permission and annotations

Required scope: cadence.read. Contract 1.7.0; available since 1.0.0.

  • title: “Fetch Cadence record”
  • 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
id yes string Result id from search: behavior:<uuid>, occurrence:<uuid>, or day_note:<uuid>.; maxLength: 64; pattern: ^(behavior|occurrence|day_note):[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

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
id yes string Result id from search: behavior:<uuid>, occurrence:<uuid>, or day_note:<uuid>.; maxLength: 64; pattern: ^(behavior|occurrence|day_note):[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
title yes string
text yes string Plain-text rendering of the record. User-entered text is quoted as data.
url yes string Link to the record in the Cadence web app.; format: uri; maxLength: 2048; pattern: ^https://
metadata yes object
metadata.kind yes string Values: behavior, occurrence, day_note
metadata.behavior_id no string Present for Behavior and Occurrence results. Absent for day notes.; format: uuid
metadata.local_date no string Calendar date (YYYY-MM-DD) in the account timezone.; format: date
metadata.status no string Values: unresolved, completed, not_completed

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": "fetch",
  "arguments": {
    "id": "behavior:00000001-1111-4111-8111-000000000001"
  }
}

Example result

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

{
  "id": "occurrence:00000005-1111-4111-8111-000000000005",
  "title": "Morning walk on 2026-10-18",
  "text": "Status: Completed\nNote: \"Felt good.\"",
  "url": "https://app.cadence-me.com/timeline?date=2026-10-18&occurrence=00000005-1111-4111-8111-000000000005",
  "metadata": {
    "kind": "occurrence",
    "behavior_id": "00000001-1111-4111-8111-000000000001",
    "local_date": "2026-10-18",
    "status": "completed"
  }
}

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.
  • not_found: No record with that id exists for this account.

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