read_documentation
Generated automatically from the published contract sources.
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.
A script calls this action over HTTPS at POST https://turnzero.ai/api/v1/actions/read_documentation, with a bearer credential and the action's payload as the JSON body. It also accepts GET.
Contract description
Read the platform's documentation: a tree's index, one page by `page`, or the pages a search by `query` matches, where `page` and `query` exclude each other. Neither takes a `part` but the default `index`. It reads a documentation tree, named by `tree` or by the base path of the `page` route, that this connection's account holds — `cloud` for every account, `blueprint` and `tzdocs` for an account holding Turn Zero Blueprint access — using this signed-in connection. A `query` with no `tree` searches every tree the account holds, each line's route naming its tree.
It reads the tree's index by default — one line per page with its title, address, and description. Or it reads one page by its route with `page`, the pages a few words match with `query`, the index with every page's headings with `part` set to `outline`, or the whole text with `part` set to `full`. Results contain bounded text chunks. Continue with `next_offset` and the returned `stamp` until `next_offset` is null; if the content changes, restart at offset zero without a stamp. For a long page, start at a section by the offset its first chunk's `headings` lists, with that chunk's `stamp`, or list the pages holding a few of a passage's words with `query`, then continue the page by `next_offset`.
Access and action metadata
{
"name": "read_documentation",
"resource": "platform_context",
"tier": "observe",
"summary": "Read a documentation tree, named by `tree` or by the base path of the `page` route, that this connection's account holds — cloud for every account, blueprint and tzdocs for an account holding Turn Zero Blueprint access — through this signed-in connection: the tree's index by default, one page by its route with page, the pages a few words match with query, across every tree the account holds where no tree is named, the index with every page's headings with part outline, or the whole text with part full. Follow next_offset with its stamp for the complete text. For a long page, start at a section by the offset its first chunk's headings lists, with that chunk's stamp, then continue the page by next_offset.",
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": false,
"idempotentHint": true
}
}
MCP catalog entry
{
"name": "read_documentation",
"tier": "observe",
"scenario": "CHI-L0-05",
"summary": "Read the platform's documentation: a tree's index, one page by `page`, or the pages a search by `query` matches, where `page` and `query` exclude each other. Neither takes a `part` but the default `index`. It reads a documentation tree, named by `tree` or by the base path of the `page` route, that this connection's account holds — `cloud` for every account, `blueprint` and `tzdocs` for an account holding Turn Zero Blueprint access — using this signed-in connection. A `query` with no `tree` searches every tree the account holds, each line's route naming its tree.\n\nIt reads the tree's index by default — one line per page with its title, address, and description. Or it reads one page by its route with `page`, the pages a few words match with `query`, the index with every page's headings with `part` set to `outline`, or the whole text with `part` set to `full`. Results contain bounded text chunks. Continue with `next_offset` and the returned `stamp` until `next_offset` is null; if the content changes, restart at offset zero without a stamp. For a long page, start at a section by the offset its first chunk's `headings` lists, with that chunk's `stamp`, or list the pages holding a few of a passage's words with `query`, then continue the page by `next_offset`.",
"owners": [
"CTX-07",
"ACB-L0-82",
"PLD-L0-69",
"CTX-05"
]
}
request
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: [] Additional properties: false |
| / |
Zero-based Unicode code-point offset in the complete text; defaults to 0. Use the previous response's next_offset for continuation. An offset inside a line or a code block is read from the nearest place before it where a chunk can begin, which the answer's offset names. A nonzero offset requires its stamp. Type: integer Minimum: 0 Maximum: 9007199254740991 |
| / |
The `stamp` member of the previous answer of this same read, copied unchanged: 64 lower-case hexadecimal characters, the SHA-256 of the text. Required with a nonzero offset, beside that answer's `next_offset`; a first read sends none. A change to the text returns context_changed; restart at offset 0 without a stamp. The stamp does not grant access. Type: string Pattern: ^[a-f0-9]{64}$ |
| / |
Maximum Unicode code points this chunk reaches past the offset asked: 1 through 16000, default 8000. A chunk read from next_offset under the same limit holds at most this many. Offsets and limits count code points, not UTF-8 bytes or UTF-16 code units. Type: integer Minimum: 1 Maximum: 16000 |
| / |
The documentation tree to read: cloud, blueprint, or tzdocs. Leave it out when page begins with a tree's base path, such as /cloud/, because that path names the tree, or beside query, which then searches every tree this connection may read; any other call without it is refused invalid_request. Requires a signed-in connection whose account holds the tree — cloud for every account, blueprint and tzdocs for an account holding Turn Zero Blueprint access — and a tree the served site version holds. Read the index first; then a page by its route, the outline for every page's headings, or a query for the pages a few words match. Type: string Allowed values: ["cloud","blueprint","tzdocs"] |
| / |
Which text of the tree to read: index (the default), one line per page with its title, address, and description. Or outline, the same lines each followed by the page's headings below its title with their anchors, for choosing a page by heading. Or full, every page of the tree in one text with the generated reference left out, for a tool that ingests the tree whole. Not combined with page or query unless left at its default. Type: string Allowed values: ["index","full","outline"] Default: index |
| / |
One page by its route as the index prints it (`/cloud/guides/add-a-database/`), or the same without the base path and the trailing slash; answers that page's Markdown copy from the served version, paged within the page. The page address a completed answer carries is accepted as it is. Without tree, the route must begin with a tree's base path, which names the tree. A route the tree's manifest does not list is refused context_not_found. Not combined with query or with a part other than the default. Type: string Minimum length: 1 Maximum length: 160 |
| / |
A few words; answers the pages whose title, headings, or text hold them, one Markdown line per page in score order — the title, the route, and the page's first matching line — at most 5 pages, an empty text where nothing matches. Without tree, it searches every tree this connection may read, each line's route naming its tree. An empty query, or one of white space alone, is read as left out. The words are recorded nowhere. Not combined with page or with a part other than the default. Type: string Maximum length: 200 |
response
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","stamp","offset","total","next_offset","id","mime_type","text"] Additional properties: false |
| / |
Required value: 1 |
| / |
Type: string Pattern: ^[a-f0-9]{64}$ |
| / |
Where this chunk's text starts: the offset asked, or the nearest place before it where a chunk can begin, such as the start of the line or code block holding it. Type: integer Minimum: 0 Maximum: 9007199254740991 |
| / |
Type: integer Minimum: 0 Maximum: 9007199254740991 |
| / |
Type: ["integer","null"] Minimum: 0 Maximum: 9007199254740991 |
| / |
Type: string |
| / |
Type: string |
| / |
Present where this answer holds only part of the text: in words, the characters read of the total, then either the call that reads on, with next_offset as offset and this answer's stamp, or that this chunk is the last. On a `page` read's first chunk where more follows, it also says that a second read from an offset in `headings`, where present, starts at that section, and that the list is cut where it is. It says too that `query` lists the pages holding a few of a passage's words. Where a chunk after the first starts before the offset asked, it says so. Absent where one answer holds the whole text. The chunks' text joined in order is the whole text. Type: string |
| / |
Present on a `page` read's first chunk where more follows and the page has headings: each heading of depth 2 or deeper outside a code block, in order, with its text and the offset where its line starts. A page with more than 40 lists those of depth 2 alone. The list holds at most 200 entries, the first in the page's order, and a text longer than 200 code points is cut to 200; `continuation` says where either cuts it. Call again with that offset and this answer's stamp to start at the section. Type: array Maximum items: 200 |
| / |
Type: object Required fields: ["text","offset"] Additional properties: false |
| / |
Type: string Maximum length: 200 |
| / |
Type: integer Minimum: 0 Maximum: 9007199254740991 |
| / |
Type: string |
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. An offset inside a line or a code block is read from the nearest place before it where a chunk can begin, which the answer's offset names. 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, the SHA-256 of the text. Required with a nonzero offset, beside that answer's `next_offset`; a first read sends none. A change to the text returns context_changed; restart at offset 0 without a stamp. The stamp does not grant access."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 16000,
"description": "Maximum Unicode code points this chunk reaches past the offset asked: 1 through 16000, default 8000. A chunk read from next_offset under the same limit holds at most this many. Offsets and limits count code points, not UTF-8 bytes or UTF-16 code units."
},
"tree": {
"type": "string",
"enum": [
"cloud",
"blueprint",
"tzdocs"
],
"description": "The documentation tree to read: cloud, blueprint, or tzdocs. Leave it out when page begins with a tree's base path, such as /cloud/, because that path names the tree, or beside query, which then searches every tree this connection may read; any other call without it is refused invalid_request. Requires a signed-in connection whose account holds the tree — cloud for every account, blueprint and tzdocs for an account holding Turn Zero Blueprint access — and a tree the served site version holds. Read the index first; then a page by its route, the outline for every page's headings, or a query for the pages a few words match."
},
"part": {
"type": "string",
"enum": [
"index",
"full",
"outline"
],
"default": "index",
"description": "Which text of the tree to read: index (the default), one line per page with its title, address, and description. Or outline, the same lines each followed by the page's headings below its title with their anchors, for choosing a page by heading. Or full, every page of the tree in one text with the generated reference left out, for a tool that ingests the tree whole. Not combined with page or query unless left at its default."
},
"page": {
"type": "string",
"minLength": 1,
"maxLength": 160,
"description": "One page by its route as the index prints it (`/cloud/guides/add-a-database/`), or the same without the base path and the trailing slash; answers that page's Markdown copy from the served version, paged within the page. The page address a completed answer carries is accepted as it is. Without tree, the route must begin with a tree's base path, which names the tree. A route the tree's manifest does not list is refused context_not_found. Not combined with query or with a part other than the default."
},
"query": {
"type": "string",
"maxLength": 200,
"description": "A few words; answers the pages whose title, headings, or text hold them, one Markdown line per page in score order — the title, the route, and the page's first matching line — at most 5 pages, an empty text where nothing matches. Without tree, it searches every tree this connection may read, each line's route naming its tree. An empty query, or one of white space alone, is read as left out. The words are recorded nowhere. Not combined with page or with a part other than the default."
}
},
"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,
"description": "Where this chunk's text starts: the offset asked, or the nearest place before it where a chunk can begin, such as the start of the line or code block holding it."
},
"total": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"next_offset": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 9007199254740991
},
"id": {
"type": "string"
},
"mime_type": {
"type": "string"
},
"continuation": {
"type": "string",
"description": "Present where this answer holds only part of the text: in words, the characters read of the total, then either the call that reads on, with next_offset as offset and this answer's stamp, or that this chunk is the last. On a `page` read's first chunk where more follows, it also says that a second read from an offset in `headings`, where present, starts at that section, and that the list is cut where it is. It says too that `query` lists the pages holding a few of a passage's words. Where a chunk after the first starts before the offset asked, it says so. Absent where one answer holds the whole text. The chunks' text joined in order is the whole text."
},
"headings": {
"type": "array",
"maxItems": 200,
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"maxLength": 200
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"text",
"offset"
],
"additionalProperties": false
},
"description": "Present on a `page` read's first chunk where more follows and the page has headings: each heading of depth 2 or deeper outside a code block, in order, with its text and the offset where its line starts. A page with more than 40 lists those of depth 2 alone. The list holds at most 200 entries, the first in the page's order, and a text longer than 200 code points is cut to 200; `continuation` says where either cuts it. Call again with that offset and this answer's stamp to start at the section."
},
"text": {
"type": "string"
}
},
"required": [
"contract_version",
"stamp",
"offset",
"total",
"next_offset",
"id",
"mime_type",
"text"
],
"additionalProperties": false
}
}
Shared contracts
- Refusals: every refusal, by surface, with its cause and its remedy
- schemas/wire_error.schema.json
- schemas/wire_errors.json
- schemas/action_payloads.json (includes shared shapes)
- management_api_contract.md