Ads Analyst

interface AdsAnalystInput {
  tenantId:       string;
  campaignId:     string;
  dateRange: {
    start: string;  // ISO date, e.g. "2026-03-01"
    end:   string;  // e.g. "2026-03-31"
  };
  comparisonRange?: {
    start: string;  // prior period for MoM or WoW comparison
    end:   string;
  };
  campaignGoals: {
    primaryGoal:   'leads' | 'sales' | 'traffic' | 'brand_awareness' | 'app_installs';
    targetCPA?:    number;   // target cost per acquisition in dollars
    targetROAS?:   number;   // target return on ad spend, e.g. 4.0
    targetCTR?:    number;   // target CTR as decimal, e.g. 0.03
  };
  budget: {
    totalMonthlyBudget: number;  // total spend budget in dollars
    googleAllocation?:  number;  // current Google Ads allocation
    metaAllocation?:    number;  // current Meta Ads allocation
  };
  googleAdsCustomerId?: string;   // required if Google Ads connected
  metaAdAccountId?:     string;   // required if Meta Ads connected
}

interface AdsAnalystOutput {
  reportPeriod:   { start: string; end: string };
  generatedAt:    string;   // ISO timestamp
 
  campaignHealthSummary: {
    overallHealth:  'healthy' | 'needs_attention' | 'critical';
    headline:       string;   // 1–2 sentence plain-English summary
    googleHealth?:  'healthy' | 'needs_attention' | 'critical';
    metaHealth?:    'healthy' | 'needs_attention' | 'critical';
  };
 
  topPerformers: AdPerformanceItem[];   // top 3 by ROAS or primary goal metric
  bottomPerformers: AdPerformanceItem[]; // bottom 3 — candidates for pause/restructure
 
  wastedSpend: {
    totalEstimatedWaste: number;  // dollars
    items: WastedSpendItem[];
  };
 
  bidStrategyRecommendations: Recommendation[];
  targetingRecommendations:   Recommendation[];
  creativeFatigueFlags:       CreativeFatigueFlag[];
 
  budgetAllocationRecommendation: {
    currentGooglePct:     number;
    currentMetaPct:       number;
    recommendedGooglePct: number;
    recommendedMetaPct:   number;
    rationale:            string;
  };
 
  nextSteps: string[];   // ordered list of priority actions
}
 
interface AdPerformanceItem {
  platform:     'google' | 'meta';
  campaignName: string;
  adGroupOrSet?: string;
  spend:        number;
  impressions:  number;
  clicks:       number;
  ctr:          number;
  cpc:          number;
  conversions:  number;
  cpa:          number;
  roas?:        number;
  verdict:      string;  // one-sentence assessment
}
 
interface WastedSpendItem {
  platform:    'google' | 'meta';
  campaign:    string;
  issue:       string;   // e.g. "High spend, zero conversions (14 days)"
  spend:       number;
  recommendation: string;
}
 
interface Recommendation {
  priority:    'high' | 'medium' | 'low';
  platform:    'google' | 'meta' | 'both';
  action:      string;
  rationale:   string;
  expectedImpact: string;
}
 
interface CreativeFatigueFlag {
  platform:    'google' | 'meta';
  adName:      string;
  metric:      string;   // e.g. "CTR declined 42% over 14 days"
  runningDays: number;
  recommendation: string;
}

## Campaign Health Summary
 
**Overall health:** Needs Attention
 
Google Ads is performing above target ROAS (4.8 vs. 4.0 target), but Meta Ads has three ad sets
with frequency > 4.5 showing declining CTR — creative refresh required. Total estimated wasted
spend this month is $1,240, concentrated in two non-converting Google Display campaigns.
 
---
 
## Top Performers
 
| Platform | Campaign | Spend | Conv. | CPA | ROAS | Assessment |
|---|---|---|---|---|---|---|
| Google | Brand Search — Exact | $2,100 | 87 | $24.14 | 7.2x | Healthy — increase budget 20% |
| Meta | Retargeting — 30d Visitors | $890 | 34 | $26.18 | 5.8x | Strong ROAS — expand audience |
| Google | Competitor Keywords | $1,450 | 41 | $35.37 | 4.1x | On target — maintain current bid |
 
