Skip to main content
Glama
rgdevment

Tisty

by rgdevment
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

Read a document, or a part of one

read_doc

Reads a Tisty document in sections, line ranges, or character budgets and returns a print token so you can continue reading or edit passages without loading the whole document.

Instructions

The text of a document and the print it reads at. Left alone it brings the whole body; one past about 12,000 characters comes back as its outline instead, with whole set to false, and then you ask for a section, a run of lines or a budget of chars, about 12,000 at a time. Reading a part is the ordinary way to work: the print comes with every answer, so a passage can be changed with edit_doc without ever bringing the rest. pages_loose names the pages no line in the body names.

Input Schema

NameRequiredDescriptionDefault
asNoBring 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`
toNoLast line. Left out, it reads to the end
docYesThe document's id, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title
fromNoFirst line, counting from 1
charsNoAbout how many characters to bring. The answer says `next` when there is more
printNoThe `print` the previous part came with. Needed only alongside `cursor`, so that two halves are known to be the same document
cursorNoThe `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
sectionNoOne heading and everything under it, numbered as `outline_doc` numbers them, from 0

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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"
+}
  2. First observed

TDQS

A3.9/5.0
Behavior4/5

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

With no annotations the description carries the full load and does so substantially: it discloses the ~12,000-character truncation threshold, the `whole=false` signal, the `print` token returned with every answer that lets a passage be edited without re-reading, and the conversion losses reported in `left_out` when `as: markdown` is used (attachments, mermaid fences, flattened links, HTML formatting). The cryptic 'pages_loose names the pages no line in the body names' sentence is unexplained and reads as opaque jargon.

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?

About 130 words, front-loaded with the whole-document behavior before paging, and each sentence covers a distinct mode or caveat. The final `pages_loose` sentence is an unexplained fragment that a reader cannot place, but otherwise there is little padding.

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

Completeness4/5

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

For an eight-parameter, no-annotation, no-output-schema read tool, the description covers the essential return signals (`whole`, `next`, `print`, `left_out`) and the paging workflow. What is missing is an explanation of what `pages_loose` is and where it appears, plus any note on permissions or failure modes for an inaccessible document.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all eight parameters — including the doc-id-is-not-a-title note and the cursor/print pairing — and the prose largely restates it. The one piece of genuine cross-parameter insight, that a lone `cursor` is ignored and reading restarts from the top, also appears in the schema. Baseline 3 applies.

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 opening states a specific verb and resource ('the text of a document') and immediately frames the two modes — whole body vs. a `section`, line run, or `chars` budget. It distinguishes itself from siblings by naming `edit_doc` for changes and `outline_doc` for section numbering. The undefined token '`print`' and the dangling 'pages_loose' clause keep it from being fully crisp.

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?

Gives concrete when-to-use guidance: called plain it returns the whole body, past ~12,000 characters it returns an outline with `whole` false, and then you page with `section`/`from`-`to`/`chars`. It even prescribes the normal workflow ('Reading a part is the ordinary way to work') and points at `export_doc` for attached files. No explicit statement of when NOT to call this in favor of `outline_doc` or `find`.

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

Deploy Server

Other Tools