Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.adspirer.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Exact tool sequences for campaign creation, optimization, and analysis. These are the workflows that agent skills enforce automatically.

​
1. Performance Analysis (Cross-Platform)

Pull metrics from all connected ad platforms and present a unified view.

​
Tool Sequence

1. get_connections_status → confirm which platforms are connected
2. get_campaign_performance (Google Ads)
3. get_meta_campaign_performance (Meta Ads)
4. get_linkedin_campaign_performance (LinkedIn Ads)
5. get_tiktok_campaign_performance (TikTok Ads)
   → run in parallel if multi-platform
6. Present side-by-side comparison table

​
Output Format

Results should be formatted as a table with columns: Platform, Spend, Conversions, CPA, ROAS, CTR.

​
Deep Analysis Tools (Optional)

  • analyze_wasted_spend (Google), analyze_meta_wasted_spend (Meta), analyze_linkedin_wasted_spend (LinkedIn) — Find campaigns wasting spend. Campaigns in learning phase (< 14 days) or with insufficient data (< $20 spend) are excluded from waste totals automatically.
  • detect_meta_creative_fatigue (Meta) — Identify declining ad performance
  • explain_performance_anomaly (any platform) — Diagnose sudden CPA spikes or CTR drops

​
2. Google Search Campaign Creation

Five-step workflow. Skip a step = campaign creation fails.

​
Tool Sequence

1. get_connections_status → verify Google Ads is connected
2. research_keywords → input: business_description, seed_keywords, target_location
                      → output: keyword suggestions with real CPC data
3. discover_existing_assets → check if user has images/headlines in Google Ads already
4. suggest_ad_content (if new assets needed) → generate headlines, descriptions within character limits
5. validate_and_prepare_assets → verify assets meet Google's requirements
6. create_search_campaign → campaign created PAUSED
7. ASK USER FOR CONFIRMATION before proceeding

​
Key Parameters

  • research_keywords: business_description, seed_keywords, target_location (e.g., “United States”)
  • create_search_campaign: campaign_name, daily_budget (min $10), asset_bundle, targeting

​
Safety Rules

  • Never skip keyword research (even if user provides keywords — validate CPC data)
  • Always validate assets before campaign creation
  • Campaign is created PAUSED — user reviews before launching

​
3. Google PMax Campaign Creation

Performance Max campaigns require high-quality assets plus optional search themes and audience signals for targeting.

​
Tool Sequence

1. get_connections_status
2. discover_existing_assets → check for high-quality images, videos, logos
3. help_user_upload (if assets missing) → guide user to upload to Merchant Center or provide URLs
4. validate_and_prepare_assets → PMax requires: 5+ images, 1+ video, 5+ headlines, 5+ descriptions
5. create_pmax_campaign → campaign created PAUSED
6. add_pmax_search_themes → add up to 50 search themes to guide targeting (recommended)
7. search_audiences → find relevant in-market, affinity, and custom audiences
8. add_pmax_audience_signal → combine audience segments into a targeting signal (recommended)
9. ASK USER FOR CONFIRMATION

​
Asset Requirements

  • Minimum 5 images (1200x628px landscape + 1200x1200px square)
  • Minimum 1 video (under 30 seconds recommended)
  • 5 headlines (max 30 chars each)
  • 5 descriptions (max 90 chars each)
  • 1 logo (1200x1200px)

​
Search Themes (PMax Only)

Search themes are short phrases (max 50 per asset group) that tell Google which search queries your PMax campaign should target. They supplement Google’s automated targeting with explicit intent signals.
  • Derive themes from keyword research, search term reports, and brand context
  • Max 50 themes per asset group
  • Only support add and remove (no update — remove + re-add instead)
  • Tools: add_pmax_search_themes, get_pmax_search_themes, remove_pmax_search_themes

​
Audience Signals (PMax Only)

Audience signals tell Google which audience segments are most likely to convert. They are signals, not hard targeting — Google uses them as starting points and expands from there.
  • Only one audience signal per asset group (combine multiple segments in one signal)
  • Supported types: in-market audiences, affinity audiences, custom audiences, user lists (remarketing)
  • Use search_audiences to find audience IDs by keyword
  • Tools: add_pmax_audience_signal, get_pmax_audience_signals, remove_pmax_audience_signal

​
4. Google Display Campaign Creation

Six-step workflow for standard Display (full manual targeting) and Smart Display (Google-managed). See the Display Ads guide for complete details.

​
Tool Sequence

1. get_connections_status → verify Google Ads is connected
2. resolve_google_locations → names → exact geoTargetConstants/<id>
                             → rejects ambiguity ("Baja" surfaces 5 candidates)
3. list_google_languages → validate ISO language codes
4. search_audiences (standard Display, if using audience targeting)
   → find real in-market / affinity / custom audience IDs
