---
name: google-slides-toolforest
description: >
  Use when creating or editing Google Slides presentations via Toolforest MCP
  tools. Triggers on: create_presentation, add_slide, add_text_box, set_theme,
  set_page_background, create_shape, add_image, embed_chart, create_table,
  get_slide_content_elements, or any request to build, design, or modify a
  slide deck using Google Slides through the Toolforest connector.
---

### Core Workflow

Follow these steps for every presentation build:

1. **Create presentation** → create_presentation returns presentation_id, default slide ID, available layouts, and page dimensions (standard: 9,144,000 × 5,143,500 EMU).
2. **Set theme** → set_theme for master background, default text color, heading + body font families, accent colors. Never skip this step. Never default to Arial — always choose an intentional pairing (see references/fonts.md). If the user's request implies a specific audience or mood (boardroom, creative pitch, data-heavy report, high-energy launch), read references/themes.md and apply a matching preset.
3. **Build and verify each slide — ONE AT A TIME.** For each slide, complete ALL of the following before moving to the next:

   a. **Add the slide** → Use add_slide with layout_id (prefer "p12" / BLANK for full control). Delete default placeholders (i0, i1) on first slide if building a custom title.
   b. **Populate the slide** → Add shapes, text boxes, tables, images.
   c. **Verify the slide** → Call get_slide_content_elements and check EVERY element against the verification checks below.
   d. **Fix any failures** → If any check fails, fix the issue, then re-verify. Repeat until the slide passes.
   e. **Only then move to the next slide.**

### Mandatory Verification Checks (Run After EVERY Slide)

After calling get_slide_content_elements, check ALL of the following. If ANY check fails, fix and re-verify before proceeding.

**Layout:**
- All right edges (x + width) < 9,144,000 EMU
- All bottom edges (y + height) < 5,143,500 EMU
- No overlapping elements (compare bounding boxes of all element pairs)
- Content ≥ 457,200 EMU from slide edges
- ≥ 150,000 EMU gap between elements (228,600 EMU preferred)
- Stacked text is measure-then-place: never anchor subtitles, captions, or body text below a variable-height headline using a hardcoded `y`. Verify the upper text box first, then place the lower element at `actual_bottom + gap`, where `actual_bottom = y + max(height, estimatedContentHeight)`.

**Text overflow (vertical):**
- estimatedOverflow: false on all text boxes and tables
- For text boxes, investigate overflow by comparing `estimatedContentHeight` to `estimatedUsableHeight` (not raw element height). Google Slides reserves internal vertical text inset, and `estimatedOverflow` uses the usable height.
- If autofit was used: scale_factor ≥ 0.7. If below 0.7, the element MUST be rebuilt — enlarge the box, reduce content, or split across elements.

**Text overflow (horizontal):**
- `estimatedHorizontalOverflow: false` on all text boxes. `true` means content bleeds past the box's left/right edges — the vertical checks above cannot detect this.
- Investigate by comparing `estimatedContentWidth` (widest rendered line) to `estimatedUsableWidth` (box width minus the horizontal inset). Normally-wrapping text never trips this; it fires for unbreakable content wider than the box — oversized drop-cap glyphs, big display numerals, or a forced single line.
- To fix: widen the box so `estimatedContentWidth ≤ estimatedUsableWidth`. A decorative glyph may legitimately overflow *vertically* (tall by nature), but `estimatedHorizontalOverflow: true` is a real bleed — fix it.

**Font sizes (tiered minimum):**
- Body text, bullets, descriptions: ≥ 14pt
- KPI labels and captions: ≥ 10pt
- Nothing below 10pt — ever. If any text is below 10pt, delete and rebuild the element.

**Formatting quality:**
- Text hierarchy is visible — headings, body, and captions are clearly distinct
- Body text is LEFT-aligned, not centered
- Colors create proper contrast against the background

**Contrast (from check_presentation and get_slide_content_elements):**
- `contrastSufficient: true` means the element passes WCAG AA contrast ratio
- `contrastSufficient: false` means text color doesn't have enough contrast against its background
- To fix: use `update_element_style` to change the text color on that specific element, or pass explicit `text_color` when creating elements on slides with non-default backgrounds
- Common cause: `set_page_background` changes one slide's background but the global `default_text_color` (from `set_theme`) still applies — see Gotcha 4 below

For the full checklist including common issues and z-order checks, see scripts/verify_slide.md.

### Critical Gotchas (Read These First)

These are the highest-signal failure points. They are non-obvious and will waste significant time if missed.

### Gotcha 1: autofit Is Boolean, Not String

Always set autofit: true + min_font_size_pt: 10 on content text boxes. Check scale_factor in the response — values below 0.7 mean the box is too small and MUST be rebuilt.

✅ autofit: true, min_font_size_pt: 10
❌ autofit: "SHAPE_AUTOFIT" → ValidationError
❌ min_font_size_pt: 8 → allows illegible text

