---
name: pdf-parse
description: Parse a local PDF into layout-aware markdown and 0-1000 bounding boxes with an authenticated Pi vision model.
---

# PDF parsing

Use `pdf_parse` when the user wants to read, OCR, convert, or structurally parse a local PDF. The tool selects only a Pi-authenticated vision model with a validated parser prompt.

The tool streams structured progress while it plans the run, resolves Pi credentials, renders pages, requests each page, decodes blocks, and writes artifacts. If decoding produces zero blocks, report the diagnostic directory and inspect the preserved `raw/page-NNNN.txt` response before recommending a different model or prompt change.

- Pass `source` as a local PDF path.
- Omit `model` to use the saved default, then subscription/local access, then the cheapest known metered pair.
- Use `dry_run: true` when the user asks for a cost or provider check before parsing.
- Respect a user-supplied budget with `max_cost_usd`.
- Use non-contiguous `pages` such as `1-3,8` when only part of a document matters.
- Do not claim that an authenticated but unmatched model is ready; `/pdf-parse models` reports those as `untested`.
- After parsing, use the written `doc.md`, `blocks.json`, and `manifest.json` artifacts rather than reparsing the PDF.
- Use `pdf_search` to locate known text and return page+bbox hits. It searches parsed semantic blocks when present and otherwise uses the native PDF text layer.
- Use `pdf_screenshot` after search when visual inspection of charts, tables, signatures, or page layout is needed.