toolsets/pdf-toolkit/doc.md

pdf‑toolkit

Extract text, read metadata, list form fields, and merge PDF files. Layout‑aware extraction that handles the messy reality of multi‑column PDFs, encrypted files, and Unicode — so agents don't have to guess.

---

When to Use This Toolset

• Extracting readable text from a PDF for analysis or search
• Reading PDF metadata (author, title, page count) without opening the file
• Listing fillable form fields before filling them
• Merging multiple PDFs into a single document
• Inspecting PDF structure before automated processing

---

Decision Tree: Which Extraction Method?

What do you need from the PDF?

├── All readable text    → pdf_extract (layout‑aware via pdfplumber)
├── Tables from PDF      → pdf_extract + note: pdfplumber can also extract tables
├── Just metadata        → pdf_meta (fast, no page processing)
├── Form fields          → pdf_form_fields (lists names, types, values)
├── Merge PDFs           → pdf_merge (preserves order)
└── Split/extract pages  → pdf_extract with first_page/last_page params

---

Process

Extracting Text

Inspect → Extract → Review

1. Inspect with pdf_meta to check page count and encryption status
2. Extract with pdf_extract — use first_page/last_page for large docs
3. Review the output for formatting issues (common in scanned PDFs, right‑to‑left text, or complex tables)

Working with Form Fields

Inspect → Map → Fill → Validate

1. Inspect with pdf_form_fields to list all field names, types, and current values
2. Map your data to the field names discovered in step 1
3. Fill the form using PyPDF2's update_page_form_field_values
4. Validate by re‑reading the fields to confirm values were set

Merging Documents

Collect → Order → Merge → Verify

1. Collect all input PDF paths
2. Order them in the sequence you want in the output
3. Merge with pdf_merge
4. Verify with pdf_meta to check the output page count matches the sum

---

Function Reference

pdf_extract

Extract readable text using layout‑aware parsing.

When to use: Whenever you need text content from a PDF — search, analysis, indexing.

Args:

• filepath (str) — Path to the PDF
• first_page (int) — First page to extract (1‑based, default 1)
• last_page (int) — Last page to extract (0 = all pages)

Returns: {text, pages, total, range}

Gotcha: Scanned PDFs (images of text) will return empty text. You'd need OCR (not yet included). Check pdf_meta for the producer — "scanner" or "Image" in the producer field is a clue.

pdf_meta

Read metadata without processing page content.

When to use: Quick inspection before extracting, or when you only need structural info.

Args:

• filepath (str) — Path to the PDF

Returns: {filename, pages, title, author, subject, creator, producer, encrypted, file_size_bytes}

pdf_merge

Merge multiple PDFs into one, preserving page order.

When to use: Combining chapters, appendices, or separate scans into a single document.

Args:

• inputs (list) — Ordered list of file paths to merge
• output (str) — Path for the merged output PDF

Returns: {written, pages, sources}

pdf_form_fields

List all fillable form fields with types, current values, and options.

When to use: Before programmatically filling a PDF form — you need to know the field names.

Args:

• filepath (str) — Path to the PDF

Returns: {has_fields, count, fields: [{name, type, value, flags, options}], filename}

Field type guide:

Type	Meaning
Tx	Text field
Btn	Checkbox or radio button
Ch	Dropdown / choice
Sig	Signature field

---

Common Patterns

Pattern: Extract and Analyze

pdf_meta     → page count, encryption status
pdf_extract  → full text
text_stats (from text-transform toolset) → readability, word count

Pattern: Form Auto‑Fill

pdf_form_fields → list of field names and types
Map data to fields
Use PyPDF2 to fill fields programmatically
pdf_form_fields → verify values were set

Pattern: Document Assembly

pdf_meta on each input → sanity check
pdf_merge → combine in order
pdf_meta on output   → verify page count = sum of inputs

---

Guidelines

Do

• Always check pdf_meta first to understand encryption and page count
• Use first_page/last_page for large documents (100+ pages)
• Verify merged output with pdf_meta — page count should equal sum of inputs
• Handle the case where pdf_extract returns empty text (scanned PDF)

Don't

• Don't try to extract text from password‑protected PDFs (check encrypted in pdf_meta)
• Don't assume extracted text preserves exact original layout — it's best‑effort
• Don't merge PDFs with different page sizes without checking
• Don't fill forms without first inspecting field types (checkbox vs dropdown vs text)

Limitations to Communicate

• Scanned PDFs: text extraction may return empty — mention this when it happens
• Highly formatted documents: pdfplumber does its best but may misorder text in complex layouts
• Password protection: encrypted PDFs must be unlocked before processing
• Form filling: pdf_form_fields lists fields; actual filling requires additional PyPDF2 calls