---
title: PDFs and document workflows
description: PDF page operations, redaction, sanitization, forms, passwords and local document authoring.
order: 4
---

# PDFs and document workflows

Use `file_read` for text and metadata, `file_preview` for appearance, and `pdf_layout` for positioned text or structured reading order. These serve different needs: readable text alone does not prove that a visual layout survived export.

## PDF operations and options

| Need | Tool and nuance |
| --- | --- |
| Combine files | `pdf_merge`, in the order provided |
| Split or select | `pdf_split`, `pdf_pages`; pages are 1-based, with ranges such as `1-3,5`, `odd`, `even`, `all` |
| Compare | `pdf_compare` compares visible pages, including scans, aligns unchanged pages across insertion/removal; up to 250 pages per input |
| Crop | `pdf_crop` uses top/right/bottom/left insets in PDF points from visible edges; hidden content remains recoverable |
| Read layout | `pdf_layout` positions are points from top-left; `structure: true` requests headings, paragraphs, lists and tables in reading order; follow pagination |
| Extract images | `pdf_extract_images` writes embedded images at native resolution, deduplicating repeats; up to 500 images and 1 GB per call |
| Forms | Inspect IDs/options using `pdf_form_fields`, then `pdf_fill_form`; optionally flatten |
| Passwords | `pdf_protect` creates an AES-128 protected copy with permission options; `pdf_unlock` needs the password |
| Watermarks/numbers | `pdf_watermark`, `pdf_page_numbers` create stamped copies |
| Metadata/bookmarks | `pdf_set_metadata`; empty string removes a field; protected input needs a password and its output copy is unprotected |
| Damaged structure | `pdf_repair` may write a verified recovered copy; an already readable file needs no new file; recovered page count can differ from the intended original |

Page selection retains supported document structure, including page labels and tags associated with kept pages. Links or bookmark destinations targeting omitted pages can no longer navigate there. Extracted copies do not retain source encryption; apply protection separately when required. Page selection is not a scrub of private metadata, embedded files or sensitive content on retained pages.

PDFs normally use 72 points per inch. Raster export DPI is a separate choice from the page's point dimensions. Form filling uses the actual field identifiers, not nearby visual labels; flattening removes interactive editing of those fields.

## Redaction, cleanup and cropping are different

Use `pdf_find_redactions` to search selectable text and tagged replacement text (`ActualText`) with literal or regex queries. Review the matches, their page rectangles and revision; then call `pdf_redact` with the same queries, revision and chosen IDs. A whole-span match can cover multiple pages. The tool produces a verified copy that removes the selected text and associated replacement text.

**Text redaction is not automatic discovery of every sensitive mark.** Sensitive pixels in a scan, handwriting or an image require a suitable image-aware redaction workflow. A crop, black rectangle, watermark or blur is not a substitute for removing underlying sensitive content. Do not describe a text-only redaction result as a comprehensive scrub of the file.

`pdf_sanitize` handles a different task: by default it flattens visible forms and markup while retaining links, and removes document metadata, embedded files, scripts and launch actions. Page text remains selectable. Use redaction for sensitive content on the page. Compression is yet another operation and does not imply either sanitization or redaction.

Protection behavior varies by tool: do not assume encryption survives every PDF operation. In particular, metadata editing explicitly produces an unprotected copy. Discover the tool's password and output contract and disclose protection changes when they matter.

## Create documents and diagrams

`document_create` accepts Markdown or a structured outline with headings, paragraphs, lists, tables, code, quotes, images and page breaks. Outputs include DOCX, PDF, Markdown and HTML; PDF options include paper size, typeface, font size, contents and page numbers. Images must be shared absolute paths or data URIs; other references may be omitted with warnings. Read those warnings. The tool returns the published revision and records creation history where available; DOCX results can include an editable outline with heading/body IDs. See [native Office creation](/docs/office-creation/) for continuing the edit.

`typst_compile` compiles inline source or a `.typ` file to PDF or PNG/SVG pages. It is hermetic: no packages or network. File-based reads/images reach only shared files in the source folder; inline source cannot read files. Compilation failures include line/column diagnostics.

`diagram_render` renders D2 source or a `.d2` file to SVG, PNG or PDF using the bundled offline engine. Imports/icons must be shared local files in the source folder; remote icons are refused.

When editing an existing Word document, use the [structured Office workflow](/docs/office-data/) to retain its styles, fields and package content. Recreating it from extracted text is appropriate only when the user wants a new representation.