detect_meta_creative_fatigue

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

User asks about creative fatigue, ad refresh timing, frequency management, declining CTR, when to replace ads, or audience exhaustion on Meta/Facebook/Instagram. This tool analyzes all Meta Ads creatives for fatigue indicators using frequency-CTR correlation analysis and provides a fatigue score (0-100) for each ad. Returns: - Fatigue score (0-100) for each ad based on weighted factors - Severely fatigued ads (score ≥80) - immediate action required - At-risk ads (score 50-79) - plan refresh within 7-14 days - Healthy ads count - Daily spend being wasted on fatigued creatives - Projected monthly waste - Refresh schedule recommendations - Contributing factors for each fatigued ad When to use this tool: - "Are any of my Meta/Facebook/Instagram ads fatigued?" - "When should I refresh my creatives?" - "Why is my CTR declining?" - "Which ads have high frequency?" - "How much am I wasting on fatigued ads?" - "What's my ad refresh schedule?" - "Are my retargeting ads showing too often?" Parameters: - lookback_days: 7, 14, 30 (default), 60, or 90 days - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - frequency_threshold_cold: 2.0-8.0 (default: 4.0) - threshold for cold traffic audiences - frequency_threshold_retargeting: 4.0-10.0 (default: 7.0) - threshold for retargeting audiences - ctr_decline_threshold: 0.10-0.50 (default: 0.20 = 20%) - CTR decline to flag as fatigued - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 2-5 seconds (cached database query with analysis) Data source: meta_ad_creative_metrics table (ad-level daily metrics with frequency, CTR, video completion) Fatigue Score Calculation: The fatigue score (0-100) is calculated using weighted factors: - Frequency (40%): impressions/reach ratio vs threshold - CTR Decline (35%): % drop in CTR vs previous period - Days Running (25%): creative age vs optimal refresh timing Severity Levels: - 🔴 Score ≥80: Severely fatigued - PAUSE immediately and replace - 🟡 Score 50-79: At risk - prepare replacement within 7-14 days - ✅ Score <50: Healthy - continue monitoring Best practices: - Cold traffic: Refresh creatives when frequency reaches 3-4x - Retargeting: Can tolerate higher frequency (up to 6-7x) - Create 3-5 variations per ad set for automatic rotation - Monitor weekly for frequency and CTR trends

{
  "arguments": {
    "start_date": "string",
    "end_date": "string",
    "date_range": "string",
    "raw_data": false,
    "lookback_days": 30,
    "frequency_threshold_cold": 4.0
  }
}

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

{
  "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": "detect_meta_creative_fatigue"
}

{
  "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": "detect_meta_creative_fatigue",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}