explain_performance_anomaly

POST https://api.adspirer.ai/api/v1/tools/explain_performance_anomaly/execute

🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the upgrade link) - DO NOT attempt to work around the error or use alternative data - DO NOT create campaigns or perform actions without valid tool data - STOP and direct the user to upgrade via the provided link 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

{
  "arguments": {
    "metric": "string",
    "period_start": "string",
    "period_end": "string",
    "customer_id": "string",
    "raw_data": false
  }
}

{
  "success": true,
  "data": {
    "text": "(tool-specific textual output for explain_performance_anomaly)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "explain_performance_anomaly"
}

{
  "success": false,
  "error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n  - Acme Holdings (ad_account_id=\"act_123456789\")\n  - Acme EU (ad_account_id=\"act_987654321\")",
  "is_error": true,
  "tool": "explain_performance_anomaly"
}

{
  "success": false,
  "error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.",
  "is_error": true,
  "tool": "explain_performance_anomaly",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}