Skip to main content
Glama

read_document

Read-onlyIdempotent

Extracts raw text from PDF, Office, EPUB, HTML, CSV, Markdown, and notebook files, with PDF page ranges, OCR for scanned pages, and paginated offsets for long documents.

Instructions

Read text content from a document with optional page selection. Use this when you need the raw text of a PDF, TXT, MD, CSV, DOCX, XLSX, PPTX, ODT, EPUB, HTML, RTF or IPYNB file; TXT/MD/CSV are returned verbatim, the Office, EPUB, HTML, RTF and notebook formats via pandoc; PDFs support page ranges (e.g. "1-5", "1-3,7,10-12") and auto-OCR fallback for scanned pages. Long texts come in pages of max_chars characters; a truncated result ends with the offset to ask for next. Read-only.

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": {
      "filename": "<filename>"
    },
    "name": "read_document"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoOptional single page number to read (1-based, PDF only). If omitted, returns full text.
pagesNoOptional page ranges to read (PDF only), e.g. "1-5", "10", "1-3,7,10-12". Overrides 'page' if both provided.
offsetNoCharacter offset to start reading from (default 0). A truncated result ends with the offset of the next page.
filenameYesThe document filename to read
max_charsNoMaximum characters to return (default 50000, at most 200000).

Output Schema

NameRequiredDescriptionDefault
textYesThe text of this page of the document
next_offsetNoOffset to pass on the next call; absent when this page reaches the end
total_charsYesLength of the whole text in characters

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv1.4.1
    • addedInput schema / properties / max_chars
      Added value: +{
      +  "default": 50000,
      +  "description": "Maximum characters to return (default 50000, at most 200000).",
      +  "maximum": 200000,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedInput schema / properties / offset
      Added value: +{
      +  "default": 0,
      +  "description": "Character offset to start reading from (default 0). A truncated result ends with the offset of the next page.",
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedInput schema / properties / page / description
      Previous value: -"Optional single page number to read (1-based). If omitted, returns full text."New value: +"Optional single page number to read (1-based, PDF only). If omitted, returns full text."
    • changedInput schema / properties / pages / description
      Previous value: -"Optional page ranges to read, e.g. \"1-5\", \"10\", \"1-3,7,10-12\". Overrides 'page' if both provided."New value: +"Optional page ranges to read (PDF only), e.g. \"1-5\", \"10\", \"1-3,7,10-12\". Overrides 'page' if both provided."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "next_offset": {
      +      "description": "Offset to pass on the next call; absent when this page reaches the end",
      +      "type": "integer"
      +    },
      +    "text": {
      +      "description": "The text of this page of the document",
      +      "type": "string"
      +    },
      +    "total_chars": {
      +      "description": "Length of the whole text in characters",
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "text",
      +    "total_chars"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.1.0

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real behavior beyond that: verbatim vs pandoc conversion per format, auto-OCR fallback for scanned PDF pages, and the truncation/offset continuation contract. It does not discuss cost, latency, or failure modes on unsupported/corrupt files.

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 then format support then pagination, and every clause carries information. The single dense sentence for the format list is slightly run-on but not wasteful.

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 an output schema present, return shape need not be explained, and the description covers format scope, OCR fallback, and pagination adequately. Minor gaps remain around error conditions and whether filename is a path or relative name, but the definition is callable as written.

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 all five parameters are already documented, including the page-range syntax and the offset continuation. The description's mentions of page ranges and max_chars largely restate the schema, adding only the 'truncated result ends with the offset' loop as a workflow hint.

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 precise verb+resource ('Read text content from a document') and immediately enumerates the supported formats and per-format behavior. It is clearly distinguishable from siblings like get_document_summary, extract_tables, or ocr_document, which return derived artifacts rather than raw text.

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 a clear triggering condition ('Use this when you need the raw text of a ... file') that implicitly excludes summary/table/image extraction tools. It never explicitly names an alternative or says when NOT to use it (e.g. use get_document_summary for large PDFs), so it stops short of full routing guidance.

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