get_benchmark_context

POST https://api.adspirer.ai/api/v1/tools/get_benchmark_context/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 Get industry benchmark context for AI-powered recommendations. ⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. 🎯 **What This Tool Does (Performance Agent - Phase 1 Feature 5):** - Generates contextual benchmark data for the user's business - Combines business profile with industry benchmarks - Provides recommended ROAS targets based on vertical - Returns formatted context for AI prompts **Returns benchmark context:** - Business vertical and size context - Industry-specific ROAS benchmarks (typical, good, excellent) - CTR benchmarks by industry - CPC expectations for the vertical - Seasonality considerations - Custom recommendations based on profile **Industry Benchmarks Included:** | Vertical | Typical ROAS | Good ROAS | Excellent ROAS | |----------|--------------|-----------|----------------| | Retail | 4.0x | 6.0x | 8.0x | | Services | 3.0x | 5.0x | 7.0x | | Technology | 3.5x | 5.5x | 8.0x | | Healthcare | 2.5x | 4.0x | 6.0x | | Finance | 5.0x | 8.0x | 12.0x | | Education | 2.0x | 3.5x | 5.0x | **Parameters:** - **include_recommendations**: Include performance recommendations (default: true) - **customer_id**: Optional (uses connected account if omitted) **Use this tool when:** - Before providing performance analysis - When comparing user's metrics to industry standards - User asks "how am I doing compared to others?" - You need context for optimization recommendations **Integration with Other Tools:** Call this BEFORE or AFTER these tools for enhanced recommendations: - `analyze_wasted_spend` - Contextualize waste against industry norms - `optimize_budget_allocation` - Use industry-appropriate ROAS targets - `get_campaign_performance` - Compare metrics to benchmarks - `explain_performance_anomaly` - Understand if changes are industry-wide **Execution time:** 1-2 seconds (profile lookup + benchmark calculation)

{
  "arguments": {
    "include_recommendations": true,
    "customer_id": "string"
  }
}

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

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

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