create_search_campaign

POST https://api.adspirer.ai/api/v1/tools/create_search_campaign/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 🔄 LONG-RUNNING TOOL: Creates a Google Ads Search campaign with full structure. Emits MCP progress updates during authentication and campaign creation (typically 5-10 seconds). Progress stages: validate → commit. ⚠️ CRITICAL WARNING ⚠️ - Call this tool ONLY ONCE per campaign - Creates REAL campaigns that cost REAL money - Do NOT retry automatically if errors occur - Report errors to user instead of retrying ⚠️ GOOGLE ADS POLICY NOTE: Avoid keywords related to health conditions, medical treatments, financial hardship, or political topics. These may trigger policy violations. Use general service terms instead. Example: Use "senior care services" not "nursing care", "home services" not "medical services" YOUR ROLE: Expert Google Ads Campaign Strategist BEFORE calling this tool, YOU MUST: 1. **Research the business thoroughly:** - Understand products/services, target audience, value propositions - Analyze competitive landscape and market positioning - Review website messaging and offers - Consider seasonal factors and current trends 2. **🔍 KEYWORD RESEARCH (CRITICAL - Call research_keywords tool FIRST):** Do NOT use generic SEO keywords. Get HIGH-INTENT keywords with real CPC data! **YOU MUST call the research_keywords tool BEFORE this tool:** Steps: a) Call the research_keywords tool: ``` Tool: research_keywords Arguments: { "business_description": "Emergency plumbing services for homeowners", "website_url": "https://example.com", "target_location": "New York, NY" } ``` b) The tool will return: - Keyword table with dynamic CPC thresholds (adapts to industry) - HIGH/MEDIUM/LOW intent keywords - Budget recommendations (Conservative/Moderate/Aggressive) - Top 15-20 recommended keywords c) Show the keyword table to the user d) Ask user if they want to modify keyword selection: - Can add/remove specific keywords - Can use only HIGH intent keywords - Default: use recommended keywords e) Extract keyword texts from the research_keywords result - Use the recommended keywords for this tool's 'keywords' parameter - Max 15-20 keywords per ad group - Will use BROAD match automatically (Google's 2025 recommendation) 3. **Analyze Target Demographics:** For each ad group, consider who the ideal customer is: - **Age**: What age groups are most likely to buy? (e.g., luxury products → 35-54, gaming → 18-34) - **Gender**: Is the product/service gender-specific? (e.g., women's fashion → FEMALE) - **Income**: What income level can afford this? (e.g., luxury → TOP_10/80_90, budget → 0_50/50_60) **Examples:** - Luxury watches: Males 35-54, income top 20% - Budget fashion: Females 18-34, all income levels - Senior services: Age 65+, income 50%+ - Gaming products: 18-34, all genders, middle income If unclear, leave demographics empty for broad reach. 3. **Generate complete campaign structure with ALL details:** **Required Fields (all mandatory):** 1. **campaign_name** - Unique descriptive name 2. **business_description** - What the business sells 3. **website_url** - Landing page URL 4. **budget_daily** - Daily budget in the account's native currency (do NOT convert — pass user's amount as-is) 5. **target_locations** - Geographic targets (cities/states/countries) 6. **ad_groups** - Array of 2-4 ad groups, each containing: - name: Ad group theme (e.g., "Premium Care Services") - keywords: 15-20 keywords from Keyword Planner research (will use BROAD match - Google's 2025 recommendation) - headlines: Exactly 15 headlines (MAXIMUM 30 chars each - NO EXCEPTIONS) - descriptions: Exactly 4 descriptions (MAXIMUM 80 chars each - NO EXCEPTIONS) - final_url: Landing page for this ad group - sitelinks (optional): 2-4 additional links below ad - audiences (optional): Demographics and audience targeting - demographics: {age_ranges: [...], genders: [...], income_ranges: [...]} - custom_audiences: [...], in_market_audiences: [...], affinity_audiences: [...] 7. **negative_keywords** (optional) - Terms to exclude **🚨 CRITICAL CHARACTER LIMITS - COUNT BEFORE CALLING 🚨** - **Headlines:** MAXIMUM 30 characters (NO EXCEPTIONS - will be rejected!) - **Descriptions:** MAXIMUM 80 characters (NO EXCEPTIONS - will be rejected!) - **Long Headlines (PMAX):** MAXIMUM 90 characters (NO EXCEPTIONS - will be rejected!) - Generate ALL content BEFORE calling this tool - COUNT the characters in each headline and description - If ANY exceed limits, you MUST shorten them BEFORE calling - Do NOT rely on retry - fix it the first time! - ✅ Commas ARE ALLOWED and encouraged for natural language - ❌ Do NOT use pipes (|) as separators - they will appear literally in ads - ❌ Do NOT send comma-delimited strings - use proper JSON arrays - Example: ["Expert Care, 24/7 Support", "Premium Service Available"] - Do NOT call this tool multiple times - it creates REAL campaigns - If errors occur, show them to the user - do NOT retry automatically - Each call costs money and creates actual Google Ads campaigns **SITELINK RULES (if using):** ⚠️ Google will REJECT sitelinks that violate these rules: - ALL sitelink URLs MUST be same domain as final_url ✅ Good: final_url='https://example.com' → sitelink='https://example.com/shipping' ❌ Bad: final_url='https://example.com' → sitelink='https://different-site.com' - Each sitelink must link to a UNIQUE, WORKING page (no duplicates, no 404s) - Link text must be DESCRIPTIVE (not "Click Here", "Learn More") - If you add description1, you MUST also add description2 - Only add sitelinks if you've verified the URLs exist and work **Execution Time:** 15-30 seconds **What happens:** - Campaign created immediately in Google Ads - Real money will be spent on the campaign - Returns campaign_id for tracking **Use for:** - Launching new advertising campaigns - Testing new market segments - Scaling successful products

{
  "arguments": {
    "campaign_name": "string",
    "business_description": "string",
    "website_url": "https://example.com",
    "budget_daily": 1.0,
    "target_locations": [
      "string"
    ],
    "ad_groups": [
      {
        "name": "string",
        "keywords": [
          "string"
        ],
        "headlines": [
          "string"
        ],
        "descriptions": [
          "string"
        ],
        "final_url": "https://example.com",
        "sitelinks": [
          {
            "link_text": null,
            "final_url": null,
            "description1": null,
            "description2": null
          }
        ],
        "audiences": {
          "demographics": null,
          "custom_audiences": null,
          "in_market_audiences": null,
          "affinity_audiences": null
        }
      }
    ],
    "negative_keywords": [
      "string"
    ],
    "bidding_strategy": "MAXIMIZE_CONVERSIONS",
    "objective": "CONVERSIONS",
    "target_roas": 1.0,
    "customer_id": "string"
  }
}

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

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

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