website/docs/user-guide/features/document-extraction.md

metadata

sidebar_position: 3
title: Document Extraction
description: >-
  How read_file converts PDFs, Office documents, and notebooks to text — and
  what to do when a PDF is scanned images

Document Extraction

The read_file tool automatically converts common document formats to readable text, so the agent can inspect a PDF or spreadsheet the same way it reads source code.

Supported formats

Format	Extensions	Converter	Availability
Jupyter notebooks	.ipynb	Built-in (stdlib)	Always
Word documents	.docx	Built-in (stdlib)	Always
Excel workbooks	.xlsx	Built-in (stdlib)	Always
PDF	.pdf	Optional anydoc converter	Auto-installed on first use*
Legacy Office	.doc, .ppt, .xls, .pptx, and variants	Optional anydoc converter	Auto-installed on first use*
OpenDocument	.odt, .ods, .odp	Optional anydoc converter	Auto-installed on first use*
Rich text / eBooks	.rtf, .epub	Optional anydoc converter	Auto-installed on first use*

* The optional converter is the firecrawl-anydoc package, installed lazily where installs are permitted (security.allow_lazy_installs in config.yaml). Without it, the three stdlib formats still work; other formats fall back to the binary-file guard.

Conversion output is Markdown, paginated through read_file's normal offset/limit window. Documents over 50 MB are refused to keep tool turns bounded.

Extraction works with remote terminal backends (Docker, Modal, SSH): the file's bytes are transferred across the backend boundary and converted host-side, so a document inside a sandbox reads the same as a local one.

Scanned PDFs: the coverage warning

PDF conversion reads the text layer only. Pages that are scanned images — common in legal documents, resale packages, signed contracts, faxes — contain no text layer and silently convert to nothing. The telltale signature is section headers with empty bodies.

When a meaningful share of pages yields no text (over 20% of the document, or 10+ pages absolute), read_file prepends a warning to the extraction. Each unreadable gap is labeled with the last text extracted before it — usually a section divider — so the agent can target only the gaps it actually needs instead of OCRing the whole document:

[EXTRACTION COVERAGE WARNING: 198 of 311 pages in this PDF yielded no
text. ... Unreadable gaps, each labeled with the last text extracted
before it:
  pages 42-77 (36 pages) — after "Antigua Maintenance Corp Bylaws" (p41)
  pages 92-213 (122 pages) — after "... Covenants, Codes and Regulations" (p91)
  page 224 (1 page) — after "... Insurance Declaration Pages" (p223)
Decide which gaps you actually need — do NOT OCR or render everything. ...]

The warning lists the exact page ranges and the recovery paths:

1. A few pages — render + vision. Convert the pages to images and read them with the vision tool:

   pdftoppm -jpeg -r 150 -f 92 -l 94 document.pdf /tmp/page
   

   Then inspect each image with vision_analyze. Zero extra dependencies (poppler is required for the detection itself).
2. Many pages — OCR. The ocr-and-documents skill covers bulk OCR with marker-pdf (90+ languages, handles equations and tables; ~3-5 GB install).

Detection uses poppler's pdftotext for per-page text counts. If poppler is not installed, extraction still works — the coverage check is silently skipped.

:::tip The agent handles the warning on its own — it will offer to render or OCR the missing pages. If you're reading extractions yourself, treat "header with an empty body" as a scanned section, not a missing one. :::