---
title: "read_context"
description: "Generated reference for the management action read_context: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/read-context
order: 72
visibility: public
redirects_from: ["/reference/actions/list-context"]
---

# read\_context

Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources).

A script calls this action over HTTPS at `POST https://turnzero.ai/api/v1/read_context`, with a bearer credential and the action's payload as the JSON body. It also accepts `GET`. An MCP connection lists this action as the tool `read_context`.

OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts ([Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/)).

**Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

## Contract description

List the readable context IDs, or read one entry by `id`\. With no `id`, the catalog includes contracts, guides, tzCloud's own skills, one skills entry per other product, and documentation trees\. With `id`, the answer is a text chunk, 8,000 characters by default and at most 16,000\. Read `manifest_schema:<member>` for one manifest member, or `manifest_schema:services:<kind>` for one service kind\. A product's skills entry gives the `skill:<prefixed name>` IDs, which need not appear in the catalog\.

On either form, continue with the returned `next_offset` as `offset` and its `stamp` until `next_offset` is null\. If the content changes, restart at offset zero without a stamp\.

A host may cut batched results, so read long texts one chunk at a time at the default limit\.

## More about this action

Pass `stamp` with any nonzero offset: copy the `stamp` member of the previous answer of this same read, unchanged\. It is 64 lowercase hexadecimal characters, the SHA\-256 of the text\. Send it beside that answer's `next_offset`; a first read sends no stamp\. Where the text has changed, the call is refused `context_changed`: restart at offset 0 without a stamp\. A stamp from another read is refused the same way\. A product's own skill reads by `skill:<prefixed name>`, a name `skills:<product>` gives and no catalog page lists\.

List readable context IDs: contracts, guides, tzCloud's own skills, a skills entry per other product, and documentation trees\. A skill's entry describes it in one line; `read_context` returns its steps\. Results are paged: pass the returned `next_offset` as `offset`, with the returned `stamp`, until `next_offset` is null\.

## Access and action metadata