5. Prepare creative: 1-5 short headlines ≤30 chars, 1 long headline ≤90,
                     1-5 descriptions ≤90, ≥1 landscape + ≥1 square image
6. create_display_campaign → campaign + ad group + RDA created PAUSED
7. add_sitelinks + add_callout_extensions + add_structured_snippets
8. ASK USER FOR CONFIRMATION

​
Targeting Surfaces (Standard Display)

Five independent surfaces that intersect — mix and match:
  • Audiences — in-market, affinity, custom, user lists (use search_audiences)
  • Topics — Google content categories
  • Managed placements — specific websites, apps, YouTube channels/videos
  • Display keywords — contextual (always BROAD match)
  • Demographics — age, gender, parental status, income exclusions
Each surface has GET / ADD / REMOVE tools, plus a unified remove_display_criteria for cleanup.

​
Smart Display Rules

  • Requires bidding_strategy=TARGET_CPA + target_cpa set
  • Requires 50+ Display conversions in the last 30 days
  • Rejects manual targeting fields — fully Google-managed
  • Set smart_display=true on create_display_campaign

​
Safety Rules

  • ALWAYS resolve locations + languages before creation — no silent US fallback
  • Never fabricate audience IDs — run search_audiences first
  • Smart Display + manual targeting is rejected; use one or the other
  • Campaign created PAUSED — user reviews before launching

​
5. Meta Campaign Creation

Six-step workflow for Facebook & Instagram campaigns.

​
Tool Sequence

1. get_connections_status → verify Meta Ads is connected
2. search_meta_targeting → find audiences by interests, demographics, behaviors
                         → output: targeting options with audience size estimates
3. select_meta_campaign_type → image, video, or carousel based on user's creative
4. discover_meta_assets → check existing creatives in Meta
5. validate_and_prepare_meta_assets → verify image/video URLs meet Meta requirements
6. create_meta_image_campaign | create_meta_video_campaign | create_meta_carousel_campaign
   → campaign created PAUSED
7. ASK USER FOR CONFIRMATION

​
Creative Requirements by Type

  • Image: 1080x1080px, JPG/PNG, under 30MB
  • Video: 1080x1080px, MP4/MOV, under 4GB, 1-240 seconds
  • Carousel: 2-10 cards, each 1080x1080px

​
Ad Copy Tips

  • Use emojis, line breaks (\n), and bullet points (•, ✅, ▸) in primary_text for higher engagement
  • primary_text max 125 characters, headline max 40 characters
  • For location targeting, use search_meta_targeting with search_type='location' to find cities, regions, or zip codes — pass the returned objects directly to campaign creation

​
Safety Rules

  • Creative assets must be provided as URLs (Google Drive, Dropbox, S3)
  • Validate creative URLs are publicly accessible before campaign creation
  • Minimum $5/day budget per ad set

​
6. LinkedIn Campaign Creation

Five-step workflow for B2B sponsored content.

​
Tool Sequence

1. get_linkedin_organizations → list user's company pages, select one to advertise under
2. search_linkedin_targeting | research_business_for_linkedin_targeting
   → find B2B audiences by job title, industry, company size, seniority
   → output: targeting options with audience size
3. discover_linkedin_assets → check existing creatives
4. validate_and_prepare_linkedin_assets → verify images meet LinkedIn requirements
5. create_linkedin_image_campaign → campaign created PAUSED
6. ASK USER FOR CONFIRMATION

​
Targeting Best Practices

  • Combine job titles + industries (e.g., “Marketing Manager” + “Computer Software”)
  • Add seniority filter for decision-makers (Director, VP, C-level)
  • Use company size to match your ICP (Ideal Customer Profile)
  • Minimum audience size: 300 members (LinkedIn requirement)

​
Safety Rules

  • Must select organization first (no org = campaign creation fails)
  • Minimum $10/day budget
  • Image dimensions: 1200x627px or 1200x1200px

​
7. TikTok Campaign Creation

Three-step workflow (simpler than other platforms).

​
Tool Sequence

1. get_connections_status → verify TikTok Ads is connected
2. discover_tiktok_assets → check existing videos
3. validate_and_prepare_tiktok_assets → verify video meets TikTok requirements: 9:16 vertical, 5-60 seconds
4. create_tiktok_campaign → campaign created PAUSED
5. ASK USER FOR CONFIRMATION

​
Creative Requirements

  • Vertical video: 9:16 aspect ratio (1080x1920px)
  • Duration: 5-60 seconds (9-15 seconds performs best)
  • Format: MP4 or MOV
  • File size: Under 500MB

​
8. Budget Optimization Workflow

Reallocate spend based on performance data.

​
Tool Sequence

1. get_campaign_performance → pull last 30 days
2. optimize_budget_allocation (Google)
   OR optimize_meta_budget (Meta)
   OR optimize_linkedin_budget (LinkedIn)
   → analyzes ROAS or CPA, suggests reallocation
