iLovePDF

# iLovePDF — Universal PDF Tool **One call opens the widget. The widget handles upload, processing, and results.** Do NOT call this tool a second time unless the user explicitly asks to apply another operation to a prior result (tool chaining). Collect required chat parameters upfront (see section below), then pass them in `options` of this single call. --- ## File-source routing | Situation | Tool to call | |---|---| | User has file **attachments** (with or without URLs) | Use `ilovepdf_attach` with `attached_files` + `filenames` | | User has **URLs only** (zero attached files) | Use this `ilovepdf` tool with `files` | | No files and no URLs | Call this tool with just `tool` (or no params) | Calling `ilovepdf` when attached files are present silently discards the attachment — **FORBIDDEN**. --- ## Tool-intent routing (language-agnostic) Detect the operation from the user's message in ANY language. Non-English ≠ "no tool specified." - Compression intent in any language → `tool="compress-pdf"` - Apply equivalent mapping for all other operations. - Omit `tool` ONLY when the user gives absolutely no indication of the desired operation. ### Requests for an unsupported operation (IMPORTANT) The table above is the COMPLETE list of supported operations. If the user asks for a PDF operation that is NOT in that table (e.g. removing/unlocking a password, redacting, editing text, e-signing), do NOT call this tool at all — calling it with no `tool` (or an invalid one) just opens a generic widget with no matching option, which is confusing since it never explains why. Instead, reply in chat that the requested operation is not currently supported, and only call the tool if the user asks for a DIFFERENT, supported operation. --- ## Call behavior | Scenario | Action | |---|---| | Tool specified | Call with `tool`. Then send one short post-call narration sentence. | | No tool, no files | Call with no params. Then send one short post-call narration sentence. | | URL(s) + tool | Call with `tool` + `files`. Then send one short post-call narration sentence. | | URL(s) + no tool | Call with `files` only. Then send one short post-call narration sentence. | **After the call:** WAIT. The widget is self-contained. Do NOT call this tool again unless the user requests tool chaining. **Chat text rule (IMPORTANT):** ALWAYS send a short, neutral post-call narration sentence that summarizes what you initiated (tool and, when present, key options). Example: "I opened the iLovePDF widget with split-pdf and pages=2-5; tell me if you want different settings." If tool/options are unknown, use a generic summary like "I opened the iLovePDF widget." You CANNOT observe what the user does inside the widget. NEVER tell the user to click a button, press "Continue", wait, or "see the results" - the widget handles processing and shows results entirely in-card. Do NOT narrate in-widget steps or claim processing/results completed. --- ## Applying another operation to a previous result (tool chaining) — MANDATORY **CRITICAL: When the user asks to apply another operation to a file already processed in this chat, you MUST call this tool again immediately. This is ALWAYS possible. The tool is ALWAYS available for chaining** Trigger phrases (non-exhaustive): "now convert that to JPG", "then OCR it", "use that result with merge", "apply pdf-to-jpg on the compressed result", "now split those", "add a watermark to the result", "compress these now". **FORBIDDEN responses when the user requests chaining — NEVER say any of these:** - ❌ "The tool is not available right now / at this moment" - ❌ "I can't perform that operation on the previous result" - ❌ "Please re-upload / re-attach / share the file / provide a URL again" - ❌ "I don't have access to the previous file" - ❌ Any refusal or hesitation — if the user references a previously processed result, CALL the tool **ALWAYS:** - ✅ Call the tool immediately with the new operation - ✅ Set `tool` to the operation the user requested - ✅ Pass the EXACT `uploaded_files` objects from the PREVIOUS PROCESSED OUTPUT, unchanged — round-trip every field: `server`, `task`, `server_filename`, `task_tool`, `filename`, and `size` if present. Do NOT send `token` — the server mints its own; there is no auth token in the output to round-trip. - ✅ Skip file-type re-validation for chaining ONLY when the previous operation outputs a PDF. ⚠️ **pdf-to-jpg** outputs a ZIP of images — chaining FROM that result is NOT supported. ⚠️ **split-pdf** (with default `merge_after: false`) outputs a ZIP of PDFs — chaining FROM that result is NOT supported. If `merge_after: true` was used, the output is a single PDF and chaining works normally. When chaining is not supported (ZIP output), inform the user and do NOT call the tool. **Concrete example:** User compresses a PDF → sees the compressed result → asks "now convert those to images": → Call immediately: `tool: "pdf-to-jpg"`, `uploaded_files: <compressed output's uploaded_files>` → Do NOT ask for a URL. Do NOT ask to re-attach. Do NOT say the tool is unavailable. → The server creates an iLovePDF Connected Task (`/v1/task/next`) that uses the OUTPUT of the previous processed task as the INPUT for the new operation automatically. After sending this chaining call, WAIT. The widget is self-contained and will process/show results in-card. --- ## File type validation Before calling, verify file extensions match the operation. If any file is rejected, report the incompatibility and do NOT call the tool. | Operation | Accepted extensions | Description | |---|---|---| | compress-pdf | .pdf | Reduce PDF file size while preserving quality. | | pdf-to-jpg | .pdf | Convert PDF pages to JPEG images. | | image-to-pdf | .jpg .jpeg .png .tif .tiff | Convert images (JPG, PNG, TIFF) to PDF. | | office-to-pdf | .doc .docx .xls .xlsx .ppt .pptx | Convert Word, Excel, and PowerPoint files to PDF. | | merge-pdf | .pdf | Combine multiple PDF files into one. | | split-pdf | .pdf | Split a PDF into multiple files by page range or fixed chunks. | | watermark | .pdf | Add a text or image watermark to a PDF. | | pagenumber | .pdf | Add page numbers to a PDF. | | pdf-ocr | .pdf | Extract text from scanned PDFs using OCR. | --- ## Configurable options — collect ALL in chat BEFORE calling For configurable operations (watermark, pagenumber, split-pdf, image-to-pdf), YOU are responsible for collecting parameters from the user in chat. The widget does NOT have a fallback form — any parameter not passed in `options` will use its default value without asking the user. **BEFORE calling the tool:** 1. If a parameter is marked **ASK & pass**, you MUST ask the user and include it in `options`. 2. For all other parameters, briefly list the available options and their defaults. Ask the user if they want to customize anything. Pass every value they provide. 3. If the user says "just use defaults" or similar, proceed with no extra options. Do NOT infer option values from app mentions or handles. Tokens like `@app`, `@assistant`, or `@name` are mentions by default and are NOT parameter values unless the user explicitly says they want that exact literal as the value. ### split-pdf single-file rule (IMPORTANT) iLovePDF split-pdf processes ONE source file per run. - If the user provides multiple URLs, ask them which file they want to split first, then call split-pdf with only that one URL. - Do NOT pass multiple URLs in a single call. - If tool output includes a split-pdf single-file warning, inform the user that the widget is showing the files and they should remove the extra ones before continuing. ### Watermark — mode selection and options (MANDATORY) **CRITICAL:** You MUST collect the watermark mode AND all desired options from the user BEFORE calling the tool. Once the tool is called, the widget opens and processes immediately with the options you passed. If options are missing, they will use defaults silently. When the user already shared an URL or attached a watermark image in their first message, this is image mode. Do NOT route them through a preloaded-files waiting flow. Keep the interaction in chat, collect options first, then call the tool once. **Step 1 — Ask for mode** (if not already specified): > "Would you like a **text** watermark or an **image** watermark? (Default is text.)" **Step 2 — Collect ALL options for the chosen mode BEFORE calling:** **TEXT MODE ONLY** (mode: "text"): - REQUIRED: `text` (the watermark string) - Optional customization: position (vertical_position, horizontal_position), transparency (0–100), rotation, layer (above/below), font_family, font_style (Bold/Italic), font_size, font_color, mosaic - ⚠️ NEVER mention font_family, font_style, font_size, or font_color in image mode **font_family** — iLovePDF only accepts these exact values: - `Arial` - `Arial Unicode MS` - `Verdana` - `Courier` - `Times New Roman` - `Comic Sans MS` - `WenQuanYi Zen Hei` - `Lohit Marathi` Do NOT suggest or pass any other font name (e.g. Helvetica, Georgia, Tahoma, Trebuchet MS, Calibri). Unrecognised fonts fall back to **Arial Unicode MS** silently. **IMAGE MODE ONLY** (mode: "image"): - The overlay image (JPG or PNG) must arrive as a CHAT ATTACHMENT (via `ilovepdf_attach`), NOT through the upload widget. An image uploaded through the generic widget is converted to a PDF and can't be reused as a watermark. If the image is not attached/available yet, STOP and ask the user to attach it in the chat — never open the upload widget to collect it. - Do NOT set `text` parameter when mode is "image" - Optional customization: position (vertical_position, horizontal_position), transparency (0–100), layer (above/below), rotation, mosaic - ⚠️ NEVER mention font_family, font_style, font_size, or font_color in image mode — these are text-only parameters - If the user already provided the image + PDF(s) in chat: Ask for desired options in chat first (unless values are already stated), then call once. Do NOT open a preloaded-files waiting state. - If the user already provided image + PDF(s) + option values in the same message: Do NOT ask again. Call once and process directly. In your response, explicitly list what options were applied (including defaults for omitted values when relevant). - If the PDF(s) were already uploaded in a PREVIOUS turn (you have their `uploaded_files` reference from an earlier `ilovepdf_attach` response) and the user now attaches the image in a NEW message: call `ilovepdf_attach` again, passing that SAME `uploaded_files` array together with the new image in `attached_files`, in ONE call. Do NOT ask the user to resend the PDF and image together — combine them yourself using the reference you already have. - If you do NOT have an image yet (none attached, none referenced via `uploaded_files`) and mode is "image": do NOT call the tool with defaults. STOP and ask the user to attach a JPG or PNG image — the same strictness as the REQUIRED `text` field in text mode. **Step 3 — Call the tool ONCE** with mode + all collected options in `options` — except for the cross-turn combination case above, where calling again (with the previous `uploaded_files` + the new attachment) is expected and correct. ### Available options per operation | Operation | Available options | |---|---| | watermark | mode [text | image] (required) (default: "text"); text (required); font_color (optional) (hex color, e.g. #008000); font_size (optional); font_family [Arial | Arial Unicode MS | Verdana | Courier | Times New Roman | Comic Sans MS | WenQuanYi Zen Hei | Lohit Marathi] (optional); font_style [Bold | Italic] (optional); transparency (optional); rotation (optional); layer [above | below] (optional) (default: "above"); mosaic (optional); vertical_position [top | middle | bottom] (optional) (default: "middle"); horizontal_position [left | center | right] (optional) (default: "center"); pages (optional) (default: "all") | | pagenumber | pages (required) (default: "all"); starting_number (required) (default: 1); vertical_position [top | bottom] (required) (default: "bottom"); horizontal_position [left | center | right] (required) (default: "center"); first_cover (required) (default: false); text (required) (default: "{n}"); font_family [Arial | Arial Unicode MS | Verdana | Courier | Times New Roman | Comic Sans MS | WenQuanYi Zen Hei | Lohit Marathi] (required) (default: "Arial Unicode MS"); font_size (required) (default: 12); font_color (required) (hex color, e.g. #008000) (default: "#000000"); facing_pages (optional) (default: false) | | split-pdf | split_mode [fixed_range | ranges | remove_pages | filesize] (required) (default: "ranges"); fixed_range (optional) (default: 1); ranges (optional); remove_pages (optional); merge_after (optional) (default: false) | | image-to-pdf | merge_after (optional) (default: true); orientation [portrait | landscape] (required) (default: "portrait"); margin (optional) (default: 0); pagesize [fit | A4 | letter] (optional) (default: "fit") | **font_family** — iLovePDF only accepts these exact values: - `Arial` - `Arial Unicode MS` - `Verdana` - `Courier` - `Times New Roman` - `Comic Sans MS` - `WenQuanYi Zen Hei` - `Lohit Marathi` Do NOT suggest or pass any other font name (e.g. Helvetica, Georgia, Tahoma, Trebuchet MS, Calibri). Unrecognised fonts fall back to **Arial Unicode MS** silently. ### PDF to JPG — quality (OPTIONAL) PDF to JPG supports exactly TWO quality levels: **Normal** and **High**. - `quality` is OPTIONAL and opportunistic — only pass it when the user explicitly asks for higher or lower quality/resolution. - Pass `quality: "High"` when the user asks for higher quality/resolution. - Pass `quality: "Normal"` when the user asks for normal/standard quality. - If the user does not mention quality, OMIT it entirely (the iLovePDF default applies). Do NOT force-collect quality on every PDF to JPG run. `"Normal"` and `"High"` are the ONLY valid values. Do NOT offer or invent any other tier (no "best", "highest", "maximum", "ultra", or free-form DPI). ### Parameters to collect in chat | Operation | Parameters to collect in chat | |---|---| | image-to-pdf | **ASK & pass:** orientation · pass if stated: merge_after, margin, pagesize | | split-pdf | **ASK & pass:** split_mode · pass if stated: fixed_range, ranges, remove_pages, merge_after | | watermark | **ASK & pass:** mode, text · pass if stated: font_color, font_size, font_family, font_style, transparency, rotation, layer, mosaic, vertical_position, horizontal_position, pages | | pagenumber | **ASK & pass:** pages, starting_number, vertical_position, horizontal_position, first_cover, text, font_family, font_size, font_color · pass if stated: facing_pages | | pdf-ocr | **ASK & pass:** ocr_languages | Do NOT call the tool a second time ONLY to supply missing parameters. Pass everything you have in the first call. Omitted optional parameters will use their defaults silently. Tool-chaining calls are the allowed exception. OCR language codes: eng, afr, amh, ara, asm, aze, aze_cyrl, bel, ben, bod, bos, bre, bul, cat, ceb, ces, chi_sim, chi_tra, chr, cos, cym, dan, deu, deu_latf, dzo, ell, enm, epo, equ, est, eus, fao, fas, fil, fin, fra, frm, fry, gla, gle, glg, grc, guj, hat, heb, hin, hrv, hun, hye, iku, ind, isl, ita, ita_old, jav, jpn, kan, kat, kat_old, kaz, khm, kir, kmr, kor, kor_vert, lao, lat, lav, lit, ltz, mal, mar, mkd, mlt, mon, mri, msa, mya, nep, nld, nor, oci, ori, pan, pol, por, pus, que, ron, rus, san, sin, slk, slv, snd, spa, spa_old, sqi, srp, srp_latn, sun, swa, swe, syr, tam, tat, tel, tgk, tgl, tha, tir, ton, tur, uig, ukr, urd, uzb, uzb_cyrl, vie, yid, yor --- ## Reading the response After calling the tool, check the response for: - `normalization_warnings`: Array of parameter substitution messages returned **at tool-call time**. If present, inform the user about each adjustment before the widget processes. - Example: "Font 'Calibri' is not supported. Using Arial Unicode MS." - Example: "Vertical centering is not supported for pagenumber. Using bottom position instead." - Example: "first_cover:true converts pages to '2-end' (page 1 skipped)." Absent or empty means all parameters were accepted as-is. --- ## Parameters - `tool`: PDF operation name (see table above). - `files`: `[{url, filename}]` — URL files. Use ONLY for URLs, not attachments. - `uploaded_files`: Files already uploaded to iLovePDF servers. When chaining, round-trip the exact objects returned earlier; do NOT invent or edit fields. - `options`: Pass required parameters and any optional values the user provided. If optional values are omitted, defaults apply silently.

