# Your agent cannot read a scanned PDF

> A scan is a picture of a page. There is no text to extract, so the file opens fine and comes back empty.

Canonical HTML version: https://mcpbelt.com/problems/read-a-scanned-pdf

## The problem

You hand your agent a PDF. It opens, it has forty pages, and the answer that comes back is that the document appears to be empty, or worse, a confident summary of the two lines that happened to be in the file's metadata.

The file is a scan. Someone put paper on a glass plate, and what came out is a picture of a page wrapped in a PDF container. To a human it looks identical to a document. To anything that reads text, it is a photograph with nothing to read.

This is the single most common way a document workflow fails, and it fails silently: no error, no warning, just an answer built on nothing.

## Why it fails locally

A PDF is a container, not a format. It can hold a text layer, or page images, or both. `pdftotext`, `pypdf` and every library like them read the text layer, and on a scan that layer does not exist. They return an empty string and no error, because from their point of view nothing went wrong.

Recognising the characters in the image is optical character recognition, and that is a different job from parsing a file. Running it locally means installing an OCR engine, keeping its language data current, and accepting whatever quality it gives you. The part nobody mentions is the hard part: **you cannot tell when it read badly.** An engine that gets 15% of the characters wrong returns the same shape of answer as one that got them all right.

So the naive local path either returns nothing, or returns something wrong with no way to know which.

## The code

Upload the file, then read it. The `key` comes from `upload` and is not a path on your disk: this service cannot see your disk.

```
upload(filename="invoice.pdf", content_type="application/pdf")
  -> key, upload_url

curl -T invoice.pdf "<upload_url>"

read(key="<key>")
  -> handle, engine, cost_eur, structure, text
```

## What it costs

`read` in `balanced` mode costs 0.007 EUR per page. It first tries to extract the text locally, which costs nothing, and pays an OCR engine only when that fails. On a scan it always fails, so a scan always costs the per-page price.

`exact` costs 0.016 EUR per page and skips the free attempt entirely. Use it when the PDF does carry a text layer but you do not trust it, which happens on old scans that were run through someone else's OCR years ago.

Pages are counted from the file itself, not estimated from its size, so a forty-page scan is charged as forty pages. If the same file is read twice, the second call returns the first result and charges nothing.

## What this does not do

- The text comes back as text. Handwriting, stamps and signatures are not reliably read by any engine, ours included.
- Email files (EML, MSG) and ebooks (EPUB) are read by no engine. Extract the text or convert to PDF.
- The file is fetched from the address you upload it to and passed to an engine that runs elsewhere. If the document cannot leave your machine, this is the wrong tool.