read_context #

View this page as Markdown

On this page

Generated automatically from the published 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).

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 #

{
  "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 #

{
  "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
Required fields: []
Additional properties: false
/properties/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.

Type: integer
Minimum: 0
Maximum: 9007199254740991
/properties/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.

Type: string
Pattern: ^[a-f0-9]{64}$
/properties/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.

Type: integer
Minimum: 1
/properties/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.

Type: string
Minimum length: 1
Maximum length: 160

response #

JSON pointer Description and constraints
"" (root) Type: object
Required fields: ["contract_version","stamp","offset","total","next_offset"]
Additional properties: false
/properties/contract_version Required value: 1
/properties/stamp Type: string
Pattern: ^[a-f0-9]{64}$
/properties/offset Type: integer
Minimum: 0
Maximum: 9007199254740991
/properties/total Type: integer
Minimum: 0
Maximum: 9007199254740991
/properties/next_offset Type: ["integer","null"]
Minimum: 0
Maximum: 9007199254740991
/properties/id Type: string
/properties/mime_type Type: string
/properties/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.

Type: string
/properties/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.

Type: string
/properties/text Type: string
/properties/entries Type: array
/properties/entries/items Type: object
Required fields: ["id","summary","tool","authentication"]
Additional properties: false
/properties/entries/items/properties/id Type: string
/properties/entries/items/properties/summary Type: string
/properties/entries/items/properties/tool Allowed values: ["read_context","read_documentation"]
/properties/entries/items/properties/authentication Allowed values: ["optional","required"]
/properties/entries/items/properties/tree Allowed values: ["cloud","tzteam","tzdocs","tzmesh","tztrack"]
/properties/entries/items/properties/part Allowed values: ["index","full"]

Complete payload contract #

{
  "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 #