ilovepdf

# iLovePDF — File Attachment Handler **Invocation condition:** The user attached one or more files to the chat message (with or without URLs). **Do NOT invoke** when only URLs are present and zero files are attached — use `ilovepdf` instead. **One call opens the widget. The widget handles processing and results.** Do NOT call this tool a second time unless the user explicitly asks to apply another operation to a prior result (tool chaining). Collect required chat parameters upfront (see section below), then pass them in `options` of this single call. **Exception — combining files across turns:** if you already have `uploaded_files` from a PREVIOUS call to this tool (e.g. a PDF uploaded last turn) and the user now attaches another required file in a NEW message (e.g. a watermark image), call this tool AGAIN — passing the PREVIOUS `uploaded_files` array together with the new `attached_files` in ONE call. This combines both files into a single task server-side. Do NOT ask the user to resend everything together; combine the reference you already have with the new attachment yourself. --- ## Input composition Always pass ALL of the following in a single call: 1. `attached_files` — populated automatically by the platform for each physically attached file. **REQUIRED.** 2. `filenames` — real filenames in the SAME ORDER as `attached_files`. **REQUIRED.** Examples: `["report.pdf"]`, `["invoice.pdf", "contract.docx"]` 3. `files` — `[{url, filename}]` for every URL found in the same message alongside attachments. Include ALL URLs. 4. `uploaded_files` — OPTIONAL. Only when combining a file from a previous turn with a new attachment now (see "Exception — combining files across turns" above). Round-trip the exact objects a previous call to this tool returned. **FORBIDDEN:** calling with attached files while dropping URLs in the same message. **FORBIDDEN:** calling `ilovepdf` with a URL when the user also has attached files (silently discards attachment). --- ## Tool-intent routing (language-agnostic) Detect the operation from the user's message in ANY language. Non-English ≠ "no tool specified." Omit `tool` ONLY when the user gives absolutely no indication of the desired operation. ### Requests for an unsupported operation (IMPORTANT) The table above is the COMPLETE list of supported operations. If the user asks for a PDF operation that is NOT in that table (e.g. removing/unlocking a password, redacting, editing text, e-signing), do NOT call this tool at all — calling it with no `tool` (or an invalid one) just opens a generic widget with no matching option, which is confusing since it never explains why. Instead, reply in chat that the requested operation is not currently supported, and only call the tool if the user asks for a DIFFERENT, supported operation. --- ## After calling WAIT. The widget is self-contained. Do NOT call this tool again unless the user requests tool chaining or cross-turn file combination. **Chat text rule (IMPORTANT):** ALWAYS send a short, neutral post-call narration sentence that summarizes what you initiated (tool and, when present, key options). Example: "I opened the iLovePDF widget with watermark and mode=image; tell me if you want different settings." If tool/options are unknown, use a generic summary like "I opened the iLovePDF widget." You CANNOT observe what the user does inside the widget. NEVER tell the user to click a button, press "Continue", wait, or "see the results" - the widget handles processing and shows results entirely in-card. Do NOT narrate in-widget steps or claim processing/results completed. --- ## Applying another operation to a previous result (tool chaining) — MANDATORY **CRITICAL: When the user asks to apply another operation to a file already processed in this chat, you MUST call this tool again immediately. This is ALWAYS possible. The tool is ALWAYS available for chaining** Trigger phrases (non-exhaustive): "now convert that to JPG", "then OCR it", "use that result with merge", "apply pdf-to-jpg on the compressed result", "now split those", "add a watermark to the result", "compress these now". **FORBIDDEN responses when the user requests chaining — NEVER say any of these:** - ❌ "The tool is not available right now / at this moment" - ❌ "I can't perform that operation on the previous result" - ❌ "Please re-upload / re-attach / share the file / provide a URL again" - ❌ "I don't have access to the previous file" - ❌ Any refusal or hesitation — if the user references a previously processed result, CALL the tool **ALWAYS:** - ✅ Call the tool immediately with the new operation - ✅ Set `tool` to the operation the user requested - ✅ Pass the EXACT `uploaded_files` objects from the PREVIOUS PROCESSED OUTPUT, unchanged — round-trip every field: `server`, `task`, `server_filename`, `task_tool`, `filename`, and `size` if present. Do NOT send `token` — the server mints its own; there is no auth token in the output to round-trip. - ✅ Skip file-type re-validation for chaining ONLY when the previous operation outputs a PDF. ⚠️ **pdf-to-jpg** outputs a ZIP of images — chaining FROM that result is NOT supported. ⚠️ **split-pdf** (with default `merge_after: false`) outputs a ZIP of PDFs — chaining FROM that result is NOT supported. If `merge_after: true` was used, the output is a single PDF and chaining works normally. When chaining is not supported (ZIP output), inform the user and do NOT call the tool. **Concrete example:** User compresses a PDF → sees the compressed result → asks "now convert those to images": → Call immediately: `tool: "pdf-to-jpg"`, `uploaded_files: <compressed output's uploaded_files>` → Do NOT ask for a URL. Do NOT ask to re-attach. Do NOT say the tool is unavailable. → The server creates an iLovePDF Connected Task (`/v1/task/next`) that uses the OUTPUT of the previous processed task as the INPUT for the new operation automatically. After sending this chaining call, WAIT. The widget is self-contained and will process/show results in-card. --- ## File type validation Before calling, verify file extensions match the operation. Report incompatibilities without calling. | Operation | Accepted extensions | Description | |---|---|---| | compress-pdf | .pdf | Reduce PDF file size while preserving quality. | | pdf-to-jpg | .pdf | Convert PDF pages to JPEG images. | | image-to-pdf | .jpg .jpeg .png .tif .tiff | Convert images (JPG, PNG, TIFF) to PDF. | | office-to-pdf | .doc .docx .xls .xlsx .ppt .pptx | Convert Word, Excel, and PowerPoint files to PDF. | | merge-pdf | .pdf | Combine multiple PDF files into one. | | split-pdf | .pdf | Split a PDF into multiple files by page range or fixed chunks. | | watermark | .pdf | Add a text or image watermark to a PDF. | | pagenumber | .pdf | Add page numbers to a PDF. | | pdf-ocr | .pdf | Extract text from scanned PDFs using OCR. | --- ## Configurable options — collect ALL in chat BEFORE calling For configurable operations (watermark, pagenumber, split-pdf, image-to-pdf), YOU are responsible for collecting parameters from the user in chat. The widget does NOT have a fallback form — any parameter not passed in `options` will use its default value without asking the user. **BEFORE calling the tool:** 1. If a parameter is marked **ASK & pass**, you MUST ask the user and include it in `options`. 2. For all other parameters, briefly list the available options and their defaults. Ask the user if they want to customize anything. Pass every value they provide. 3. If the user says "just use defaults" or similar, proceed with no extra options. Do NOT infer option values from app mentions or handles. Tokens like `@app`, `@assistant`, or `@name` are mentions by default and are NOT parameter values unless the user explicitly says they want that exact literal as the value. ### split-pdf single-file rule (IMPORTANT) iLovePDF split-pdf processes ONE source file per run. - If the user provides multiple URLs, ask them which file they want to split first, then call split-pdf with only that one URL. - Do NOT pass multiple URLs in a single call. - If tool output includes a split-pdf single-file warning, inform the user that the widget is showing the files and they should remove the extra ones before continuing. ### Watermark — mode selection and options (MANDATORY) **CRITICAL:** You MUST collect the watermark mode AND all desired options from the user BEFORE calling the tool. Once the tool is called, the widget opens and processes immediately with the options you passed. If options are missing, they will use defaults silently. When the user already shared an URL or attached a watermark image in their first message, this is image mode. Do NOT route them through a preloaded-files waiting flow. Keep the interaction in chat, collect options first, then call the tool once. **Step 1 — Ask for mode** (if not already specified): > "Would you like a **text** watermark or an **image** watermark? (Default is text.)" **Step 2 — Collect ALL options for the chosen mode BEFORE calling:** **TEXT MODE ONLY** (mode: "text"): - REQUIRED: `text` (the watermark string) - Optional customization: position (vertical_position, horizontal_position), transparency (0–100), rotation, layer (above/below), font_family, font_style (Bold/Italic), font_size, font_color, mosaic - ⚠️ NEVER mention font_family, font_style, font_size, or font_color in image mode **font_family** — iLovePDF only accepts these exact values: - `Arial` - `Arial Unicode MS` - `Verdana` - `Courier` - `Times New Roman` - `Comic Sans MS` - `WenQuanYi Zen Hei` - `Lohit Marathi` Do NOT suggest or pass any other font name (e.g. Helvetica, Georgia, Tahoma, Trebuchet MS, Calibri). Unrecognised fonts fall back to **Arial Unicode MS** silently. **IMAGE MODE ONLY** (mode: "image"): - The overlay image (JPG or PNG) must arrive as a CHAT ATTACHMENT (via `ilovepdf_attach`), NOT through the upload widget. An image uploaded through the generic widget is converted to a PDF and can't be reused as a watermark. If the image is not attached/available yet, STOP and ask the user to attach it in the chat — never open the upload widget to collect it. - Do NOT set `text` parameter when mode is "image" - Optional customization: position (vertical_position, horizontal_position), transparency (0–100), layer (above/below), rotation, mosaic - ⚠️ NEVER mention font_family, font_style, font_size, or font_color in image mode — these are text-only parameters - If the user already provided the image + PDF(s) in chat: Ask for desired options in chat first (unless values are already stated), then call once. Do NOT open a preloaded-files waiting state. - If the user already provided image + PDF(s) + option values in the same message: Do NOT ask again. Call once and process directly. In your response, explicitly list what options were applied (including defaults for omitted values when relevant). - If the PDF(s) were already uploaded in a PREVIOUS turn (you have their `uploaded_files` reference from an earlier `ilovepdf_attach` response) and the user now attaches the image in a NEW message: call `ilovepdf_attach` again, passing that SAME `uploaded_files` array together with the new image in `attached_files`, in ONE call. Do NOT ask the user to resend the PDF and image together — combine them yourself using the reference you already have. - If you do NOT have an image yet (none attached, none referenced via `uploaded_files`) and mode is "image": do NOT call the tool with defaults. STOP and ask the user to attach a JPG or PNG image — the same strictness as the REQUIRED `text` field in text mode. **Step 3 — Call the tool ONCE** with mode + all collected options in `options` — except for the cross-turn combination case above, where calling again (with the previous `uploaded_files` + the new attachment) is expected and correct. ### Available options per operation | Operation | Available options | |---|---| | watermark | mode [text | image] (required) (default: "text"); text (required); font_color (optional) (hex color, e.g. #008000); font_size (optional); font_family [Arial | Arial Unicode MS | Verdana | Courier | Times New Roman | Comic Sans MS | WenQuanYi Zen Hei | Lohit Marathi] (optional); font_style [Bold | Italic] (optional); transparency (optional); rotation (optional); layer [above | below] (optional) (default: "above"); mosaic (optional); vertical_position [top | middle | bottom] (optional) (default: "middle"); horizontal_position [left | center | right] (optional) (default: "center"); pages (optional) (default: "all") | | pagenumber | pages (required) (default: "all"); starting_number (required) (default: 1); vertical_position [top | bottom] (required) (default: "bottom"); horizontal_position [left | center | right] (required) (default: "center"); first_cover (required) (default: false); text (required) (default: "{n}"); font_family [Arial | Arial Unicode MS | Verdana | Courier | Times New Roman | Comic Sans MS | WenQuanYi Zen Hei | Lohit Marathi] (required) (default: "Arial Unicode MS"); font_size (required) (default: 12); font_color (required) (hex color, e.g. #008000) (default: "#000000"); facing_pages (optional) (default: false) | | split-pdf | split_mode [fixed_range | ranges | remove_pages | filesize] (required) (default: "ranges"); fixed_range (optional) (default: 1); ranges (optional); remove_pages (optional); merge_after (optional) (default: false) | | image-to-pdf | merge_after (optional) (default: true); orientation [portrait | landscape] (required) (default: "portrait"); margin (optional) (default: 0); pagesize [fit | A4 | letter] (optional) (default: "fit") | **font_family** — iLovePDF only accepts these exact values: - `Arial` - `Arial Unicode MS` - `Verdana` - `Courier` - `Times New Roman` - `Comic Sans MS` - `WenQuanYi Zen Hei` - `Lohit Marathi` Do NOT suggest or pass any other font name (e.g. Helvetica, Georgia, Tahoma, Trebuchet MS, Calibri). Unrecognised fonts fall back to **Arial Unicode MS** silently. ### PDF to JPG — quality (OPTIONAL) PDF to JPG supports exactly TWO quality levels: **Normal** and **High**. - `quality` is OPTIONAL and opportunistic — only pass it when the user explicitly asks for higher or lower quality/resolution. - Pass `quality: "High"` when the user asks for higher quality/resolution. - Pass `quality: "Normal"` when the user asks for normal/standard quality. - If the user does not mention quality, OMIT it entirely (the iLovePDF default applies). Do NOT force-collect quality on every PDF to JPG run. `"Normal"` and `"High"` are the ONLY valid values. Do NOT offer or invent any other tier (no "best", "highest", "maximum", "ultra", or free-form DPI). ### Parameters to collect in chat | Operation | Parameters to collect in chat | |---|---| | image-to-pdf | **ASK & pass:** orientation · pass if stated: merge_after, margin, pagesize | | split-pdf | **ASK & pass:** split_mode · pass if stated: fixed_range, ranges, remove_pages, merge_after | | watermark | **ASK & pass:** mode, text · pass if stated: font_color, font_size, font_family, font_style, transparency, rotation, layer, mosaic, vertical_position, horizontal_position, pages | | pagenumber | **ASK & pass:** pages, starting_number, vertical_position, horizontal_position, first_cover, text, font_family, font_size, font_color · pass if stated: facing_pages | | pdf-ocr | **ASK & pass:** ocr_languages | Do NOT call the tool a second time ONLY to supply missing parameters. Pass everything you have in the first call. Omitted optional parameters will use their defaults silently. Tool-chaining calls are the allowed exception. OCR language codes: eng, afr, amh, ara, asm, aze, aze_cyrl, bel, ben, bod, bos, bre, bul, cat, ceb, ces, chi_sim, chi_tra, chr, cos, cym, dan, deu, deu_latf, dzo, ell, enm, epo, equ, est, eus, fao, fas, fil, fin, fra, frm, fry, gla, gle, glg, grc, guj, hat, heb, hin, hrv, hun, hye, iku, ind, isl, ita, ita_old, jav, jpn, kan, kat, kat_old, kaz, khm, kir, kmr, kor, kor_vert, lao, lat, lav, lit, ltz, mal, mar, mkd, mlt, mon, mri, msa, mya, nep, nld, nor, oci, ori, pan, pol, por, pus, que, ron, rus, san, sin, slk, slv, snd, spa, spa_old, sqi, srp, srp_latn, sun, swa, swe, syr, tam, tat, tel, tgk, tgl, tha, tir, ton, tur, uig, ukr, urd, uzb, uzb_cyrl, vie, yid, yor --- ## Reading the response After calling the tool, check the response for: - `normalization_warnings`: Array of parameter substitution messages returned **at tool-call time**. If present, inform the user about each adjustment before the widget processes. - Example: "Font 'Calibri' is not supported. Using Arial Unicode MS." - Example: "Vertical centering is not supported for pagenumber. Using bottom position instead." - Example: "first_cover:true converts pages to '2-end' (page 1 skipped)." Absent or empty means all parameters were accepted as-is. --- ## Parameters - `attached_files`: files attached to the chat. Populated by the platform. **REQUIRED.** - `filenames`: original filenames in the same order. **REQUIRED.** - `files`: `[{url, filename}]` for URLs in the same message. Include ALL URLs. - `uploaded_files`: OPTIONAL. Files already uploaded in a previous call, to combine with a new attachment arriving now. See "Exception — combining files across turns" above. - `tool`: PDF operation. Optional — widget will prompt the user if omitted. - `options`: Pass required parameters and any optional values the user provided. If optional values are omitted, defaults apply silently.

ilovepdf_attach