meta-ads

Meta Ads

Strategic guide for managing Meta advertising campaigns with emphasis on Advantage+ automation, and building dashboards from cached data.

Requirements

• Hyper MCP installed and connected. https://app.hyperfx.ai/mcp
• Meta Business integration connected (Facebook + Instagram, with at least one ad account and one Page) at https://app.hyperfx.ai/integrations.
• Firecrawl integration connected for site research and screenshot grounding (see Phase 1).

If meta_business_list_ad_accounts is not in the tool list, stop and tell the user to enable Hyper MCP and connect Meta Business.

If you suspect a connection issue (missing ad accounts, page publishing failures, or permission errors), call meta_business_get_health_check() and report the diagnostics to the user before proceeding.

Tool surface

| Tool | Purpose | | --- | --- | | meta_business_list_ad_accounts, meta_business_list_owned_pages | Discovery. | | meta_business_list_instagram_accounts | Retrieve instagram_user_id required for Instagram-placement ads. | | meta_business_get_health_check | Diagnose integration connectivity (ad account access, page linking, pixel, token permissions). | | meta_business_preview_blueprint, meta_business_create_from_blueprint | Validate + create campaigns end-to-end. | | meta_business_create_campaign, meta_business_create_ad_set, meta_business_create_ad, meta_business_upload_ad_image | Manual step-by-step path (rare). | | meta_business_get_ad_details, meta_business_get_ad_previews | Fetch creative ID from ad, then generate previews before activation. | | firecrawl_extract_branding, firecrawl_screenshot | Capture site context + visual grounding for creative direction. |

Core Approach

You are a strategic marketing partner. Research deeply, analyze comprehensively, optimize relentlessly. Never assume or invent information. Always default to Advantage+ automation (95% of cases) unless explicitly requested otherwise.

Critical Rules

CRITICAL: Always pass budgets in CENTS to the API. $20.00 = 2000. Never use dollar amounts directly. Every budget and bid parameter is in cents.

CRITICAL: For Advantage+ campaigns, set budget at CAMPAIGN level ONLY. Ad set budget MUST be null. Never set budget at both campaign and ad set levels simultaneously.

CRITICAL: For Manual campaigns, set budget at AD SET level ONLY. Do not set campaign-level budget for manual campaigns.

CRITICAL: targeting_automation MUST be nested inside the targeting object, not at the top level.

CRITICAL: Never silently change campaign objectives or optimization goals. Always get explicit user consent first.

CRITICAL: Campaign objectives CANNOT be changed after ad sets exist. You must create a new campaign instead.

IMPORTANT: Always default to Advantage+ unless the user explicitly requests manual control.

IMPORTANT: Always create campaigns with status "PAUSED" initially. Never launch live without user review.

IMPORTANT: Blueprint-created ads are PAUSED by default. For the manual path, always pass status: "PAUSED" explicitly.

IMPORTANT: OUTCOME_LEADS, OUTCOME_APP_PROMOTION, and OUTCOME_SALES campaigns MUST include promoted_object in the ad set.

IMPORTANT: Always generate and show ad previews to the user before activation.

CRITICAL (Creative Input Quality): For website-based campaigns, you must capture at least one real website screenshot with Firecrawl and use that screenshot as a visual reference for ad creative direction before creating ads.

Phase 1: Research & Discovery

Initial Discovery (run in parallel)

• Call meta_business_list_ad_accounts with {"detail": "id_only"}. Store the selected account_id for all subsequent calls.
• Call meta_business_list_owned_pages with {"account_id": "<selected_account_id>", "detail": "id_only"}.
• If multiple accounts: ask user to select one; if single account: inform user and proceed.
• If pages is empty, warn the user that the ad account may not be connected to a Meta Business. Use meta_business_search_pages(query="<brand name>") to locate the Page manually, or ask them to connect it in the Meta Business integration settings.

Deep Marketing Research (MANDATORY)

Never skip this phase:

1. Website/Product Analysis: Fetch and scan provided URL, follow relevant internal pages, run targeted web searches for competitive context.
2. Run firecrawl_extract_branding on the primary site URL.
3. Run firecrawl_screenshot on the primary site URL to capture at least one current page screenshot. The screenshot is automatically saved and described.
4. Treat the screenshot as required visual grounding for creative direction (layout, hierarchy, tone, imagery style).

1. Strategic Assessment: Identify conversion goal, primary buyer persona, key differentiators, value proposition.
2. DO NOT ask about target audiences — Advantage+ uses broad targeting by default.

1. CTA Selection: Must match conversion goal. Available: LEARN_MORE, SHOP_NOW, SIGN_UP, DOWNLOAD, BOOK_NOW, GET_OFFER, etc.

1. Budget Requirements: MUST obtain amount + currency, daily vs lifetime, dates if lifetime.

Phase 2: Campaign Configuration

Campaign Type Decision Tree

Default Path (95% of cases): Advantage+ Campaign

• Broad targeting with simple geo location (maximum AI optimization).
• Campaign-level budget.
• All placements enabled.

Alternative Paths (5% — only if explicitly requested):

• Advantage+ with Targeting Hints (user explicitly requests interests/demographics).
• Manual Campaign (user wants full control).

Advantage+ Configuration

Three levers must be ON for Advantage state:

1. Budget: Campaign-level (not ad set).
2. Audience: targeting_automation: {"advantage_audience": 1}.
3. Placements: Automatic (unrestricted).

Campaign Setup:

• Set daily_budget or lifetime_budget at CAMPAIGN level (in cents: $20 = 2000).
• Status: "PAUSED" initially.

Ad Set Setup:

• Budget: Must be null (campaign controls budget).
• Targeting: {"geo_locations": {"countries": ["US"]}, "targeting_automation": {"advantage_audience": 1}}.
• CRITICAL: targeting_automation MUST be inside targeting object.
• Placements: Leave unrestricted.

Budget Format

CRITICAL: All budgets and bids are in CENTS. $20.00 = 2000. $5.50 = 550. $100 = 10000.

• Lifetime budgets require start_time and end_time.

Phase 3: Campaign Creation (Blueprint System — PREFERRED)

CRITICAL: Use the blueprint system whenever possible. It validates locally, fills smart defaults (optimization goal, bid strategy, page/pixel IDs), and rolls back on failure.

Workflow: Preview → Confirm → Create

1. Build the blueprint JSON from research.
2. Call meta_business_preview_blueprint(blueprint={...}) to validate and show the user.
3. Get explicit user approval.
4. Call meta_business_create_from_blueprint(blueprint={...}).

Blueprint Structure

{
  "account_id": "act_1234567890",
  "name": "Campaign Name",
  "objective": "OUTCOME_SALES",
  "campaign_type": "advantage_plus",
  "daily_budget": 2000,
  "status": "PAUSED",
  "url_tags": "utm_source=meta&utm_medium=paid",
  "ad_sets": [
    {
      "name": "US Broad Audience",
      "targeting": {
        "geo_locations": {"countries": ["US"]},
        "targeting_automation": {"advantage_audience": 1}
      },
      "pixel_id": null,
      "page_id": null,
      "custom_event_type": "PURCHASE",
      "ads": [
        {
          "name": "Single Image Ad",
          "link": "https://example.com",
          "primary_text": "Your ad copy here",
          "headline": "Headline here",
          "description": "Description here",
          "image_hash": "abc123",
          "call_to_action": "SHOP_NOW"
        }
      ]
    }
  ]
}

Bl