```json
{
  "name": "read_context",
  "resource": "platform_context",
  "tier": "observe",
  "surface": "account",
  "addresses": [
    "tzcloud",
    "tztools"
  ],
  "admits": [
    "device_sign_in"
  ],
  "access": "anonymous",
  "summary": "Read a catalog content ID. Follow next_offset with its stamp to read the complete contracts, guide or live skill text. With no `id` it returns the catalog: List the platform context catalog, including contracts, guides, tzCloud's own skills and available documentation trees. The catalog lists no skills from other products. Start here to discover what to read.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "read_context",
  "title": "Read guide or reference",
  "tier": "observe",
  "scenario": "CHI-L0-05",
  "summary": "List the readable context IDs, or read one entry by `id`. With no `id`, the catalog includes contracts, guides, tzCloud's own skills, one skills entry per other product, and documentation trees. With `id`, the answer is a text chunk, 8,000 characters by default and at most 16,000. Read `manifest_schema:<member>` for one manifest member, or `manifest_schema:services:<kind>` for one service kind. A product's skills entry gives the `skill:<prefixed name>` IDs, which need not appear in the catalog.\n\nOn either form, continue with the returned `next_offset` as `offset` and its `stamp` until `next_offset` is null. If the content changes, restart at offset zero without a stamp.\n\nA host may cut batched results, so read long texts one chunk at a time at the default limit.",
  "owners": [
    "CTX-07"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \[\]<br>Additional properties: false |
| /<wbr>properties/<wbr>offset | Zero\-based Unicode code\-point offset in the complete text; defaults to 0\. Use the previous response's next\_offset for continuation\. A nonzero offset requires its stamp\.<br><br>Type: integer<br>Minimum: 0<br>Maximum: 9007199254740991 |
| /<wbr>properties/<wbr>stamp | The `stamp` member of the previous answer of this same read, copied unchanged: 64 lower\-case hexadecimal characters\. Required with a nonzero offset; send none on your first read\. A changed text is refused `context_changed`: restart at offset 0 without a stamp\. The stamp does not grant access\.<br><br>Type: string<br>Pattern: ^\[a\-f0\-9\]\{64\}$ |
| /<wbr>properties/<wbr>limit | Maximum Unicode code points returned in this chunk: 1 through 16000, default 8000\. A larger value reads 16000, and `note` says so\. Offsets and limits count code points, not UTF\-8 bytes or UTF\-16 code units\. Catalog reads without `id` must omit `limit`\.<br><br>Type: integer<br>Minimum: 1 |
| /<wbr>properties/<wbr>id | A content ID the catalog lists whose tool is read\_context\. Leave it out to read the catalog itself\. IDs select listed platform content and are never arbitrary paths or URLs\.<br><br>Type: string<br>Minimum length: 1<br>Maximum length: 160 |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","stamp","offset","total","next\_offset"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>stamp | Type: string<br>Pattern: ^\[a\-f0\-9\]\{64\}$ |
| /<wbr>properties/<wbr>offset | Type: integer<br>Minimum: 0<br>Maximum: 9007199254740991 |
| /<wbr>properties/<wbr>total | Type: integer<br>Minimum: 0<br>Maximum: 9007199254740991 |
| /<wbr>properties/<wbr>next\_offset | Type: \["integer","null"\]<br>Minimum: 0<br>Maximum: 9007199254740991 |
| /<wbr>properties/<wbr>id | Type: string |
| /<wbr>properties/<wbr>mime\_type | Type: string |
| /<wbr>properties/<wbr>note | Present where the identifier asked matched no member of an entry read by member and the read returned the one member it most likely meant: a sentence giving the identifier asked and the member returned, whose id the answer's id carries\. Where the identifier's last part is a property inside that member, a second sentence says so\. Present too where `limit` was past the most one read returns: a sentence saying this read used that most\. Absent on every other read\.<br><br>Type: string |
| /<wbr>properties/<wbr>continuation | Present where this answer holds part of the text\. Gives the characters read and total\. For more text, gives the next call with next\_offset as offset and the stamp value\. Otherwise says this is the last chunk\. Absent where one answer holds the whole text\. Join the chunks' text in order for the whole text\.<br><br>Type: string |
| /<wbr>properties/<wbr>text | Type: string |
| /<wbr>properties/<wbr>entries | Type: array |
| /<wbr>properties/<wbr>entries/<wbr>items | Type: object<br>Required fields: \["id","summary","tool","authentication"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>entries/<wbr>items/<wbr>properties/<wbr>id | Type: string |
| /<wbr>properties/<wbr>entries/<wbr>items/<wbr>properties/<wbr>summary | Type: string |
| /<wbr>properties/<wbr>entries/<wbr>items/<wbr>properties/<wbr>tool | Allowed values: \["read\_context","read\_documentation"\] |
| /<wbr>properties/<wbr>entries/<wbr>items/<wbr>properties/<wbr>authentication | Allowed values: \["optional","required"\] |
| /<wbr>properties/<wbr>entries/<wbr>items/<wbr>properties/<wbr>tree | Allowed values: \["cloud","tzteam","tzdocs","tzmesh","tztrack"\] |
| /<wbr>properties/<wbr>entries/<wbr>items/<wbr>properties/<wbr>part | Allowed values: \["index","full"\] |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "properties": {
      "offset": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "description": "Zero-based Unicode code-point offset in the complete text; defaults to 0. Use the previous response's next_offset for continuation. A nonzero offset requires its stamp."
      },
      "stamp": {
        "type": "string",
        "pattern": "^[a-f0-9]{64}$",
        "description": "The `stamp` member of the previous answer of this same read, copied unchanged: 64 lower-case hexadecimal characters. Required with a nonzero offset; send none on your first read. A changed text is refused `context_changed`: restart at offset 0 without a stamp. The stamp does not grant access."
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "description": "Maximum Unicode code points returned in this chunk: 1 through 16000, default 8000. A larger value reads 16000, and `note` says so. Offsets and limits count code points, not UTF-8 bytes or UTF-16 code units. Catalog reads without `id` must omit `limit`."
      },
      "id": {
        "type": "string",
        "minLength": 1,
        "maxLength": 160,
        "description": "A content ID the catalog lists whose tool is read_context. Leave it out to read the catalog itself. IDs select listed platform content and are never arbitrary paths or URLs."
      }
    },
    "required": [],
    "additionalProperties": false
  },
  "response": {
    "type": "object",
    "properties": {
      "contract_version": {
        "const": 1
      },
      "stamp": {
        "type": "string",
        "pattern": "^[a-f0-9]{64}$"
      },
      "offset": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991
      },
      "total": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991
      },
      "next_offset": {
        "type": [
          "integer",
          "null"
        ],
        "minimum": 0,
        "maximum": 9007199254740991
      },
      "id": {
        "type": "string"
      },
      "mime_type": {
        "type": "string"
      },
      "note": {
        "type": "string",
        "description": "Present where the identifier asked matched no member of an entry read by member and the read returned the one member it most likely meant: a sentence giving the identifier asked and the member returned, whose id the answer's id carries. Where the identifier's last part is a property inside that member, a second sentence says so. Present too where `limit` was past the most one read returns: a sentence saying this read used that most. Absent on every other read."
      },
      "continuation": {
        "type": "string",
        "description": "Present where this answer holds part of the text. Gives the characters read and total. For more text, gives the next call with next_offset as offset and the stamp value. Otherwise says this is the last chunk. Absent where one answer holds the whole text. Join the chunks' text in order for the whole text."
      },
      "text": {
        "type": "string"
      },
      "entries": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "summary": {
              "type": "string"
            },
            "tool": {
              "enum": [
                "read_context",
                "read_documentation"
              ]
            },
            "authentication": {
              "enum": [
                "optional",
                "required"
              ]
            },
            "tree": {
              "enum": [
                "cloud",
                "tzteam",
                "tzdocs",
                "tzmesh",
                "tztrack"
              ]
            },
            "part": {
              "enum": [
                "index",
                "full"
              ]
            }
          },
          "required": [
            "id",
            "summary",
            "tool",
            "authentication"
          ],
          "additionalProperties": false
        }
      }
    },
    "required": [
      "contract_version",
      "stamp",
      "offset",
      "total",
      "next_offset"
    ],
    "additionalProperties": false
  }
}
```

## Shared contracts

- [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)
