Skip to main content
Glama

read_document

Extracts text from 1–5 pages or logical chunks of a registered PDF, DOCX, XLSX, DOC, or XLS by SHA-256 ID, with optional OCR for scanned PDF pages.

Instructions

Read 1–5 pages/chunks of a registered PDF, DOCX, XLSX, DOC or XLS by SHA-256 ID.

PDF pages report whether they have embedded text. Set ocr=true to run optional local Polish OCR on pages without embedded text. Returns untrusted text and source metadata. DOCX/XLSX/DOC/XLS page numbers are logical chunks; PDF page numbers are physical pages.

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

Input Schema

NameRequiredDescriptionDefault
ocrNo
pageNo
pagesNo
document_idYes

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.8/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 burden and does substantial work: it discloses that only PDF pages report embedded-text presence, that OCR is local and Polish-only, that returns contain untrusted text plus source metadata, and that page numbering semantics differ by format (logical chunks vs physical pages). It stops short of noting cost/latency for OCR or any read-only guarantee beyond the verb 'Read'.

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?

Four front-loaded sentences with no filler – each one adds a distinct fact (scope, embedded-text reporting, OCR option, page-numbering semantics). The stray line breaks and the dense 'optional local Polish OCR' phrasing are minor blemishes.

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 a four-parameter read tool with no annotations and 0% schema coverage, the description supplies the format list, page semantics, OCR conditionality, and the untrusted-text nature of the return. Since an output schema exists, the return-value gap is acceptable, though the page/pages interaction and defaults remain underspecified.

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 0%, so the description must compensate, and it largely does: 'ocr' gets meaning (OCR only on pages lacking embedded text, Polish), 'page'/'pages' get per-format semantics (logical chunks for Office formats, physical pages for PDF), and 'document_id' is identified as a SHA-256 of a registered document. The interaction between 'page' and 'pages' (is 'pages' a count from 'page' or an end page?) and the defaults are not stated.

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 description uses a concrete verb ('Read') with a bounded scope ('1–5 pages/chunks') and names the resource and identifier type ('a registered PDF, DOCX, XLSX, DOC or XLS by SHA-256 ID'). It does not differentiate itself from the sibling 'fetch_documents', which an agent could plausibly confuse with this one.

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

Usage Guidelines3/5

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

There is conditional guidance for a parameter ('Set ocr=true ... on pages without embedded text'), which is genuinely useful. However, nothing says when to choose read_document over fetch_documents or list_documents, and no prerequisites (e.g. that the document must already be registered) are spelled out beyond the adjective 'registered'.

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