Skip to main content
Glama

Read a document, or a part of one

read_doc
Read-onlyIdempotent

Reads a document's Markdown text, outline, sections, lines or characters, returning the print each part needs for edits without a whole read.

Instructions

A document's text and the print it reads at. Past about 12,000 characters it comes back as its outline (whole false): then ask for a section, lines, or chars at a time. Every part brings the print, so edit_doc needs no whole read.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "doc": "<doc>"
    },
    "name": "read_doc"
  }
}

Input Schema

NameRequiredDescriptionDefault
asNoThe whole document in GitHub Markdown for another tool; tell the person what `left_out` lists (`rules` «documents»). Not with `section`, lines or `chars`
toNoLast line; left out, to the end
docYesThe document's id from `docs`, not its title
fromNoFirst line, from 1
charsNoAbout how many characters to bring; the answer gives `next` when there is more
printNoThe `print` the previous part came with; only with `cursor`
cursorNoThe `next` a previous answer gave, with `chars`
sectionNoA heading and all under it, by its `at` in `outline_doc`, from 0

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv1.43.2
    • changedInput schema / properties / as / description
      Previous value: -"Bring the whole document in standard GitHub Markdown, to hand to another tool — Confluence, Jira, Notion, Linear, GitHub — whose own tools turn it into their format. Not everything travels, and the answer says what this document loses in `left_out`, which you tell the person before publishing: attached files stay in Tisty — `export_doc` writes them into a folder, from where the other place's tool uploads them; diagrams stay mermaid fences, drawn by GitHub, GitLab and Notion but shown as code by Confluence and Jira; links to other documents and tasks become plain words; pens, underlines, icons and folds go as HTML tags some places show as written. A document put away or marked as having had its day says so first. Pages come apart, each read with `as`. It takes no part of the document: no `section`, lines or `chars`"New value: +"The whole document in GitHub Markdown for another tool; tell the person what `left_out` lists (`rules` «documents»). Not with `section`, lines or `chars`"
    • changedInput schema / properties / chars / description
      Previous value: -"About how many characters to bring. The answer says `next` when there is more"New value: +"About how many characters to bring; the answer gives `next` when there is more"
    • changedInput schema / properties / cursor / description
      Previous value: -"The `next` a previous answer gave, to carry on from there. It goes with `chars`; on its own it is ignored and the reading starts again from the top"New value: +"The `next` a previous answer gave, with `chars`"
    • changedInput schema / properties / doc / description
      Previous value: -"The document's id, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title"New value: +"The document's id from `docs`, not its title"
    • changedInput schema / properties / from / description
      Previous value: -"First line, counting from 1"New value: +"First line, from 1"
    • changedInput schema / properties / print / description
      Previous value: -"The `print` the previous part came with. Needed only alongside `cursor`, so that two halves are known to be the same document"New value: +"The `print` the previous part came with; only with `cursor`"
    • changedInput schema / properties / section / description
      Previous value: -"One heading and everything under it, numbered as `outline_doc` numbers them, from 0"New value: +"A heading and all under it, by its `at` in `outline_doc`, from 0"
    • changedInput schema / properties / to / description
      Previous value: -"Last line. Left out, it reads to the end"New value: +"Last line; left out, to the end"
  2. Changed1 schema field changedv1.33.0
    • addedInput schema / properties / as
      Added value: +{
      +  "description": "Bring the whole document in standard GitHub Markdown, to hand to another tool — Confluence, Jira, Notion, Linear, GitHub — whose own tools turn it into their format. Not everything travels, and the answer says what this document loses in `left_out`, which you tell the person before publishing: attached files stay in Tisty — `export_doc` writes them into a folder, from where the other place's tool uploads them; diagrams stay mermaid fences, drawn by GitHub, GitLab and Notion but shown as code by Confluence and Jira; links to other documents and tasks become plain words; pens, underlines, icons and folds go as HTML tags some places show as written. A document put away or marked as having had its day says so first. Pages come apart, each read with `as`. It takes no part of the document: no `section`, lines or `chars`",
      +  "enum": [
      +    "markdown"
      +  ],
      +  "type": "string"
      +}
  3. First observed

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish this is a safe, idempotent, closed-world read, so the bar is lower, yet the description adds genuinely non-obvious behavior: the ~12,000-character outline fallback, the `whole` false marker, and the fact that each partial read returns the print token. What it doesn't explain is what the print actually is or what happens when it's stale — the main hazard for a tool feeding `edit_doc`.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences, front-loaded with the outcome (text plus print) and then the large-document escape hatch. No filler, though the elliptical fragments ('A document's text and the `print` it reads at') and undefined term 'print' cost a little immediate comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an eight-parameter, no-output-schema read tool, it covers the pagination strategy and the edit_doc interop well. It leaves the `print` concept under-defined — there's no output schema to explain it — and never mentions error behavior for a stale or missing print, which is the one thing an agent could get wrong.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the interaction between `chars`, the returned `next`, and `cursor` as a pagination loop, and by tying partial reads together via `print`. It says less about `section` (left to the schema's `outline_doc`/`at` reference) and nothing about `from`/`to` beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The title-plus-description pair makes it clear this returns a document's text plus a `print` token, and the description explicitly separates the whole-document case from the large-document outline case. It doesn't spell out the plain 'read the document' framing in a full sentence, but the verb and resource are unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete branching guidance: past ~12,000 characters you get the outline (`whole` false) and should then ask for a `section`, lines, or `chars` at a time. It also closes the loop with `edit_doc`, noting every part carries the print so no whole read is needed. It stops short of naming sibling reads like `outline_doc` or `read` as alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.