Google Ads Writer

interface GoogleAdsWriterInput {
  tenantId:          string;
  campaignId?:       string;
 
  campaignName:      string;                                              // e.g. "Spring HVAC Specials — Sydney"
  campaignGoal:      'leads' | 'sales' | 'awareness' | 'traffic';
  targetKeywords:    string[];                                            // exactly 5 — primary keywords to work into headlines
  landingPageUrl:    string;                                              // used to verify display path and align messaging
  geographicTarget?: string;                                              // e.g. "Sydney", "North Shore", "Australia-wide"
  existingAds?:      { headlines: string[]; descriptions: string[] }[];   // previously used ads — avoid repetition
}

interface GoogleAdsWriterOutput {
  headlines: {
    text:         string;        // HARD MAX: 30 characters — validation rejects any headline over this limit
    charCount:    number;
    pinPosition?: 1 | 2 | 3;    // if set, this headline is pinned to that position in the ad
  }[];                           // exactly 15 items
 
  descriptions: {
    text:         string;        // HARD MAX: 90 characters — validation rejects any description over this limit
    charCount:    number;
    pinPosition?: 1 | 2;        // if set, this description is pinned to that position in the ad
  }[];                           // exactly 4 items
 
  displayPath1:  string;         // HARD MAX: 15 characters — first display URL path segment
  displayPath2:  string;         // HARD MAX: 15 characters — second display URL path segment
  finalUrl:      string;         // the actual destination URL
  qualityNotes:  string[];       // 3–5 notes explaining headline variety, keyword inclusion, and pinning rationale
}

headlines: [
  { text: "Emergency Plumber Melbourne",   charCount: 28, pinPosition: 1 },  // 28 chars — pinned H1
  { text: "Fixed Fast or It's Free",        charCount: 23, pinPosition: 2 },  // 23 chars — pinned H2
  { text: "Available 24/7 — Call Now",      charCount: 25 },                  // 25 chars
  { text: "Licensed Local Plumbers",        charCount: 22 },                  // 22 chars
  { text: "Same-Day Blocked Drain Fix",     charCount: 26 },                  // 26 chars
  { text: "No Fix No Fee Guarantee",        charCount: 23 },                  // 23 chars
  { text: "Hot Water Repairs Today",        charCount: 22 },                  // 22 chars
  { text: "Burst Pipe? We're 30 Min Away",  charCount: 29 },                  // 29 chars
  { text: "Melbourne's #1 Plumber",         charCount: 22 },                  // 22 chars
  { text: "Upfront Pricing, No Surprises",  charCount: 29 },                  // 29 chars
  { text: "Gas Fitting Specialists",        charCount: 23 },                  // 23 chars
  { text: "Free Quote in 60 Seconds",       charCount: 25 },                  // 25 chars
  { text: "500+ Five-Star Reviews",         charCount: 22 },                  // 22 chars
  { text: "Trusted Since 2008",             charCount: 18 },                  // 18 chars
  { text: "Book Online, Fast Response",     charCount: 26 }                   // 26 chars
]

descriptions: [
  { text: "Call Melbourne's emergency plumbers. Same-day repairs, no fix no fee.",
    charCount: 69, pinPosition: 1 },                                         // 69 chars — pinned D1
  { text: "Blocked drains, burst pipes, hot water failures — on call 24/7 in Melbourne.",
    charCount: 75 },                                                          // 75 chars
  { text: "Upfront pricing, licensed tradies, 100% satisfaction guarantee on every job.",
    charCount: 75 },                                                          // 75 chars
  { text: "500+ five-star reviews. Book online or call for a free 60-second quote.",
    charCount: 71 }                                                           // 71 chars
]

displayPath1: "Plumber"        // 7 chars
displayPath2: "Melbourne"      // 9 chars

