Skip to main content
Glama

read

Read-only

Read web pages, local files and scholarly papers as Markdown, returning each item's content or error, and optionally answer one question across all items.

Instructions

Reads pages, files and papers — web pages, local documents and scholarly works, as Markdown. Call read{urls:["https://…"], files:["/path/to/file.pdf"], publications:["10.1038/nature14539"]}: 1–50 items, at most 20 publications. A title goes to search_literature first; a file wanted as bytes to download_file. Returns one text block per item, input order: === [n/N] {item}, the artifact's absolute path, a partial: or truncated: line when incomplete, then the content. A failed item is its header and an error: line; all failed = an error result. Add ask:"question" for one answer over every item, in a last === answer block.

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": "read"
  }
}

Input Schema

NameRequiredDescriptionDefault
askNoOptional question, answered once over every item read, after the item blocks; the items then show their size, not their content, unless include_content is true.
urlsNoWeb page URLs (http or https), each read as a page; a PDF or document URL is parsed. An identifier goes in publications, a local path in files.
filesNoLocal document paths (or file:// URLs) on this machine, each parsed to Markdown. A web URL goes in urls. Formats: PDF, DOC, DOCX, XLS, XLSX, PPTX (with their macro and template variants), ODT, ODS, ODP, RTF, EPUB, HTML, CSV, JSON, Markdown and plain text.
modelNoWith ask: the model that answers it, an alias (haiku, sonnet, opus, fable) or a model id; default haiku on claude, the configured ask model on codex.
engineNoWith ask: the engine that answers it, claude (default) or codex.
headersNoOptional request headers (name → value) sent only to a url's own origin and a publication's landing origin, never with files; reader services, archives and resolver APIs never receive them. At most 32 headers, 8 KiB; no Host, Content-Length, Transfer-Encoding, Connection, Upgrade, TE, Trailer, Keep-Alive or Proxy-*. A caller header overrides the default of its name.
refreshNoBypass the cache: read every item again and overwrite its cached artifact.
ocr_languageNoOptional script for OCR of a scanned document: latin, zh, ja, ar, ru or he. By default the document's text layer, /Lang or metadata names it, else Latin; set it when a scan's gaps say it was read in Latin. Always a fresh read.
publicationsNoAt most 20 works: a DOI, arXiv id, PMID, PMCID, ISBN, a search_literature handle, or a paper or book landing URL, each read as its full text.
include_contentNoDefault true. false: read and cache the full content, answering a size line in place of the body.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations declare readOnlyHint=true but idempotentHint=false, and the description explains exactly why: refresh bypasses and overwrites the cache, and OCR is 'always a fresh read' — behavior the annotations alone could not convey. It further discloses the per-item return format, partial/truncated markers, per-item error lines, and all-failed error results, though it says nothing about rate limits or authentication requirements.

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 the call shape, then routing rules, then return format — a logical progression with no filler. It is dense and long-ish, and the inline JSON call example plus the return-format template compress a lot into single sentences that require re-reading, but every sentence carries information.

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

Completeness5/5

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

For a 10-parameter tool with nested objects, no output schema, and no required parameters, the description covers invocation shape, limits, sibling routing, failure behavior, and return layout — enough to call it correctly without the output schema. Nothing essential is missing.

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 extra by adding cross-parameter semantics the schema doesn't tie together — that ask suppresses item bodies unless include_content is true, and that a publication cap of 20 applies. It does not explain model/engine selection tradeoffs beyond naming the defaults, leaving some meaning to 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?

The description opens with a specific verb and resource set: 'Reads pages, files and papers — web pages, local documents and scholarly works, as Markdown.' It distinguishes its three input families and explicitly routes titles to search_literature and byte-wanted files to download_file, so an agent can tell it apart from both siblings without opening a schema.

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?

Explicit when-to-use and when-not: 'A title goes to search_literature first; a file wanted as bytes to download_file.' It also states the item-count limits (1–50 items, at most 20 publications) and the ask: pattern for answering over every item, giving clear selection conditions rather than leaving them to inference.

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