3. Present recommendations in table:
   - Current budget allocation
   - Recommended budget allocation
   - Expected impact (conversions gained)
4. ASK USER FOR APPROVAL before executing changes

​
Optimization Logic

  • Shift budget from low-ROAS campaigns to high-ROAS campaigns
  • Increase spend on campaigns with CPA below target
  • Decrease or pause campaigns with CPA 2x+ above target
  • Maintain minimum budgets per platform (10Google/LinkedIn,10 Google/LinkedIn, 5 Meta)

​
9. Account Management Workflow

Managing multiple ad accounts and checking system status.

​
Tool Sequence

1. get_connections_status → shows all connected platforms and account IDs
2. switch_primary_account (if managing multiple accounts) → change active account for subsequent tool calls
3. get_usage_status → check Adspirer plan limits: tool calls used/remaining
4. get_business_profile → view user's Adspirer account details

​
When to Use

  • At the start of every session (verify correct account is active)
  • Before creating campaigns (confirm you’re in the right ad account)
  • When switching between client accounts (agencies managing multiple advertisers)

​
10. Automation & Proactive Monitoring

Schedule recurring tasks, set alerts, and use the Watch Agent for proactive campaign monitoring.

​
Watch Agent (Proactive Signal)

The Watch Agent runs automatically in the background every 15 minutes, scanning your connected ad accounts for issues. When it finds something actionable, it emails you a copy-paste prompt to act on it immediately. Tool Sequence — on-demand scan: 
1. run_watch_now → kicks off a Watch Agent session right now (async)
2. [email arrives with signal_id and re-entry prompt]
3. get_signal_briefing(signal_id) → advisory + pre-staged fix actions
4. apply_signal_actions(signal_id) → execute the fixes (with confirmation)
Managing staged actions: 
1. list_pending_actions → see all Watch Agent staged fixes waiting for approval
2. manage_action(action_id, decision="approve") → approve one action
   OR apply_signal_actions(signal_id) → approve all staged actions for a finding

​
Monitors & Alerts

Tool Sequence — create a metric alert: 
1. create_monitor(metric, operator, threshold) → set the alert
   OR use the Monitors web UI at adspirer.ai/monitors
2. list_monitors → verify it's active
3. [alert fires when threshold is crossed, email sent]
4. get_monitor_history(alert_id) → see all past trigger events
   test_monitor(alert_id) → dry-run against today's data

​
Scheduled Briefs

1. schedule_brief(delivery_destination, schedule_type, time, platforms)
   → set up daily or weekly email report (now includes PDF attachment)
2. list_scheduled_tasks → see all active briefs and monitors
3. manage_scheduled_task(task_id, action="pause") → pause, resume, or delete

​
Example: Daily Performance Brief

Daily Performance Brief
schedule_brief(
  name="Morning Standup Brief",
  delivery_destination="team@company.com",
  schedule_type="daily",
  time="08:00",
  timezone="America/New_York",
  platforms=["google_ads", "meta_ads", "linkedin_ads"]
)

​
Example: CPA Spike Monitor

CPA Spike Alert
create_monitor(
  metric="cpa",
  operator="greater_than",
  threshold=50,        # alert if CPA exceeds $50
  consecutive_days=2,  # only alert if it stays above for 2 days (reduces noise)
  platforms=["google_ads"]
)

​
Example: On-Demand Watch Agent Scan

"Run the watch agent on my accounts now"
→ run_watch_now()
→ [email arrives] "Show me the briefing for signal abc123"
→ get_signal_briefing(signal_id="abc123")
→ "Apply the staged fixes"
→ apply_signal_actions(signal_id="abc123")

​
Workflow Principles

These rules apply to ALL workflows:
  1. Always start with connections check: Run get_connections_status before platform-specific tools
  2. Read before write: Research/validate before creating campaigns
  3. User confirmation required: Ask before any action that affects spend
  4. Campaigns created PAUSED: User reviews before launching live
  5. Never retry on error: Report failures, don’t auto-retry campaign creation
  6. Format results as tables: Make data scannable (columns: metric name, value, change vs. previous period)

​
Input Format Rules

  • IDs must be strings: Pass all IDs (campaign_id, video_id, ad_account_id, etc.) as quoted strings, never bare integers
  • Never modify IDs: Copy IDs exactly as returned by list/discover tools — do not round or change digits
  • Respect text limits: Google headline max 30 chars, description max 90, Meta primary_text max 125. Meta primary_text supports emojis and line breaks
  • Enum casing: The server auto-normalizes, but prefer uppercase for status/objective/match_type and lowercase for date_range/campaign_type
  • Budgets are numbers: Pass as numbers in account’s local currency (not cents, not strings)
  • Keywords as objects: add_negative_keywords expects [{"text": "free", "match_type": "BROAD"}], not ["free"]
See Tool Catalog — Input Format Requirements for full details.
Last modified on May 21, 2026