Explain Performance Anomaly

Explain why a performance metric changed using statistical analysis and historical context.

⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. Uses statistical analysis only (no ML models).

🎯 What This Tool Does (Performance Agent - Phase 1 Feature 4):

• Explains why metrics changed (ROAS, CTR, CPC, conversions, conversion rate)
• Compares current period to historical averages (30/60/90-day)
• Identifies contributing factors with severity levels
• Detects campaign changes (paused, new, budget changes)
• Finds similar historical periods (seasonality detection)
• Provides actionable recommendations to address issues

Returns comprehensive anomaly explanation:

• Current metric value vs historical averages
• Deviation percentages (how much it changed)
• Contributing factors:
  • CPC changes (>15% = auction competition shifts)
  • Conversion rate changes (>10% = landing page/seasonality issues)
  • Campaign changes (paused high-performers, new campaigns, budget changes)
  • Day-of-week patterns (weekend vs weekday effects)
• Similar historical periods for context
• Assessment (normal variation vs requires action)
• Specific recommendations to fix the issue

🔍 How Anomaly Detection Works:

Historical Comparison:

• Compares current period to 30/60/90-day averages
• ±15% deviation considered “normal variation”

• 15% deviation flagged as requiring attention

Contributing Factor Detection:

1. CPC Changes (>15% threshold)

   • Increased CPC = auction competition increased
   • Decreased CPC = auction competition decreased or bid adjustments

2. Conversion Rate Changes (>10% threshold)

   • Decreased = landing page issues, seasonality, audience quality
   • Increased = landing page improved, better targeting

3. Campaign Changes:

   • Paused high-performers (ROAS > 3.0x) = lost revenue driver
   • New campaigns (>$1K spend) = learning phase affecting overall performance
   • Budget changes (>20%) = delivery and auction participation affected

4. Day-of-Week Patterns:

   • Weekend-heavy periods often show different performance
   • Normal for B2C (higher weekend conversion)
   • Normal for B2B (lower weekend conversion)

5. Seasonality Detection:

   • Finds similar historical periods (±10% metric value)
   • Helps identify if drop is seasonal vs real issue

Parameters:

• metric: ‘roas’, ‘ctr’, ‘cpc’, ‘conversions’, ‘conversion_rate’ (REQUIRED)
• period_start: Start date in YYYY-MM-DD format (REQUIRED)
• period_end: End date in YYYY-MM-DD format (REQUIRED, max 30 days period)
• customer_id: Optional (uses connected account if omitted)

Execution time: 2-4 seconds (statistical analysis + database queries) Data source: campaign_daily_metrics table (updated nightly, 120-day retention) Analysis method: Statistical comparison (no ML models) Trigger: Reactive (user asks “why?”), not proactive alerts

Use this tool when:

• User asks “why did my ROAS drop?”
• User asks “why did my CTR increase?”
• User notices unexpected metric changes
• User wants to understand performance fluctuations
• After seeing performance changes in dashboards

📊 AFTER calling this tool, help the user understand:

Normal vs Abnormal Variation:

• Normal: ±15% deviation, typical day-of-week/seasonal patterns
• Abnormal: >15% deviation with specific contributing factors

Severity Levels:

• 🔴 HIGH: >25% change with clear cause (CPC spike, campaign paused)
• 🟡 MEDIUM: 15-25% change or multiple minor factors
• 🟢 LOW: <15% change, likely normal variation

Example Interpretation: “Your ROAS dropped 33% from 4.2x to 2.8x. This was caused by two high-severity factors:

1. CPC increased 25% (auction competition spike during holiday season)
2. Your top campaign ‘Brand - Exact’ was paused, losing $240/day in high-ROAS revenue

This is NOT normal variation - these are actionable issues. Recommendations:

• Reduce bids by 10-15% to counter CPC inflation
• Re-enable ‘Brand - Exact’ campaign if budget allows
• Review landing page conversion rate (also dropped 12%)”

Similar Period Context: If tool finds similar historical periods, explain seasonality: “Your ROAS was similarly low (2.7x) on December 18, 2024, which was also during the holiday shopping season. This suggests some of the drop is seasonal, but the campaign pause is amplifying the effect.”

Quick Actions: Based on contributing factors, prioritize:

1. Campaign paused → Re-enable high performers immediately
2. CPC spike → Adjust bids, improve Quality Score
3. Conversion rate drop → Review landing page, check for bugs
4. Budget changes → Monitor delivery as it stabilizes
5. Weekend effect → Normal variation, no action needed

Visualization Tip: Suggest creating a line chart showing the metric over time with 30-day average band and annotations for detected factors (e.g., “Campaign paused here”, “CPC spike started here”).

Important Notes:

• This is REACTIVE explanation, not proactive monitoring
• Max 120-day historical lookback (database retention limit)
• Uses simple statistics (mean, variance), no ML predictions
• Focus on actionable factors user can control
• Consider seasonality when interpreting results

Best Practices:

• Run this tool when you notice >15% metric changes
• Compare multiple time periods to confirm trends
• Cross-reference with other tools (wasted spend, budget optimizer)
• Use for post-mortem analysis of performance changes
• Help user distinguish normal variation from real issues

💬 Community: For anomaly analysis discussions, visit our Discord: https://discord.gg/dH3Qt4YS