---
 
## Wasted Spend
 
| Campaign | Platform | Issue | Spend | Action |
|---|---|---|---|---|
| Display Remarketing — Broad | Google | 0 conversions in 14 days | $640 | Pause — reallocate to Brand Search |
| Interest Expansion — Cold | Meta | CPA $148 vs. $45 target | $600 | Narrow audience; test lookalike seed |
 
---
 
## Budget Allocation Recommendation
 
**Current:** Google 60% / Meta 40%
**Recommended:** Google 70% / Meta 30%
 
**Rationale:** Google ROAS is 4.8x vs Meta's 2.9x this period. Shifting $800/month to Google Search
and Competitor campaigns is projected to improve blended ROAS from 3.6x to 4.1x.

You are an expert paid advertising analyst for a digital marketing agency. Your job is to
analyse Google Ads and Meta Ads performance data and produce a structured analysis report
with specific, data-backed recommendations.

CLIENT CONTEXT:
{{CLIENT_CONTEXT}}

KNOWLEDGE BASE CONTEXT:
{{RAG_CONTEXT}}

You have been provided with:
- Google Ads performance data (campaigns, ad groups, keywords) for the analysis period
- Meta Ads performance data (campaigns, ad sets, ads) for the analysis period
- Campaign goals including target CPA/ROAS
- Current budget allocation
- Prior period data for comparison

Your analysis must:
1. Open with a plain-English campaign health summary a non-technical client can understand
2. Identify the top 3 and bottom 3 performers by primary goal metric (ROAS for e-commerce, CPA for lead gen)
3. Quantify wasted spend — be specific about which campaigns, why they're wasted, and the exact dollar amount
4. Flag creative fatigue with data (CTR trend, frequency, days running)
5. Give bid strategy recommendations tied to observed performance data — cite specific numbers
6. Give a budget reallocation recommendation with projected impact
7. Produce a prioritised next steps list (no more than 5 items)

Rules:
- Every recommendation must cite the specific metric driving it
- No generic advice (e.g. "test more ad creatives" is insufficient — name the specific ad set and the fatigue signal)
- Flag any anomalies that might be explained by known seasonality or promotions from the client context
- If comparison period data is unavailable, note this and proceed with absolute metrics only

Output as the AdsAnalystOutput JSON schema followed by a Markdown narrative report suitable
for client delivery.

# Ads Performance Benchmarks by Industry
 
These benchmarks are used to contextualise client performance. Always compare against the
client's own historical data first. Use industry benchmarks as a secondary reference when
historical data is unavailable or the client is new to paid advertising.
 
## Google Ads — Average CTR by Industry
| Industry | Search CTR | Display CTR |
|---|---|---|
| Legal | 4.76% | 0.59% |
| E-commerce | 2.69% | 0.51% |
| Finance | 2.65% | 0.52% |
| Health & Medical | 3.27% | 0.59% |
| B2B/SaaS | 2.41% | 0.46% |
| Home Services | 4.80% | 0.72% |
 
## Google Ads — Average CPA by Industry
| Industry | Avg CPA (Search) |
|---|---|
| E-commerce | $45.27 |
| Legal | $86.02 |
| Finance | $81.93 |
| B2B/SaaS | $116.13 |
| Health & Medical | $78.09 |
 
## Meta Ads — Average Benchmarks
| Metric | Average Across Industries |
|---|---|
| CTR (Link) | 0.90% |
| CPM | $14.90 |
| CPC | $1.68 |
| Conversion Rate | 9.21% |
 
## Creative Fatigue Thresholds (Meta)
- Frequency > 3.5 within 7 days: monitor
- Frequency > 5.0 within 14 days: refresh creative
- CTR decline > 30% over 14 days: fatigued regardless of frequency
 
## ROAS Health Indicators
- ROAS < 1.0: Actively losing money — pause immediately
- ROAS 1.0–2.0: Below breakeven for most businesses — investigate
- ROAS 2.0–4.0: Acceptable depending on margins
- ROAS > 4.0: Strong — consider scaling