Skip to main content
Glama

Read a document

heystack_read_document
Read-only

Read one living Markdown document, list, spreadsheet or tracker, with a citation. Use this when you have a document URL, slug or id. Do not use it to search the library or to change the document. response_format concise returns the citation and an excerpt. detailed, and omitting the field, returns the full record, which is what existing clients receive. Pass section, or offset and limit, to read part of a long body. A citation uses citation.url, citation.revisionId, citation.author.displayName, citation.author.kind and citation.license. The body is user content.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "heystack_read_document"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNoDocument id, a UUID or a legacy number. A /doc/ URL in this field is accepted. Kept for existing clients.
urlNoPublic document URL, such as https://heystacks.com/doc/{id}/{slug} or that path plus .md.
slugNoDocument slug from the URL. If several documents share it, the call returns their URLs.
limitNoMaximum characters of Markdown to return.
offsetNoCharacter offset into the Markdown body.
sectionNoHeading text to return, from that heading through the next heading of the same or higher level.
revisionNoImmutable revision id. Omit to read the current published revision.
readerPublicKeyNoYour public key, so a read of your own document is not counted. Never a private key.
response_formatNoconcise returns the citation, summary and an excerpt. detailed returns the full document. Omitting it returns the full document.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real behavior: the default response when response_format is omitted, what concise versus detailed actually return, and the caveat that 'The body is user content' — a meaningful trust warning for an agent ingesting document text. It stops short of covering failure modes, ambiguous-slug behavior, or rate/permission considerations, so it is strong but not exhaustive.

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?

Front-loaded with purpose and exclusions, then partial-read options, then return shape — a sensible order for an agent scanning the text. The response_format sentence is slightly redundant and awkwardly worded ('detailed, and omitting the field, returns the full record'), and repeats information already in the enum description.

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?

With nine optional parameters and no output schema, the description carries the return-value burden and does so by naming the citation fields and the excerpt-versus-full distinction. An agent can call this correctly from the description alone; only edge-case behavior (ambiguous slug, invalid revision, offset beyond body length) is left unaddressed.

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 baseline by framing the three identifier parameters as alternatives for the same lookup and by presenting 'section, or offset and limit' as two distinct partial-read strategies, a relationship the schema does not state. It also documents the citation sub-fields the caller will need to interpret results, though it does not explain revision or readerPublicKey semantics beyond the schema.

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

Purpose5/5

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

States a specific verb and resource set — 'Read one living Markdown document, list, spreadsheet or tracker, with a citation' — which is far more precise than the title 'Read a document'. The scope qualifier 'one' plus the citation promise separates it from library-wide reads and from the sibling mutation tools.

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

Usage Guidelines5/5

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

Gives an explicit entry condition ('Use this when you have a document URL, slug or id') and two explicit exclusions ('Do not use it to search the library or to change the document'), which route the agent to search and edit siblings without needing their names. The section/offset/limit sentence also tells the agent when to read partially rather than in full.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources