Analyze Wasted Spend

Analyze wasted ad spend and identify campaigns losing money or underperforming.

⚠️ 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

POST /api/v1/tools/analyze_wasted_spend/execute

Analyze Wasted Spend

cURL

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/analyze_wasted_spend/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "date_range": "string",
    "end_date": "string",
    "lookback_days": 30,
    "raw_data": false,
    "start_date": "string",
    "target_roas": 1
  }
}
'

200

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

Authorizations

Authorization · string · header · required

API key from https://adspirer.ai/keys. Prefix sk_live_. Treat as a secret — never commit.

Headers

Idempotency-Key · string<uuid>

Client-generated UUID to make writes idempotent. Strongly recommended for write tools. A repeat call with the same key returns the cached result instead of re-executing. Example: 550e8400-e29b-41d4-a716-446655440000

Body

application/json

All tool arguments are wrapped in an arguments object. The fields accepted inside arguments are listed below — required fields are marked with a red asterisk.

arguments · object · required

Show child attributes

Response

200

application/json

Tool executed successfully. data.text carries the human-readable result (markdown-friendly). data.quota shows your current usage against the plan limit. data.structured appears when the tool emits machine-parseable structured content. data.content appears for tools that return non-text blocks (images, resources).

Returned on HTTP 200. data.text is the primary human-readable output. data.quota is always present for billable calls. data.structured is set only when the tool emits machine-parseable structured content. data.content is set only when the tool emits non-text content blocks.

data · object · required

Show child attributes

success · boolean · required

tool · string · required

Echoed tool_name from the request URL.