qualityNotes: [
  "Primary keyword 'Emergency Plumber Melbourne' pinned to H1 — relevance signal in every impression.",
  "All 5 target keywords appear across the headline set — Google can assemble high-relevance combinations.",
  "H2 pins the core guarantee ('Fixed Fast or It's Free') — risk reversal anchored in every ad.",
  "Descriptions cover urgency, service range, guarantee, and social proof — variety enables Google's rotation.",
  "All 15 headlines are within the 30-character hard limit. All 4 descriptions are within the 90-character hard limit."
]

You are a paid search copywriter specialising in Google Ads RSA (Responsive Search Ad) copy.
You write ad copy that earns high Quality Scores, wins auctions, and converts clicks into leads.

CLIENT CONTEXT:
{{CLIENT_CONTEXT}}

TENANT SETTINGS:
{{TENANT_SETTINGS}}

KNOWLEDGE BASE CONTEXT (USPs, competitor angles, landing page content, offer details):
{{RAG_CONTEXT}}

CAMPAIGN BRIEF:
Campaign name: {{CAMPAIGN_NAME}}
Campaign goal: {{CAMPAIGN_GOAL}}
Target keywords: {{TARGET_KEYWORDS}}
Landing page URL: {{LANDING_PAGE_URL}}
Geographic target: {{GEOGRAPHIC_TARGET}}
Existing ads to avoid repeating: {{EXISTING_ADS}}

CHARACTER LIMITS — ABSOLUTE AND NON-NEGOTIABLE:
- Every headline: MAXIMUM 30 characters including spaces and punctuation
- Every description: MAXIMUM 90 characters including spaces and punctuation
- Display path 1: MAXIMUM 15 characters
- Display path 2: MAXIMUM 15 characters
Count every headline and description before including it. If it is over the limit, rewrite it.
Do not trim — rewrite. A trimmed headline is often grammatically broken.

Your RSA must:
1. Include exactly 15 headlines and exactly 4 descriptions. No more, no fewer.
2. Cover the full range of ad copy angles: keyword-direct, benefit-led, social proof, guarantee,
   urgency, location, and offer-specific. Google rotates combinations — variety is how you win.
3. Work all 5 target keywords into the headline set naturally. Distribute them so Google can
   assemble high-relevance combinations for different queries.
4. Pin Headline 1 = brand or primary keyword. Pin Headline 2 = strongest differentiator or
   guarantee. Pin Description 1 = primary CTA containing the main target keyword.
5. Use only claims sourced from the Client Context or Knowledge Base. Do not invent guarantees,
   years in business, star ratings, or offer details. If a detail is unavailable, write a
   benefit statement instead.
6. Match the messaging on the landing page — ad-to-page alignment is a Quality Score factor.
7. Differentiate from competitor angles identified in the knowledge base. If competitors lead
   with "Fast & Affordable", find a different angle.
8. Apply the brand tone from tenant settings to all copy.
9. Avoid all prohibited words from tenant settings.

Output as JSON matching the GoogleAdsWriterOutput schema exactly.
Include a qualityNotes[] array with 3–5 notes explaining keyword coverage, pin rationale,
and a confirmation that all character limits were respected.

# Google Ads Copywriting Guide
 
## RSA Structure and Google's Rotation Logic
 
A Responsive Search Ad gives Google up to 15 headlines and 4 descriptions. Google's machine
learning assembles combinations of 3 headlines and 2 descriptions per impression — choosing
the combination it predicts will perform best for a given user and query.
 
The writer's job is not to write one perfect ad. It is to write 15 headlines and 4 descriptions
that can be combined in hundreds of ways and remain coherent in any combination. Every headline
must make sense next to any other headline. Every description must work alongside either other
description.
 
## Character Limits — Absolute Hard Rules
 
| Element | Limit |
|---|---|
| Each headline | 30 characters (including spaces and punctuation) |
| Each description | 90 characters (including spaces and punctuation) |
| Display path 1 | 15 characters |
| Display path 2 | 15 characters |
 
Count before you write, not after. Worked example: "Emergency Plumber Melbourne" = 28 chars
(fine). "24/7 Emergency Plumber Melbourne NSW" = 36 chars (over — split into two headlines:
"Emergency Plumber Melbourne" + "Available 24/7 — Call Now"). A common mistake is assuming
punctuation doesn't count. It does. Hyphens, commas, apostrophes — all count.
 
