---
name: pdf-tools-fill-pdf-form
description: "Fill one existing fillable PDF form from known details or a saved profile, the way a careful clerk does: read the real field list first, map values to fields by meaning, check required fields and types, fill, then verify the result before reporting it done. Use when the user asks to fill in, complete, populate or prefill a PDF form, apply a saved profile to a form, or asks which fields a form needs. Use bulk-fill-pdf-from-csv instead when many files or many records are involved."
---
# Fill an existing PDF form
A filled form is only correct when every value landed in the field it was meant for and the document still says what it said before. The common failure is not an error message; it is a value written silently into the wrong box, a date in a day-month field, or a checkbox that looks ticked but is not. Work from the form's own field list, never from memory of what a "typical" form contains.
## 1. Confirm the file and the target
Before anything else, establish which PDF is the target:
- Use `list_pdfs` to see what is in the active folder, then confirm with the user the exact file if more than one looks plausible.
- Check that the file is the blank template or an intended copy. A form that already has values may be someone else's completed submission; say so and ask before filling over it.
- If the user names a file outside the allowed directories, stop and explain that PDF Tools only reads and writes its active folders. Do not work around the boundary.
## 2. Read the field list before deciding anything
Call `read_pdf_fields` on the target. Record for each field: its name, type (text, checkbox, radio, choice, signature), whether it is required, its current value, and any allowed options. Field names are often cryptic (`Text1`, `chk_03`, `f2_date`), so the label is the thing to match, and the label usually lives in the text near the field. If names are opaque and the mapping is unclear, call `read_pdf_layout` or `read_pdf_content` for the page to read the labels beside each box.
Decision points at this stage:
- **No fillable fields at all.** The PDF is flat (scanned or printed). Stop filling. Say that it is not a fillable form and offer to read its content or render it for manual completion instead.
- **Fields exist but the required list is long and the user has given few details.** List the missing required fields and ask for them rather than inventing values.
- **Field names suggest a different form than the user described.** Confirm before filling.
## 3. Map user-supplied values to fields
Build a table of field name to value before calling `fill_pdf`. Map by meaning:
- Keep the source of each value visible: from the user's message, from a named saved profile, or from an assumption you flagged.
- Watch for ambiguous pairs: "address" versus "mailing address", "date" when the form has a signing date and a birth date, "name" versus "printed name". Ask rather than guess when a wrong mapping would be costly.
- Checkboxes and radio groups take their allowed on-state value, which may not be "yes" or "true". Use the option listed in the field read. A radio group takes one option only.
- Dates: write them in the format the field expects, and state the format you used to the user. Day and month order is a silent error source; if the field shows no format and the date could be read two ways, ask.
- Never fill a signature field with typed text unless the user intends a typed signature and the form accepts one. Signing is a separate workflow.
For a saved profile, call `list_profiles` and then `fill_with_profile` (or `load_profile` if you need to inspect what it contains first). A profile can hold stale details: an old address or a previous tax year. Show the user the values that will go in, especially for dates, identifiers and money, before applying.
## 4. Check before writing
Run these checks against your table:
- Every required field is covered, or you have a documented reason to leave it blank.
- Each value fits the field type: no letters in a numeric field, a valid date, a checkbox value that is in the allowed list.
- No value is longer than the field plausibly holds (a truncated postcode or account number is a real risk).
- Nothing is written to a field that the form labels as office-use-only, unless the user has confirmed it.
## 5. Fill, to a new copy, then verify
Filling changes a file, so it needs explicit approval. Show the user the full mapping table (field, value, source) and wait for the user's explicit yes before calling `fill_pdf`. Prefer writing to a new output file so the blank template is kept.
After filling, verify rather than trusting the call succeeded:
- Call `read_pdf_fields` on the output and compare every value with your table. Any field that differs, or is empty when it should not be, is a failure to report.
- Call `render_pdf_page` on the filled page(s) and look at the result. Confirm the values sit inside their boxes and that a checkbox shows as ticked, not just stored.
- Call `validate_pdf` if the form is expected to be valid for submission.
## Common patterns and traps
- **Value accepted, displayed wrong.** The stored value is correct but the field has a formatting mask or font that clips it. The render step catches this; the field read does not.
- **Checkbox "filled" by writing text.** A checkbox needs its on-state value. Writing "Yes" to a box whose on-state is "1" leaves it visibly unticked.
- **Radio group filled with two options.** Only one can be selected; the second silently replaces the first. Check the final state of the group.
- **Stale profile.** A saved address from an earlier year looks authoritative. Always show profile values before applying them.
- **Date order.** 04/05 means 4 May to one reader and 5 April to another. Use the format the field implies, and say which you used.
- **Field names mislead.** A field called `Name` may be the company name on a business form. Match against the label, not the name.
- **Overwriting existing data.** A form that already contains values is either a draft to continue or someone else's submission. Ask which.
- **Filling does not sign or submit.** A filled form is not a completed legal act. Do not describe it as submitted or signed.
## Output
```
File: →