Two corollaries that bite repeatedly:

- **Pass `min_font_size_pt: 10` on every body text box that might not fit its content** (especially in tight cards). Without the explicit floor, autofit will silently scale below 10pt and violate the hard rule above.
- **Decorative oversized glyphs need `autofit: false`.** Drop-cap quote marks, big italic numerals, condensed display type at 96pt+ — autofit will scale them below the 0.7 floor every time. Use `autofit: false` and a generously sized box. A genuinely decorative glyph may report `estimatedOverflow: true` simply because it is tall (compare `estimatedContentHeight` with `estimatedUsableHeight`) — that vertical warning can be acceptable. But `estimatedHorizontalOverflow: true` means the glyph is bleeding sideways out of its box: the box is too narrow — widen it until `estimatedContentWidth ≤ estimatedUsableWidth`. Never override body text overflow of either kind.

### Gotcha 2: Hex Encoding for Images, Never Base64

Claude/Cowork's content filter scans outgoing tool parameters for API key-like patterns. Base64 image data can trigger this, silently corrupting the image. Always use hex encoding.

✅ image_encoding: "hex", image_data: "89504e470d0a1a0a..."
❌ image_encoding: "base64" (may be corrupted by content filter)

Always read hex data from file programmatically. Never hand-type or split hex strings manually.

### Gotcha 3: Gradients via create_gradient

Use create_gradient to add gradient backgrounds and rectangular fills. Supports full-slide backgrounds (position at 0,0 with slide dimensions) and rectangular gradient fills at any position/size. Limitation: gradients are always rectangular — they won't clip to non-rectangular shapes like rounded rectangles or circles.

### Gotcha 4: set_page_background vs default_text_color

`set_theme` sets a global `default_text_color` that applies to ALL slides via all text-creating tools (`add_text_box`, `create_table`, `create_shape`). `set_page_background` changes the background of ONE slide. If the new background conflicts with the global text color, you'll get contrast failures from `check_presentation`.

Fix: after calling `set_page_background`, explicitly set `text_color` on elements for that slide — either pass it directly when creating elements, or use `update_element_style` to change existing elements. Do NOT try to call `set_theme` again or guess non-existent tools to fix contrast.

### Gotcha 5: Font Rendering — Google Fonts Only

Google Slides cannot embed fonts. Licensed fonts (Proxima Nova, Avenir, Helvetica Neue, Futura) fall back silently to a default. Stick to Google Fonts catalog. See references/fonts.md for safe pairings.

### Gotcha 6: Stacked Text Needs Measure-Then-Place

Title slides and hero layouts often stack a headline above a subtitle. Display fonts, all-caps text, and multi-line headlines can render taller than their requested box. Do not place the subtitle at a fixed `y` such as `2,850,000` EMU.

Correct sequence:

1. Create the headline with a generous height, or with `autofit: true` and `min_font_size_pt: 10`.
2. Call `get_slide_content_elements` and read the headline's `estimatedContentHeight`, `height`, and `estimatedOverflow`.
3. If `estimatedOverflow` is true, rebuild the headline box so `height >= estimatedContentHeight`, reduce the text, or use acceptable autofit with `scale_factor >= 0.7`.
4. Place the subtitle only after the headline passes: `subtitle_y = headline_y + max(headline_height, estimatedContentHeight) + gap`.
5. Re-run verification and confirm the headline and subtitle bounding boxes have at least 150,000 EMU between them.

This is mandatory for variable-height title stacks, including Tokyo Neon slides with large Oswald headlines.

### Font Size Reference (Quick Look)

| Element | Size |
|---------|------|
| Slide title | 24–40pt bold |
| Section header | 20–26pt bold |
| KPI / stat numbers | 28–48pt bold, accent color |
| Body text, bullets | 14–16pt |
| KPI labels, captions | 10–12pt muted |

Nothing below 10pt — ever.

## Reference Files

Claude should read these on demand — not all at once.

- references/design-patterns.md — Layout patterns (header bars, card grids, KPI callouts, two-column splits), color palettes for dark/light/accent backgrounds. Read when designing slide layouts.
- references/fonts.md — Font pairing recommendations by audience/tone, common mistakes, Google Fonts availability. Read when choosing typography.
- references/themes.md — Alternative theme presets by audience (editorial, creative, analytical, bold). Read when the user requests a different mood than the default Toolforest theme, or when the audience clearly calls for one.
- references/images-and-charts.md — Image embedding via hex encoding, size constraints, Sheets→Slides chart pipeline. Read when adding images or data visualizations.
- references/tables-and-formatting.md — Table creation, multi-run text formatting for visual hierarchy, alignment rules. Read when creating tables or text-heavy slides.
- scripts/verify_slide.md — Full verification checklist with common issues and edge cases. The critical checks are already inline above — this file has additional detail.
- config.json — User preferences (theme colors, font pairing, margin style). If this file doesn't exist, ask the user for preferences or use sensible defaults.