# Tool page: keyword → surface checklist

**Last Updated:** 2026-04-01

Copy this file to `docs/content/tools/{slug}/KEYWORD_SURFACE_CHECKLIST.md` (optional) or tick items in the PR when shipping or overhauling a tool. **Do not** paste this checklist into visible page copy.

**Sources:** `data/keywords-candidate.json`, `DATA_DRIVEN_SYNTHESIS.md`, `data/paa-questions.json` (for FAQ stems only).

**Rule:** Integrate phrases in **natural German** (compounds, questions). Never write „Keywords“, „SERP“, or „PAA“ on the public page. See `.cursor/rules/tools-pages-content-blocks.mdc`.

## Surfaces

- [ ] **`<title>`** — Primary head term (often compound „…-Rechner“) + year + benefit; ≤ ~60 characters where possible.
- [ ] **Meta description** — Primary + secondary head term once each if readable; disclaimer at end.
- [ ] **OG title / description / image alt** — Aligned with title + meta (no contradictions).
- [ ] **`WebPage.name` / `description`** (JSON-LD `@graph`) — Matches hero promise; no stuffing.
- [ ] **`SoftwareApplication` / `WebApplication`** — Name + description mention tool type + year where relevant.
- [ ] **`HowTo`** (if used) — Steps use same vocabulary as on-page instructions.
- [ ] **Hero H1** — Primary term visible in first line; avoid duplicate of `<title>` only if both stay clear.
- [ ] **Hero lead paragraph** — Secondary head term (e.g. „… berechnen“) and year bridge for legacy searches if appropriate.
- [ ] **First SEO H2 + paragraph** (`seo-content.php` or inline blocks) — Explains what the **Rechner** does; optional „online berechnen“ / inverted phrasing when data-backed.
- [ ] **Further H2s** — Cover high-volume intents (Höhe, Tabelle, Steuer, Phasen) as **sections**, not keyword lists.
- [ ] **`v2/data/tools_index_data.php`** — Listing `description` + `tags` reflect primary phrases naturally.
- [ ] **`v2/data/tools-faqs/{file}.json`** — Questions read like real user questions; answers match visible FAQ HTML (JSON-LD parity).

## Validation (after edits)

- `python3 v2/scripts/tools/audit-tools-content-blocks.py {slug} --format-check`
- `php v2/scripts/tools/validate-tool-content-completeness.php --tool={slug}`
- `php v2/scripts/dev-helpers/verify-faq-jsonld-parity.php --file=tools-faqs/{basename}.json`
- Optional: `php v2/scripts/tools/audit-tool-keyword-coverage.php --tool={slug}`

## Post-deploy

- [ ] Google Rich Results Test (FAQ + main `@graph`)
- [ ] Spot-check mobile hero (tools traffic is often majority mobile)