What this machine can do right now: routes, GUI session, installed apps, Keynote slide-op status. Call first when unsure. Call first when unsure what this machine can do: which apps exist, whether a GUI session is available, which toolsets are loaded. Not needed before plain reads of .numbers or .key files.

Read a .numbers, .key or .pages file into JSON (.pages needs the Pages app and a GUI session). Use to see a file's content before editing it. Not for formatting details: use numbers_inspect_format (Numbers) or keynote_inspect_style (Keynote). For file facts only, iwork_metadata is cheaper.

List the versioned backups (newest first) every write left for this file, plus the Keynote write manifest. Use when the user wants to undo or compare versions: it lists the backups, then iwork_restore_backup restores one. Not needed after a failed tool call: failed writes never change the file.

Check Pages can answer AppleEvents. Run once before any Pages op; never loop on failure. Call once before other Pages tools. A -1712 error means a dialog in Pages needs a human; don't retry until it's dismissed.

Independent check of formatting: export a PDF through the app and confirm text is drawn with the given font (name contains), size (pt), color (#RRGGBB), bold, and page size (pt). Needs macOS + the app. Use to prove how a piece of text is drawn (font, size, colour, page size). To check text is merely present use iwork_verify_render.

Export the file to PDF through its app and assert assert_text is visibly rendered. For Arabic, use one word. Use after an important write to prove the text really shows when rendered. To check font, size or colour use iwork_verify_format; to check a deck's whole design use keynote_review_deck.

Set one cell (e.g. ref "B2") in a .numbers file. Backed up, verified, atomic; every other cell is checked unchanged. dry_run=true previews the change on a copy without touching the file. Use to set one value. For a formula use numbers_set_formula; to add whole rows use numbers_insert with values; for how a number displays use numbers_set_number_format.

Current formatting of a Numbers table: column widths, row heights, header rows/cols, merges, and per-cell font/colour/fill/alignment, number format (shown_as) and borders. Read this before formatting. Use before formatting to see current styles, number formats, sizes, headers and merges. For values use iwork_read.

Set column widths and/or row heights in points, e.g. columns={"A": 160, "C": 90}, rows={"1": 32} (rows are 1-based). Nothing else changes. dry_run=true previews the change on a copy without touching the file. Use for column widths and row heights. To change which rows count as headers use numbers_set_headers.

How numbers display in a range ("B2:B9"): format = number | currency | percentage | scientific | fraction | datetime | text. Options: decimal_places, thousands_separator, negative_style (minus|red|parentheses|red_parentheses), currency_code (ISO, e.g. SAR, USD), accounting, date_format (e.g. "d MMM yyyy"). Values are not changed; the result shows how each cell now displays. dry_run=true previews the change on a copy without touching the file. Use for how numbers display (currency, %, dates, decimals); the values don't change. For fonts and colours use numbers_set_cell_style.

Style a range ("A1:D1"): font_name, font_size, bold, italic, underline, strikethrough, font_color / fill_color as "#RRGGBB", align (left|center|right|justify|auto), valign (top|middle|bottom), wrap. Only the attributes you pass change; every other cell is verified untouched. dry_run=true previews the change on a copy without touching the file. Use for fonts, colours, fill or alignment on a few cells. For a whole table that should look designed use numbers_apply_design; for how numbers display use numbers_set_number_format.

Cell borders on a range: sides = all | outline | inner | top | right | bottom | left; width in points; color "#RRGGBB"; style = solid | dashes | dots | none. dry_run=true previews the change on a copy without touching the file. Use for lines around or inside a range. For fills and fonts use numbers_set_cell_style.

Set how many header rows / header columns a table has (0–5). dry_run=true previews the change on a copy without touching the file. Use when the user wants a different number of header rows or columns, e.g. to freeze a title row on top for sorting and styling. Not for sizes (numbers_set_dimensions) or header colours (numbers_set_cell_style or numbers_apply_design).

Merge a rectangular range ("A1:C1"). Refused if any cell other than the top-left holds data (it would be hidden) or the range crosses the header edge. dry_run=true previews the change on a copy without touching the file. Use to merge a range, e.g. a title across columns. Refused if it would hide values; avoid merging inside data you will sort.

Find/replace text across every slide of a .key deck (literal unless regex=true). Formatting and structure are verified unchanged. dry_run=true previews the change on a copy without touching the file. Use to change the same text everywhere in a deck (names, dates, numbers). To rewrite one slide's title or body use keynote_set_slide_text.

Replace every occurrence of find in a .pages body (needs Pages + GUI session). Rolled back if the readback disagrees. dry_run=true previews the change on a copy without touching the file. Use to change text everywhere while keeping formatting. To replace the whole body use pages_set_body; for template fields use pages_fill_placeholders.

Replace the entire body text of a .pages document (needs Pages + GUI session). Body formatting is reset. dry_run=true previews the change on a copy without touching the file. Use only to replace the entire body text; it resets body formatting, so warn the user. Prefer pages_replace_all or pages_fill_placeholders.

Undo: atomically restore a backup (a name from iwork_list_backups). The current version is backed up first. Use to undo a change, with a backup name from iwork_list_backups. The current version is backed up first, so a restore can itself be undone.

Insert a slide after slide number after (0 = first, omit = end). Every other slide is verified unchanged. dry_run=true previews the change on a copy without touching the file. Use for a new blank slide in an existing deck. To copy a slide use keynote_duplicate_slide; for a whole new deck use keynote_build_deck.

Duplicate slide number slide (1-based); the copy lands right after it. dry_run=true previews the change on a copy without touching the file. Use to copy an existing slide (layout and content). For a blank slide use keynote_add_slide.

Delete slide number slide (1-based). Recoverable with iwork_restore_backup. dry_run=true previews the change on a copy without touching the file. Use to remove a slide for good (the last slide can't be deleted). To keep it but hide it in the slideshow use keynote_skip_slide.

Move slide number slide so it ends up at position to (both 1-based). dry_run=true previews the change on a copy without touching the file. Use to reorder slides. To copy a slide to a new position, duplicate it first with keynote_duplicate_slide.

Hide (skipped=true) or show a slide in the slideshow. dry_run=true previews the change on a copy without touching the file. Use to hide or show a slide in the slideshow without deleting it. To remove it use keynote_delete_slide.

Set the presenter notes of slide number slide (1-based). Arabic-safe. dry_run=true previews the change on a copy without touching the file. Use for speaker notes on an existing slide. For a new deck, put notes in keynote_build_deck's outline instead.

Export to another format. Numbers: pdf | xlsx | csv. Pages: pdf | docx | epub | txt | rtf. Keynote: pdf | pptx | images | movie. Optional password (+hint) for pdf/xlsx/docx/pptx, image_quality (good|better|best), image_format for slide images (jpeg|png|tiff). Default output sits next to the source. The export is checked against the source with a second tool and the source is verified unchanged. Needs macOS + the app. Use to hand the result over in another format (PDF, Excel, Word, PowerPoint, images). Never export to docx/pptx/xlsx to edit and convert back: edit the iWork file directly.

What a file says about itself, without the app: kind, size, modified, template it was made from, app builds that saved it, file format version, slide count (Keynote), embedded media count. Use for file facts (template, app build, slide count) without reading content. For the content itself use iwork_read.

Extract the preview image stored in the file (first page/slide) to a JPEG and return its path — a quick look without opening the app. Reflects the app's last save. Use for a quick look at the stored first-page preview with no app. It reflects the last save in the app, not your latest edits: to see a slide as it renders now, use keynote_slide_image.

Find Numbers / Keynote / Pages files (newest first). kind: numbers | keynote | pages; name: part of the file name. Searches folder, else the allowed folders, else Documents/Desktop/Downloads. Uses Spotlight on macOS. Use when the user names a file loosely ("my sales deck") or you don't know its path; then read it with iwork_read. Not needed when you already have the path.

Design kits for good-looking decks and tables: font pairs (Latin + Arabic, bundled with macOS), contrast-checked palettes and a type scale. Lists the presets and the kits you saved (saved: true). Use with keynote_build_deck(kit=…), keynote_apply_design, numbers_apply_design. Custom kits: pass {"fonts": {...}, "colors": {...}}. Use before any styling to pick a kit, and to see the user's saved brand kits. Pass the name as kit= to keynote_build_deck, keynote_apply_design or numbers_apply_design.

Make a design kit from the user's own deck or table: heading and body fonts (Latin and Arabic) and the title, body and brand colours. .numbers reads the table's header and body styles (no app); .key reads every slide's title and body (needs macOS + Keynote). Parts the file doesn't show come from the nearest preset and are listed in notes. save=true with a name keeps it for reuse by name (contrast must pass). The file is never changed. Use when the user has a deck or table that already has their brand look. If they give colours and fonts directly use iwork_save_design_kit instead.

Save a design kit by name for reuse anywhere a kit is accepted. kit = {"fonts": {...}, "colors": {...}, "theme": "...", "background": "#RRGGBB"} (missing parts come from the "executive" preset, or from "base": ""), or a preset name to copy. Contrast is checked (4.5:1). Never replaces a saved kit unless overwrite=true; can't reuse a preset's name. Use when the user gives brand colours and fonts directly. To capture them from an existing file use iwork_extract_design_kit.

Delete a saved design kit (presets can't be deleted). Returns the kit's contents, so it can be saved again with iwork_save_design_kit. Use only when the user asks to remove a saved kit. To change a kit, save it again with overwrite=true instead.

Style a whole table from a design kit: header band (fill, bold, contrast-checked text), body font and colour (Arabic cells get the Arabic font), alternate-row banding, number columns right-aligned. Values never change; every other table is verified untouched. No app needed. dry_run=true previews the change on a copy without touching the file. Use to make a whole table look designed in one call (header band, fonts, banding, aligned numbers). For a few cells use numbers_set_cell_style. Preview with dry_run.

Built-in templates for Numbers or Pages, or themes for Keynote (app: numbers | pages | keynote). Needs macOS + the app. Use before iwork_create to get valid template or theme names. Not needed for iwork_create_from_template, which copies the user's own file.

Create a new .numbers file from data. sheets = [{"name": "Sales", "tables": [{"name": "Q1", "rows": [["Region", "Revenue"], ["Riyadh", 1200]], "header_rows": 1}]}]. Numbers stay numbers, text stays text exactly (Arabic included). Refuses to overwrite. No app needed. Use to make a new Numbers file when you have the rows. From a CSV file use numbers_import_csv; to add a table to an existing file use numbers_add_table.

Turn a CSV/TSV into a new .numbers file (UTF-8, delimiter auto-detected). Plain numbers become numbers (numbers=false keeps everything as text); dates, "$1,234" and Arabic-Indic digits stay text exactly as written. Refuses to overwrite. Use when the data is in a CSV/TSV file. When you already have the rows use numbers_create.

Insert rows or columns (what = rows | columns) before 1-based position at; omit at to append. Optional values: one list per new row (or column). Every existing cell is verified at its new position. In tables with formulas, only appending is allowed (shifting would break references). dry_run=true previews the change on a copy without touching the file. Use to add rows or columns to an existing table (optionally filled). For a separate table use numbers_add_table. In tables with formulas only appending works; do mid-table inserts in Numbers.

Delete count rows or columns (what = rows | columns) starting at 1-based position at. Remaining cells are verified. Refused in tables with formulas or merged cells. Undo with iwork_restore_backup. dry_run=true previews the change on a copy without touching the file. Use to remove rows or columns. Not for clearing values (use numbers_edit_cell with null). Refused in tables with formulas or merges; undo with iwork_restore_backup.

Add a table with data to an existing sheet (sheet, default the first) or to a new sheet (new_sheet). Every existing table is verified unchanged. dry_run=true previews the change on a copy without touching the file. Use for a new, separate table on a sheet or a new sheet. To grow an existing table use numbers_insert.

Start a new document from one of the user's own files (any .numbers / .key / .pages): copies it to path and checks it opens. Refuses to overwrite. Use when the user has their own template or past file to start from. For Apple's built-in templates use iwork_create.

New .numbers / .key / .pages from Apple's built-in templates (Keynote: themes); names from iwork_list_templates. Omit template for Blank / Basic White. Refuses to overwrite. Needs macOS + the app. Use for a new, empty file from Apple's templates. Instead: iwork_create_from_template to copy the user's own file, numbers_create to make a Numbers file from data, keynote_build_deck for a finished deck from an outline.

Put a formula in one cell, e.g. ref "D10", formula "=SUM(D2:D9)"; Numbers computes it and the result is returned. Every other cell's input is verified unchanged. Needs macOS + Numbers, file closed. dry_run=true previews the change on a copy without touching the file. Use for a cell that calculates (=SUM…); Numbers computes the result. For a plain value use numbers_edit_cell. Needs the Numbers app.

Make Numbers recompute every formula from the current values. Numbers keeps showing a formula's old result after edits made without it (numbers_edit_cell, numbers_insert…), so run this after those when the file has formulas — their result says so (formulas_need_recalc). Formulas and inputs are verified unchanged. Needs macOS + Numbers, file closed. dry_run=true previews the change on a copy without touching the file. Use only after a no-app edit returned formulas_need_recalc, so totals are current. Not needed after numbers_set_formula, which recalculates itself.

Sort a table's body rows by a column letter (header rows stay on top). Verified as a pure reorder. A table whose formulas read other rows (e.g. =B2*0.1 below a base-figure row) is refused, because Numbers' sort would break them; for it, to_new_table=true leaves the table, its formulas and its charts as they are and puts a sorted copy of its values (no formulas) in a new table on the same sheet (named new_table_name, default " sorted"). Chart the copy with keynote_build_deck. Needs macOS + Numbers, file closed. dry_run=true previews the change on a copy without touching the file. Use to reorder body rows by one column; header rows stay on top. If it refuses because formulas read other rows, call it again with to_new_table=true for a sorted copy; never rewrite the formulas to force it. Needs the Numbers app.

Template placeholders in a .pages document (tag + current text), e.g. a letter's "Name" or "Date" fields. Needs macOS + Pages. Use before pages_fill_placeholders to see the template's field tags.

Fill template placeholders by tag, e.g. {"Name": "Sara", "Date": "3 October"}. Formatting is kept; the body is verified to change only there. Needs macOS + Pages. dry_run=true previews the change on a copy without touching the file. Use for template fields (Name, Date). It's the only write for page-layout documents like letters and flyers, which have no body text.

Every table in a .pages document: name, size, and each cell's value, shown text and formula. Needs macOS + Pages. Use before pages_set_table_cells to see the tables, their names and cell references.

Write cells of an existing table in a .pages document. table = its name or number (from pages_read_tables); cells = {"B2": 1200, "C3": "تم", "D9": "=SUM(D2:D8)"} — numbers stay numbers, "=…" makes a formula, null clears. Every other cell and the body text are verified unchanged. New tables can't be created (Pages 15 doesn't script it). Needs macOS + Pages, document closed. dry_run=true previews the change on a copy without touching the file. Use to write into an existing Pages table. New tables can't be created in Pages; for text outside tables use pages_replace_all.

Present: action = start (needs path; from_slide 1-based) | stop | next | previous. Doesn't change the file. Needs macOS + Keynote. Use to present the deck live; it doesn't change the file. To share it instead use iwork_export.

Every slide with its text, presenter notes and whether it is hidden (via Keynote). Use slide numbers from here for slide operations. Use before slide operations to see slide numbers, text, notes and hidden state. For fonts and layouts use keynote_inspect_style.

Themes available in Keynote on this Mac (names to pass to keynote_set_theme). Use before keynote_set_theme or keynote_build_deck to get valid theme names.

A deck's styling: current theme, available slide layouts, and per slide its layout plus each text item's text, font, size and colour. Read this before theming. Use before formatting: theme, layouts, and each text item's font, size and colour. For slide text and notes use keynote_list_slides.

Apply a different Keynote theme to the whole deck. Rolled back if any slide loses text. dry_run=true previews the change on a copy without touching the file. Use to switch the deck's theme only. For a full designed look (fonts, sizes, colours) use keynote_apply_design, which can set the theme too.

Change one slide's layout (master), e.g. "Title & Bullets". Other slides are verified untouched. dry_run=true previews the change on a copy without touching the file. Use to change one slide's layout (names from keynote_inspect_style). Not for text styling: use keynote_format_text.

Font (PostScript name, e.g. "HelveticaNeue-Bold"), size (pt) and/or colour ("#RRGGBB") of one text item on a slide — pick it by item index (from keynote_inspect_style) or by a unique piece of its text (match). Alignment and shape fill are not scriptable. dry_run=true previews the change on a copy without touching the file. Use for one text item's font, size or colour. To restyle the whole deck consistently use keynote_apply_design.

Transition into a slide: effect such as dissolve, push, wipe, magic move, cube, flip, move in, reveal, "none"; duration/delay in seconds; automatic=true advances on its own. Other slides verified untouched. dry_run=true previews the change on a copy without touching the file. Use for one slide's transition. For the same transition on every slide of a new deck, pass transition= to keynote_build_deck.

Build a new Keynote deck from an outline. slides = [{"title": "…", "body": ["bullet", "bullet"], "layout": "Title & Bullets", "notes": "…", "image": "/path/pic.png"}, …]; the first slide defaults to a title layout, the rest to Title & Bullets. theme from keynote_list_themes; optional transition for every slide (e.g. dissolve). Every slide is read back and checked; on any mismatch the new file is removed. Never overwrites. kit = a design kit (iwork_list_design_kits) for a designed deck in one call. Chart slides: add "chart": {"type": "bar", "rows": ["2025", "2026"], "columns": ["Q1", "Q2"], "data": [[1, 2], [3, 4]]} or {"type": "line", "from": "/path/report.numbers", "columns": ["Q1", "Q2"]} (header row → column names, first column → row names); chart slides default to Title Only. Table slides: "table": {"rows": [["Region", "Q1"], ["Riyadh", 1200]]} or {"from": "/path/report.numbers", "columns": ["Q1"], "max_rows": 8}; with a kit the table is styled too. Needs macOS + Keynote. Use for a new deck from an outline, including chart and table slides; then run keynote_review_deck. To change an existing deck use the slide and text tools instead.

Add a table to a slide (1-based). rows = [["Region", "Q1"], ["Riyadh", 1200], …]: text, numbers, or null; text starting with "=" is a formula. kit (iwork_list_design_kits name or your own) styles it: header band, fonts (Arabic-aware), banding, numbers right-aligned. Optional x, y (points from top-left) and width. Every cell, font and colour is read back; other slides and tables are checked untouched. At most 50 rows × 15 columns. dry_run=true previews the change on a copy without touching the file. Needs macOS + Keynote. Use for a table on an existing slide. In a new deck, put it in keynote_build_deck's outline; to show a trend use keynote_add_chart.

Design review of a deck as Keynote actually draws it: renders to PDF and reports, per slide, text drawn off the slide or past the bottom of its box (errors), text boxes drawn on top of each other, text under 18 pt, and slides that are too dense (warnings). Run it after building or restyling a deck, fix the errors, then look at a flagged slide with keynote_slide_image. The file isn't changed. Needs macOS + Keynote. Use after building or restyling a deck, before saying it's done; fix every error. To look at a flagged slide use keynote_slide_image; to check one word renders use iwork_verify_render.

One slide as an image (JPEG, width px wide), exported by Keynote, so you can look at the design yourself. Skipped slides aren't exported. The file isn't changed. Needs macOS + Keynote. Use to look at a slide's real rendering, e.g. one keynote_review_deck flagged. For a quick preview without Keynote use iwork_thumbnail (first slide, last saved state).

Make a deck look designed: the kit's theme (optional), then every slide's title and body fonts (Arabic-aware), sizes from a type scale, and colours from a contrast-checked palette. kit = a name from iwork_list_design_kits or your own {"fonts": {...}, "colors": {...}}. Text is verified unchanged. dry_run=true previews the change on a copy without touching the file. Use to restyle a whole deck from a kit. For one text item use keynote_format_text. Preview with dry_run, then run keynote_review_deck.

Fill a slide's title and/or body box (body may be a list of bullet lines). The title box is the top-most text box, the body the largest other one. Other slides and text boxes are verified untouched. dry_run=true previews the change on a copy without touching the file. Use to fill or rewrite one slide's title and body. To change the same words across the deck use keynote_replace_text; for speaker notes use keynote_set_presenter_notes.

Add a chart to a slide from data. rows = series names, columns = category names, data = one list of numbers per row (rows × columns). type: bar | stacked_bar | horizontal_bar | stacked_horizontal_bar | line | area | stacked_area | pie | scatter (or *_3d). group_by: row | column. Text and other charts are verified untouched. dry_run=true previews the change on a copy without touching the file. Use for a chart on an existing slide. In a new deck, put the chart in keynote_build_deck's outline instead; for exact numbers use keynote_add_table.

Place an image file (png, jpg, heic, pdf…) on a slide; optional x/y position and width in points. All text verified untouched. dry_run=true previews the change on a copy without touching the file. Use to place a picture or logo on a slide. For data, use keynote_add_chart or keynote_add_table rather than a picture of a chart.