Skip to main content
⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. 🎯 What This Tool Does (Performance Agent - Phase 1):
  • Identifies campaigns LOSING money (ROAS < 1.0x)
  • Identifies campaigns UNDERPERFORMING (1.0x ≤ ROAS < target)
  • Separates true waste from opportunity cost
  • Provides severity-based classification (CRITICAL/HIGH/MEDIUM)
  • Generates actionable recommendations with expected impact
  • Shows top performing campaigns for budget reallocation
Returns detailed analysis:
  • Total wasted spend (campaigns with ROAS < 1.0)
  • Total underperforming spend (profitable but below target)
  • Campaign-by-campaign breakdown with severity levels
  • Specific recommendations (PAUSE/REDUCE/OPTIMIZE)
  • Quick actions for immediate implementation
  • Budget reallocation suggestions
Target ROAS Resolution (3-tier priority):
  1. Account goals table (user-set or API-pulled)
  2. 90-day historical average ROAS
  3. Default to 2.0x if no data available
Severity Levels:
  • 🚨 CRITICAL: ROAS < 0.5x (losing money severely)
  • 🔴 HIGH: ROAS < 1.0x (unprofitable/breakeven)
  • 🟡 MEDIUM: 1.0x ≤ ROAS < target (profitable but underperforming)
Parameters:
  • lookback_days: 7, 30, 60, 90, or 120 days (default: 30)
  • 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.
  • target_roas: Optional override (e.g., 3.0 for 3.0x ROAS)
  • customer_id: Optional (uses connected account if omitted)
Execution time: 1-3 seconds (cached database query) Data source: campaign_daily_metrics table (updated nightly) Use this tool when:
  • User asks “where is my money going?”
  • User wants to identify wasted spend
  • User wants to optimize campaign budgets
  • User asks which campaigns to pause/reduce
  • User wants to know which campaigns are losing money
📊 AFTER calling this tool, help the user understand: Wasted vs. Underperforming:
  • Wasted Spend = Actual losses (ROAS < 1.0, you’re losing money)
  • Underperforming Spend = Opportunity cost (profitable but below target)
Example:
  • Campaign A: Spent $1000, got $600 back (ROAS 0.6x) → $400 WASTED
  • Campaign B: Spent $1000, got $1500 back (ROAS 1.5x, target 3.0x) → $0 wasted, but $500 opportunity cost
Quick Actions (IMPORTANT — read severity context first):
  • ⏳ LEARNING campaigns → Do NOT pause. Monitor for 14+ days before judging.
  • ❓ INSUFFICIENT_DATA campaigns → Need more spend before analysis is meaningful.
  • 🚨 CRITICAL campaigns (established, 14+ days, ZERO conversions) → Consider pausing
  • 🚨 CRITICAL campaigns (established, 14+ days, HAS conversions) → Review performance, verify revenue in ad platform before reducing budget
  • 🔴 HIGH severity (established, 14+ days) → Consider reducing budget by 50-70%
  • 🟡 MEDIUM → Optimize targeting, ad copy, landing pages
  • Top performers → Consider increasing budget
⚠️ NEVER say “pause” for a campaign that has conversions. Say “review” or “reduce budget” instead. ⚠️ NEVER recommend pausing a campaign in LEARNING phase. ⚠️ If ALL campaigns are LEARNING or INSUFFICIENT_DATA, tell the user their account is too new for waste analysis and recommend checking back in 2 weeks. ⚠️ Consider campaign objective: brand awareness campaigns will not have ROAS data. This is normal. ⚠️ When data confidence is MEDIUM or LOW, soften all recommendations and add verification prompts. Visualization Tip: For 10+ campaigns, suggest creating a treemap visualization to show wasted spend by campaign size. 💬 Community: For optimization discussions, visit our Discord: https://discord.gg/dH3Qt4YS

​
OpenAPI

/api-reference/openapi.json post /api/v1/tools/analyze_wasted_spend/execute