## The 15 Headlines: Coverage Framework
 
Aim to have at least one headline in each category:
 
**Keyword-direct (2–3 headlines)**
The search query, or close variant, written as naturally as possible.
- "Emergency Plumber Melbourne" — matches the query; anchors relevance.
- "Blocked Drain Specialists" — variant of a secondary keyword.
 
**Benefit-led (3–4 headlines)**
What the customer gets — specific, not generic. "Quality Service" is invisible.
- "Same-Day Blocked Drain Fix" — specific service + speed.
- "Hot Water Repairs Today" — specific service + urgency.
- "Free Quote in 60 Seconds" — specific, low-friction entry point.
 
**Social proof (1–2 headlines)**
A real, verifiable trust signal. Cite the source or the number — vague claims are ignored.
- "500+ Five-Star Reviews" — specific.
- "Trusted Since 2008" — longevity as proof.
- "10,000 Jobs Completed" — volume as proof.
 
**Guarantee or risk reversal (1–2 headlines)**
Reduces the perceived risk of clicking. Must be a real guarantee from the client.
- "No Fix No Fee Guarantee" — classic risk reversal.
- "Fixed Fast or It's Free" — combines speed + guarantee.
 
**Urgency or availability (1–2 headlines)**
Works especially well for service categories where timing matters.
- "Available 24/7 — Call Now" — 25 chars.
- "Burst Pipe? We're 30 Min Away" — 29 chars — matches urgent query intent.
 
**Offer-specific (1–2 headlines)**
A seasonal promotion, discount, or specific offer from the campaign brief.
- "$0 Call-Out Fee This Month" — 26 chars.
- "Get 10% Off First Service" — 25 chars.
 
**Brand + CTA (1 headline)**
A brand name with a direct action — used as a fallback or lower-funnel headline.
- "Book Online, Fast Response" — 26 chars.
 
## Pin Strategy
 
Google allows pinning headlines to positions 1, 2, or 3.
 
**Always pin:**
- Position 1: brand name or primary keyword — establishes context in every combination.
- Position 2: the single strongest differentiator or guarantee.
 
**Never pin more than 2 headlines.** Over-pinning restricts Google's ability to find high-
performing combinations and reduces eligible impressions.
 
**For descriptions:**
- Pin Description 1 to the primary CTA — this is the most prominent description position.
- Leave Description 2 unpinned to allow Google to rotate for intent.
 
## Quality Score Factors Influenced by Copy
 
1. **Expected CTR** — won by including the search query (or close variant) in at least one
   headline. Keyword-direct headlines signal relevance to the algorithm.
 
2. **Ad relevance** — Google compares the ad to the keyword list. Mentioning the service
   category, location, and main keywords improves relevance score.
 
3. **Landing page experience** — ad-to-page message match matters. If the ad says "No Fix No
   Fee Guarantee", that phrase should appear on the landing page.
 
## What Makes Ads Convert
 
- **Specificity over vagueness.** "500+ Five-Star Reviews" beats "Highly Rated".
- **The guarantee in Headline 2.** Risk reversal is consistently the strongest second
  headline across service categories.
- **Numbers.** "30 Min Away", "60 Seconds", "10% Off", "Since 2008" — numbers stop the scan.
- **Match the emotional urgency of the search.** A "burst pipe" query has panic behind it.
  "Burst Pipe? We're 30 Min Away" earns the click. "Plumbing Services Available" does not.
 
## Prohibited Phrases and Practices
 
- Do not use superlatives without proof: "Best in Australia", "Number 1" without citation.
- Do not use clickbait framing that cannot be substantiated by the landing page.
- Do not repeat the same phrase across more than 2 headlines — Google deduplicates at serving
  time, reducing variety and suppressing impressions.
- Do not use ALL CAPS for full headlines — Google may disapprove the ad.
- Avoid excessive punctuation. One exclamation mark per ad set, maximum.
- No competitor brand names in ad text.