Prepare signature placeholder
prepare_signature_placeholderIdempotent
Creates an unsigned PDF with a /Sig placeholder for later signing, letting you size reserved bytes, pin the widget page, and choose the PAdES subfilter.
Instructions
New PDF carrying an unsigned /Sig placeholder for a LATER sign_pdf call. OPTIONAL — sign_pdf auto-injects one. Use it to size the placeholder (placeholderBytes for > 4096-bit keys, reserveTimestamp for an RFC 3161 token), to pin the widget page (pageIndex), to choose subFilter 'ETSI.CAdES.detached' (PAdES), or to ship the placeholder separately. signerName/reason/location/contactInfo/signingTime are frozen into /Sig here — sign_pdf cannot rewrite them later. NOTE: the unsigned file is not yet a conformant PDF/A (empty /Contents); it becomes one once signed. PDF/A, print, metadata and creationDate options as on every document tool.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pdfA | No | PDF/A level: pdfa1b (simple text+images), pdfa2b/pdfa2u (richer; 2u = Unicode mapping), pdfa3b (attachments / Factur-X). Pair with embedFonts=true for a valid claim. Exclusive with encryption. See docs/guides/PDFA.md. The unsigned placeholder is NOT yet conformant (empty /Contents, ISO 19005-2 §6.4.3); it is once signed with sign_pdf profile:'pades'. | |
| debug | No | Draw margin / block / cell guide rectangles (unmarked content — not for PDF/UA output). Geometry unchanged. Default false. | |
| No | Print production (ISO 32000-1 §14.11): page boxes, `bleed` shorthand (TrimBox = MediaBox inset), crop/registration marks outside the TrimBox, /UserUnit for large formats (PDF 1.7; not under pdfa1b), `spotColours` ink declarations. See docs/guides/PRINT.md. | ||
| title | Yes | Document title. Used as the PDF metadata title and rendered at the top of page 1. | |
| blocks | No | Optional document body blocks rendered before the signature field. | |
| reason | No | Reason for signing (e.g. "Approved", "I agree to the terms"). | |
| strict | No | Fail instead of producing a file the engine warns about: a PDFA_* diagnostic → PDF_A_COMPLIANCE_VIOLATION (e.g. PDFA_NO_FONT_ENTRIES without embedFonts), a PDFX_* one → PDF_X_COMPLIANCE_VIOLATION, any other (TYPOGRAPHY_FEATURE_INEFFECTIVE, TEXT_GLYPH_NOT_COVERED — a character no font covers, drawn as a box or '?') → DIAGNOSTIC_ESCALATED. Pair with embedFonts=true. | |
| margins | No | Margins in points, all four required (0–200). Default 45 / 36 / 35 / 36. | |
| compress | No | FlateDecode the streams (smaller file, different bytes; PDF/A unaffected, XMP stays plain). Default false. | |
| location | No | Signing location (city / country). | |
| metadata | No | /Info (+ XMP under PDF/A): author, subject, keywords, /Trapped. | |
| pageSize | No | Portrait page preset (points): A4 595.28×841.89 (default), Letter 612×792, Legal 612×1008, A3 841.89×1190.55, Tabloid 792×1224. print.* boxes must fit it. | |
| direction | No | Base text direction (UAX #9): 'auto' reads each paragraph's first strong character and right-aligns RTL ones; 'ltr' / 'rtl' force it. A paragraph's own direction overrides it. Omitted = LTR (1.7.0 bytes). | |
| fieldName | No | Optional AcroForm field name for the signature widget (default 'Signature1'). | |
| pageIndex | No | Zero-based page index the (invisible) widget attaches to (default 0). | |
| subFilter | No | Signature SubFilter baked into the /Sig dictionary (frozen at placeholder time). Use 'ETSI.CAdES.detached' for PAdES baseline signatures (sign_pdf profile='pades'). Default 'adbe.pkcs7.detached'. | |
| actualText | No | Untagged output: wrap reordered shaped runs and RTL runs in /ActualText so extract_text returns reading order. Default true; false = bare 1.7.0 glyph runs. No effect on tagged (pdfA) output. | |
| embedFonts | No | Embed Noto Sans Latin instead of the viewer base-14 Helvetica. REQUIRED for a valid PDF/A or PDF/X claim (every font embedded) and for strict=true; adds ~0.3 MiB. | |
| outputMode | No | Either 'base64' (returns the PDF inline) or 'file' (writes to a sandboxed path inside PDFNATIVE_MCP_OUTPUT_DIR). | base64 |
| outputPath | No | Required when outputMode='file'. Relative path inside the sandbox; must end with .pdf. | |
| signerName | No | Name of the intended signer, embedded in the /Sig dictionary. | |
| typography | No | Fine typography, all opt-in (omitted = unchanged bytes). kerning and fontFeatures need embedFonts:true ('fr' works on base-14 too). No hyphenation dictionary is installed: use soft hyphens (U+00AD). See the typography prompt. | |
| contactInfo | No | Contact information for the signer. | |
| signingTime | No | /Sig /M — the claimed signing instant (ISO-8601), frozen into the placeholder dictionary. Omitted: the wall clock at placeholder time. Pin it (with creationDate) for byte-identical output across calls. | |
| creationDate | No | ISO-8601 instant for /CreationDate (+ XMP, the trailer /ID and the {date} placeholder), written in UTC. Pin it for byte-identical output across calls and hosts; omitted = wall clock, so every call differs. | |
| outputIntent | No | Custom OutputIntent (under pdfA or pdfx): an RGB, CMYK or Gray ICC profile + condition strings, replacing the built-in sRGB intent. The profile must be a real ICC file ('acsp' signature, consistent size — PRINT_ERROR otherwise); pdfx needs device class 'prtr'. Under a CMYK / Gray intent RGB content is mapped through a calibrated default space. | |
| footerTemplate | No | Running footer on every page. Replaces the default footer: footerText is then ignored and page numbers appear only via {page}/{pages}. | |
| headerTemplate | No | Running header on every page (left / center / right zones); reserves 15 pt. | |
| placeholderBytes | No | Reserved bytes for the future CMS /Contents blob (default 16384; 24576 when reserveTimestamp=true). Increase only for >4096-bit RSA, long chains or large TSA tokens. | |
| reserveTimestamp | No | Reserve room for an RFC 3161 signature timestamp (sign_pdf timestamp=true): adds 8 KiB to the default placeholder size. Ignored when placeholderBytes is set explicitly. | |
| includeDiagnostics | No | Return the diagnostics raised while building (PDFA_*, PDFX_*, TYPOGRAPHY_*, TEXT_GLYPH_NOT_COVERED) as `diagnostics[]` (possibly empty). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public URL of the file (file mode, only when PDFNATIVE_MCP_OUTPUT_BASE_URL is set): base URL + sandbox-relative path, percent-encoded. | |
| mode | Yes | ||
| summary | No | Tool-specific summary, when produced. | |
| filePath | No | Sandboxed absolute path (file mode). | |
| sizeBytes | Yes | ||
| diagnostics | No | Engine diagnostics (when includeDiagnostics=true). |