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 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 to retain its styles, fields and package content. Recreating it from extracted text is appropriate only when the user wants a new representation.