Skip to main content
Glama

omniseek_read

Read-only

Read text from any URL or document file, automatically routing to the right reader; extract sections, grep terms, export media, or OCR embedded images.

Instructions

Read text from any URL OR document FILE: OmniSeek's single "read this deep" verb. AUTO-ROUTES.

Tool name: omniseek_read (your MCP config adds its own prefix; never guess one). Not in your tool list? ToolSearch "omniseek_read".

A local path, or a name ending in .pdf/.pptx/.docx/.xlsx/.txt/.md/.csv (and a local .html/.htm), goes to the document reader; anything else to the URL reader. arXiv /abs/ gives metadata, /pdf/ or /html/ the whole paper. A file from another machine goes into OmniSeek host's inbox ~/.omniseek/inbox first (or pass its URL).

Args: target: the URL or document path. start_char: where the returned window starts. max_chars: window size (default 24000); when truncated, re-call with start_char + returned_chars. level: "full" (default) | "brief" (title, author, abstract, size) | "head" (section list with char ranges) | "section". section: a section title (case-insensitive prefix) or index from level="head"; implies level="section". grep: a term, comma-separated terms or a list: return only the sentences that contain one, with one sentence of context. grep_word: grep matches whole words only. grep_case: grep matches case. export_media: (documents) export the embedded images. ocr: (documents) OCR every embedded image and append its text.

Returns (URL) {url, matched, total_chars, returned_chars, start_char, truncated, cached, fetched_at?, text_quality?, document, reason?}: matched false carries reason walled (drill the source by name with omniseek_search) | empty | blocked. Returns (document) {source, total_chars, returned_chars, start_char, truncated, cached, format, title, outline, media_total, media, media_dir, ocr_images?, text_quality?, text} or {source, error, inbox_files?}. text_quality (a PDF whose text layer reads as garbled): {level "low", readings, thresholds, hint}; read those pages with omniseek_view render_pages, and a term not found in that text may still be in the paper. With grep the body is replaced by grep: {terms, hits, occurrences, matches: [{start, end, text, terms}], returned_matches, truncated, next_start_char?}. An unknown section returns error and available_sections. To see figures use omniseek_view. More: omniseek docs/TOOLS.md, omniseek_read.

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": {
      "target": "<target>"
    },
    "name": "omniseek_read"
  }
}

Input Schema

NameRequiredDescriptionDefault
ocrNo
grepNo
levelNofull
targetYes
sectionNo
grep_caseNo
grep_wordNo
max_charsNo
start_charNo
export_mediaNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.3.0
    • addedInput schema / properties / grep
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Grep"
      +}
    • addedInput schema / properties / grep_case
      Added value: +{
      +  "default": false,
      +  "title": "Grep Case",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / grep_word
      Added value: +{
      +  "default": false,
      +  "title": "Grep Word",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / level
      Added value: +{
      +  "default": "full",
      +  "title": "Level",
      +  "type": "string"
      +}
    • addedInput schema / properties / section
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "integer"
      +    }
      +  ],
      +  "default": "",
      +  "title": "Section"
      +}
  2. First observedv0.2.0

TDQS

A4.7/5.0
Behavior4/5

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

Read-only annotations exist, and the description adds substantial behavior beyond them: auto-routing, truncation semantics, cached flag, matched=false reasons (walled/empty/blocked), text_quality low-level PDF handling, and grep body replacement. The only gap is that return shapes are described in a dense inline block rather than fully explaining pagination nuance.

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?

It is front-loaded with the core purpose and routing rule, then structured into Args and Returns. It is long and dense, but nearly every sentence carries operational information. The returns block is verbose and slightly hard to parse, and the 'ToolSearch' note is meta overhead, but structure is clear.

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 no output schema, the description supplies the routing logic, per-argument semantics, return shapes, error cases, quality warnings, and next-step alternatives — everything an agent needs to invoke it correctly and handle failures.

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

Parameters5/5

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

Schema description coverage is 0%, but the description compensates completely: it documents all 10 parameters in an Args block, including target, start_char + returned_chars re-call semantics, max_chars default 24000, level enum values with meanings, section prefix/index behavior implying level=section, grep/grep_word/grep_case, export_media, and ocr — far more meaning than the field names alone provide.

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 states a specific verb+resource combo — 'Read text from any URL OR document FILE' — and explicitly calls itself OmniSeek's single 'read this deep' verb with auto-routing. This distinguishes it from omniseek_search (drill source by name) and omniseek_view (figures), which are named as alternatives.

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 routing rules: local paths or names ending in .pdf/.pptx/.docx/.xlsx/.txt/.md/.csv/.html/.htm go to the document reader, anything else to the URL reader. It names fallback paths (inbox for files from another machine, omniseek_search for walled sources, omniseek_view for figures and render_pages for garbled PDFs), and explains level/section relationships.

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