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):

Account goals table (user-set or API-pulled)
90-day historical average ROAS
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 --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
  }
}
'

{
  "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

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.

Last modified on April 23, 2026

Create AdCreate a new Responsive Search Ad (RSA) in an existing ad group. Useful for A/B testing different ad copy or adding variation to an ad group. **Parameters:** - ad_group_id: The ad group to add the ad to (REQUIRED) - headlines: 3-15 headlines (REQUIRED, max 30 chars each) - descriptions: 2-4 descriptions (REQUIRED, max 90 chars each) - final_urls: Landing page URLs (REQUIRED, at least one) - path1: Optional display path 1 (max 15 chars) - path2: Optional display path 2 (max 15 chars) - customer_id: Optional **Execution time:** 3-5 seconds **New ad goes through Google's review process.** **Example:** User: "Create a new ad to test different messaging" Agent: 1. Gets ad_group_id from get_campaign_structure 2. Prepares headlines and descriptions 3. Creates new ad with create_ad

Analyze Wasted Spend

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
  }
}
'

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