> ## 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.
# Adspirer Tool Catalog: 400+ MCP Tools by Platform
> Complete reference of all 400+ Adspirer tools. Organized by platform (Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, TikTok Ads) with types, descriptions, and parameters.
## Tool Types
* Read Safe to run anytime. Pulls data, analyzes performance, provides insights. No spending impact.
* Write Requires user confirmation. Creates campaigns, updates budgets, modifies targeting. Affects spend.
## How the agent reaches these tools
Adspirer exposes a small set of top-level tools. Most of the tools listed on this page sit **behind
a platform router** — `google_ads`, `meta_ads`, `linkedin_ads`, `tiktok_ads`, `amazon_ads`,
`chatgpt_ads` — and are reached in two steps:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
// 1. Discover. Always free — never counts against your quota.
{ "action": "list_tools" }
// 2. Execute, using an exact tool name from step 1.
{ "action": "execute", "tool_name": "create_search_campaign", "arguments": { "...": "..." } }
```
Only these tools are callable directly by name: `start_here`, `search_tools`, `get_tool_schema`,
`get_connections_status`, `get_usage_status`, `switch_primary_account`, `get_campaign_performance`,
`get_meta_campaign_performance`, `audit_conversion_tracking`, and `echo_test`.
Everything else in this catalog goes through its platform router. Calling a routed tool by name
returns "tool not found."
`search_tools` finds the right tool from a plain-English description, and `get_tool_schema` returns
its exact live signature. Both are top-level: they are never wrapped in `action: "execute"`.
The [`adspirer-mcp` skill](/agent-skills/skills) teaches this contract to your assistant, along with
the per-platform account ids and budget units.
## Google Ads Tools (147)
| Tool Name | Type | Description |
| ----------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_campaign_performance` | Read | Pull metrics for campaigns (spend, conversions, CPA, ROAS) |
| `research_keywords` | Read | Find keywords with real CPC data from Google Keyword Planner |
| `create_search_campaign` | Write | Launch Google Search campaign (created PAUSED) |
| `create_pmax_campaign` | Write | Launch Performance Max campaign (created PAUSED) |
| `analyze_wasted_spend` | Read | Find campaigns with wasted spend. Excludes learning-phase (\< 14 days) and insufficient-data (\< \$20 spend) campaigns from waste totals. |
| `optimize_budget_allocation` | Read | Recommend budget shifts based on ROAS/CPA |
| `analyze_search_terms` | Read | Review actual search queries triggering your ads |
| `discover_existing_assets` | Read | Check if account has images/headlines/descriptions |
| `suggest_ad_content` | Read | Generate ad headlines and descriptions (Google char limits) |
| `validate_and_prepare_assets` | Read | Verify assets meet Google's requirements before campaign creation |
| `update_campaign_budget` | Write | Change daily budget for existing campaigns |
| `pause_campaign` | Write | Stop campaigns or ad groups |
| `resume_campaign` | Write | Restart paused campaigns |
| `add_negative_keywords` | Write | Block irrelevant search terms |
| `add_sitelinks` | Write | Add sitelink extensions (accepts `text`/`headline` + `url`/`link` field names) |
| `remove_sitelinks` | Write | Remove sitelink extensions from a campaign |
| `add_callout_extensions` | Write | Add callout extensions (short promotional blurbs) |
| `remove_callouts` | Write | Remove callout extensions from a campaign |
| `add_structured_snippets` | Write | Add structured snippet extensions (header + values) |
| `remove_structured_snippets` | Write | Remove structured snippet extensions from a campaign |
| `list_campaign_extensions` | Read | List sitelinks, callouts, and structured snippets on a campaign |
| `update_bid_strategy` | Write | Change a campaign's bid strategy; detects shared portfolio strategies and surfaces Smart Bidding prerequisites |
| `explain_performance_anomaly` | Read | Diagnose sudden CPA spikes or CTR drops |
| `help_user_upload` | Read | Guide user through asset upload process |
| `add_pmax_search_themes` | Write | Add search themes to a PMax campaign's asset group (max 50). Guides Google's automated targeting. |
| `get_pmax_search_themes` | Read | View current search themes on a PMax campaign (max 50 per asset group) |
| `remove_pmax_search_themes` | Write | Remove specific search themes from a PMax campaign |
| `add_pmax_audience_signal` | Write | Add audience signal to PMax campaign. Combines in-market, affinity, custom audiences, and user lists. |
| `get_pmax_audience_signals` | Read | View current audience signals on a PMax campaign |
| `remove_pmax_audience_signal` | Write | Remove an audience signal from a PMax campaign |
| `search_audiences` | Read | Search Google Ads audiences by keyword across in-market, affinity, and custom types |
| `get_campaign_targeting` | Read | View location and language targeting on existing campaigns |
| `pause_ad_group` | Write | Pause an individual ad group within a campaign |
| `resume_ad_group` | Write | Resume a paused ad group |
| `update_campaign` | Write | Update campaign settings: language, locations, Search Partners, Display Expansion, audience targeting mode, AI Max |
| `add_business_name_asset` | Write | Attach a business name asset to a Search campaign (max 25 characters) |
| `add_call_asset` | Write | Attach a phone number call asset with optional call conversion tracking |
| `add_search_campaign_image` | Write | Attach image assets (logos, marketing images) to Search campaigns |
| `list_conversion_actions` | Read | List all conversion actions in the account (purchases, form fills, calls) with status and tracking method |
| `get_conversion_action_performance` | Read | Pull conversion volume, value, and CPA broken down by conversion action — see which actions drive results |
| `get_ad_performance` | Read | Per-ad metrics (Search/Display/Demand Gen/YouTube) with head-to-head comparison and ad-strength |
| `get_ad_creative` | Read | Export an ad's headlines, descriptions, images, YouTube videos, and carousel cards |
| `link_merchant_center` | Write | Link a Google Merchant Center feed to enable Shopping |
| `get_merchant_center_links` | Read | List linked Merchant Center accounts |
| `create_shopping_campaign` | Write | Launch a Standard Shopping campaign from a Merchant Center feed (created PAUSED) |
| `add_shopping_ad_group` | Write | Add an ad group to a Shopping campaign |
| `add_shopping_product_ad` | Write | Add the product ad that surfaces feed items |
| `add_product_group` | Write | Build the product partition tree (subdivide by brand/category/item and bid per partition) |
| `create_app_campaign` | Write | Launch a Universal App campaign — installs, engagement, or pre-registration (created PAUSED) |
| `create_demandgen_campaign` | Write | Launch a Demand Gen campaign across YouTube, Shorts, Discover, and Gmail (created PAUSED) |
| `add_pmax_asset_group` | Write | Add an asset group to a Performance Max campaign |
| `get_pmax_asset_performance` | Read | See which PMax assets Google rates Best / Good / Low |
| ...and more | | Shopping product partitions, App/UAC creative, Demand Gen audiences & channel controls, PMax asset-group management, ad-group device/schedule bid modifiers, campaign labels, frequency caps, geographic targeting, and additional Google Ads tools |
## LinkedIn Ads Tools (55)
| Tool Name | Type | Description |
| ------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_linkedin_campaign_performance` | Read | Pull metrics for LinkedIn campaigns (spend, clicks, conversions, cost per lead) |
| `get_linkedin_organizations` | Read | List user's LinkedIn company pages (required before campaign creation) |
| `search_linkedin_targeting` | Read | Find B2B audiences by job title, industry, company size, seniority |
| `research_business_for_linkedin_targeting` | Read | Input competitor name, get targeting suggestions |
| `create_linkedin_image_campaign` | Write | Launch sponsored content campaign (created PAUSED). Supports campaign groups and creative naming. |
| `add_linkedin_campaign_to_group` | Write | Add a campaign to an existing campaign group |
| `add_linkedin_carousel_creative` | Write | Add carousel creative variations to campaigns |
| `discover_linkedin_assets` | Read | Check existing creatives in LinkedIn (includes videos uploaded via Campaign Manager) |
| `validate_and_prepare_linkedin_assets` | Read | Verify images meet LinkedIn requirements (1200x627px or 1200x1200px) |
| `add_linkedin_creative` | Write | Add new sponsored posts to existing campaigns |
| `analyze_linkedin_creative_performance` | Read | See which images/copy combinations perform best |
| `optimize_linkedin_budget` | Read | Recommend budget reallocation based on cost per lead |
| `update_linkedin_campaign` | Write | Change budgets, bids, or targeting |
| `pause_linkedin_campaign` | Write | Stop campaigns or ad groups |
| `explain_linkedin_anomaly` | Read | Diagnose sudden CTR, CPC, or conversion rate changes |
| `manage_linkedin_conversions` | Write | Set up and track conversion events (form fills, downloads) |
| `create_linkedin_video_campaign` | Write | Launch a video sponsored content campaign (created PAUSED) |
| `create_linkedin_carousel_campaign` | Write | Launch a multi-card carousel campaign (created PAUSED) |
| `create_linkedin_text_campaign` | Write | Launch a text ad campaign (created PAUSED) |
| `create_linkedin_campaign_group` | Write | Create a campaign group with a shared budget/schedule |
| `estimate_linkedin_audience_size` | Read | Estimate reachable audience size for a targeting spec before launch |
| `forecast_linkedin_campaign_supply` | Read | Forecast impressions, clicks, and spend at a given budget |
| `get_linkedin_audience_insights` | Read | See which job functions, industries, and seniorities engage |
| `clone_linkedin_campaign` | Write | Duplicate a campaign with optional changes |
| ...and more | | Video/text/carousel creatives, campaign-group batch operations, archive/reactivate/delete, engagement metrics, wasted-spend analysis, AI creative generation, and additional LinkedIn tools |
## Meta Ads Tools (54)
| Tool Name | Type | Description |
| ----------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_meta_campaign_performance` | Read | Pull metrics for Meta campaigns (Facebook + Instagram) |
| `search_meta_targeting` | Read | Find audiences by interests, demographics, behaviors |
| `select_meta_campaign_type` | Read | Choose: Image, Video, or Carousel based on creative assets |
| `discover_meta_assets` | Read | Check existing creatives in Meta |
| `validate_and_prepare_meta_assets` | Read | Verify image/video URLs meet Meta requirements (dimensions, file size) |
| `create_meta_image_campaign` | Write | Launch single-image campaign (created PAUSED) |
| `create_meta_video_campaign` | Write | Launch video campaign (created PAUSED) |
| `create_meta_carousel_campaign` | Write | Launch multi-card carousel campaign (created PAUSED) |
| `analyze_meta_ad_performance` | Read | Deep analysis of ad-level performance with recommendations |
| `analyze_meta_audiences` | Read | See which audience segments perform best (age, gender, interests) |
| `detect_meta_creative_fatigue` | Read | Identify ads losing effectiveness over time (declining CTR after 14+ days) |
| `optimize_meta_budget` | Read | Recommend budget reallocation based on ROAS/CPA |
| `optimize_meta_placements` | Read | Shift spend to best-performing placements (Feed, Stories, Reels) |
| `explain_meta_anomaly` | Read | Diagnose sudden CPA spikes or CTR drops |
| `update_meta_campaign` | Write | Change budgets, bids, or targeting |
| `pause_meta_campaign` | Write | Stop campaigns or ad sets |
| `browse_meta_targeting` | Read | Explore Meta's targeting categories |
| `list_meta_custom_audiences` | Read | View custom audiences (database lists, lookalikes, website, engagement) |
| `add_meta_ad_set` | Write | Add ad sets to existing campaigns (lifetime budgets, end dates, placements) |
| `add_meta_ad` | Write | Add ads to existing ad sets |
| `analyze_meta_wasted_spend` | Read | Identify campaigns with poor ROAS and recommend cuts |
| `get_meta_audience_insights` | Read | Audience breakdown by age, gender, and interests |
| `resume_meta_campaign` | Write | Restart paused campaigns |
| `list_meta_campaigns` | Read | List all campaigns with status and budget |
| `get_meta_campaign_details` | Read | Detailed campaign info |
| `list_meta_ad_sets` | Read | List ad sets in a campaign |
| `list_meta_ads` | Read | List ads in an ad set |
| `update_meta_ad_set` | Write | Update ad set budgets, targeting, or schedule |
| `update_meta_ad` | Write | Update ad creative or status |
| `get_meta_ad_creatives` | Read | View creative details for ads |
| `create_meta_dco_ad` | Write | Create dynamic creative optimization ads |
| `duplicate_meta_campaign` | Write | Duplicate an existing campaign |
| `list_meta_lead_forms` | Read | View lead forms in your ad account |
| `get_meta_lead_form_submissions` | Read | Pull lead submissions from a form |
| `list_meta_instagram_accounts` | Read | View connected Instagram accounts |
| `list_meta_pixels` | Read | View Meta Pixels in your ad account |
| `get_meta_adset_performance` | Read | Pull spend, clicks, CTR, CPA, ROAS, and conversions broken down by ad set within a campaign — middle layer between campaign and ad performance |
| `list_meta_catalogs` | Read | List product catalogs available to the ad account (Advantage+ Catalog / DPA) |
| `list_meta_products` | Read | Browse products inside a catalog |
| `list_meta_product_sets` | Read | View product sets (targetable subsets of a catalog) |
| `create_meta_product_set` | Write | Create a product set with filter rules (e.g. "best sellers under \$50") |
| `validate_catalog_readiness` | Read | Pre-flight check: is the catalog + pixel data ready for retargeting or prospecting only? |
| `create_meta_catalog_campaign` | Write | Launch an Advantage+ Catalog (dynamic product ads) campaign (created PAUSED) |
| `add_meta_catalog_ad_set` | Write | Add a catalog ad set (audience, budget, retargeting window) |
| `add_meta_catalog_ad` | Write | Add a catalog ad (creative format + product set) |
| `analyze_meta_catalog_performance` | Read | Product-level performance across the catalog |
| `get_meta_product_performance` | Read | Per-product spend, sales, and ROAS |
| `detect_meta_catalog_waste` | Read | Flag products burning budget with no return |
| `diagnose_meta_catalog_funnel` | Read | Walk the catalog funnel (view → add-to-cart → purchase) to find leaks |
| `compare_meta_catalog_product_sets` | Read | Compare performance across product sets |
| ...and more | | Catalog campaign/ad-set/ad updates and additional Meta tools |
## TikTok Ads Tools (37)
| Tool Name | Type | Description |
| ------------------------------------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_tiktok_campaign_performance` | Read | Campaign summary with TikTok-specific video and engagement metrics |
| `get_tiktok_ad_performance` | Read | Ad-level analysis with hook rate, video completion, and engagement |
| `analyze_tiktok_wasted_spend` | Read | ROAS-based waste detection with campaign status awareness |
| `optimize_tiktok_budget` | Read | Budget allocation recommendations based on performance |
| `detect_tiktok_creative_fatigue` | Read | Hook rate decline as the primary fatigue signal |
| `explain_tiktok_anomaly` | Read | Diagnose sudden changes in TikTok campaign performance |
| `get_tiktok_audience_insights` | Read | Age/gender breakdown with CPA ranking |
| `analyze_tiktok_geo_performance` | Read | Country-level performance analysis |
| `discover_tiktok_assets` | Read | Check existing videos in TikTok |
| `validate_and_prepare_tiktok_assets` | Read | Verify videos meet TikTok requirements (9:16 vertical, 5-60 seconds) |
| `upload_tiktok_images` | Write | Upload images to TikTok Asset Library |
| `create_tiktok_campaign` | Write | Launch in-feed video campaign (created PAUSED) |
| `add_tiktok_ad_group` | Write | Add ad group with full targeting to existing campaign |
| `add_tiktok_ad` | Write | Add ad to existing ad group (image, video, Spark Ads, Carousel) |
| `create_tiktok_carousel_card` | Write | Create carousel card from multiple images |
| `search_tiktok_targeting` | Read | Search interests, keywords, regions, languages, action categories, carriers, device models |
| `list_tiktok_campaigns` | Read | List all campaigns with status, objective, and budget |
| `get_tiktok_campaign_details` | Read | Detailed campaign info |
| `update_tiktok_campaign` | Write | Update campaign name, budget, budget mode |
| `pause_tiktok_campaign` | Write | Pause a TikTok campaign |
| `resume_tiktok_campaign` | Write | Resume a paused TikTok campaign |
| `list_tiktok_ad_groups` | Read | List ad groups, filter by campaign |
| `update_tiktok_ad_group` | Write | Update ad group name, budget, targeting, schedule |
| `pause_tiktok_ad_group` | Write | Pause a TikTok ad group |
| `resume_tiktok_ad_group` | Write | Resume a paused TikTok ad group |
| `list_tiktok_ads` | Read | List ads, filter by ad group or campaign |
| `pause_tiktok_ad` | Write | Pause a TikTok ad |
| `resume_tiktok_ad` | Write | Resume a paused TikTok ad |
| `explain_tiktok_objective` | Read | Given your goal (leads, sales, traffic, app installs), returns the correct TikTok campaign objective, recommended ad format, and compatibility constraints — eliminates trial-and-error objective selection |
| ...and 4 more | | Additional TikTok tools |
## Amazon Ads Tools (61)
| Tool Name | Type | Description |
| ---------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------ |
| `list_amazon_profiles` | Read | List advertiser profiles across NA, EU, and FE |
| `list_amazon_campaigns` | Read | List Sponsored Products / Brands / Display campaigns |
| `create_amazon_sp_campaign` | Write | Create a Sponsored Products campaign (created PAUSED) |
| `create_amazon_sb_campaign` | Write | Create a Sponsored Brands campaign (created PAUSED) |
| `create_amazon_sd_campaign` | Write | Create a Sponsored Display campaign (created PAUSED) |
| `update_amazon_campaigns` | Write | Update name, budget, or bidding across campaign types |
| `pause_amazon_campaigns` / `resume_amazon_campaigns` | Write | Pause or resume campaigns |
| `delete_amazon_campaigns` | Write | Archive campaigns |
| `list_amazon_ad_groups` / `create_amazon_ad_groups` / `update_amazon_ad_groups` / `delete_amazon_ad_groups` | Write | Manage Sponsored Products ad groups |
| `list_amazon_product_ads` / `add_amazon_product_ads` / `update_amazon_product_ads` / `delete_amazon_product_ads` | Write | Manage product ads (your ASINs/SKUs) |
| `list_amazon_keywords` / `add_amazon_keywords` / `update_amazon_keywords` / `delete_amazon_keywords` | Write | Manage keywords for manual targeting |
| `list_amazon_negative_keywords` / `add_amazon_negative_keywords` / `delete_amazon_negative_keywords` | Write | Block irrelevant search terms |
| `list_amazon_targets` / `add_amazon_targets` / `update_amazon_targets` / `delete_amazon_targets` | Write | Manage product and category targeting |
| `list_amazon_sb_ad_groups` | Read | List Sponsored Brands ad groups |
| `create_amazon_sb_ad` / `list_amazon_sb_ads` / `update_amazon_sb_ads` | Write | Manage Sponsored Brands ads (all 7 ad types) |
| `list_amazon_sb_creatives` / `update_amazon_sb_creatives` | Write | Manage Sponsored Brands creative assets |
| `list_amazon_sb_keywords` / `add_amazon_sb_keywords` / `update_amazon_sb_keywords` / `delete_amazon_sb_keywords` | Write | Manage Sponsored Brands keywords |
| `add_amazon_sb_negative_keywords` | Write | Add negative keywords to Sponsored Brands |
| `list_amazon_sb_targets` / `add_amazon_sb_targets` / `update_amazon_sb_targets` | Write | Manage Sponsored Brands targets |
| `add_amazon_sb_themes` | Write | Add theme-based targets to Sponsored Brands |
| `upload_amazon_asset` | Write | Upload a creative asset (e.g. a brand logo) |
| `search_amazon_assets` | Read | Find existing assets in your Amazon library |
| `get_amazon_keyword_recommendations` / `get_amazon_bid_recommendations` | Read | Sponsored Products keyword & bid suggestions |
| `get_amazon_sb_keyword_recommendations` / `get_amazon_sb_bid_recommendations` | Read | Sponsored Brands keyword & bid suggestions |
| `get_amazon_budget_recommendations` / `get_amazon_budget_usage` | Read | Budget recommendations and consumption |
| `get_amazon_campaign_performance` | Read | Impressions, clicks, spend, sales, ACOS, ROAS |
| `get_amazon_search_terms` | Read | The search terms shoppers used to find your ads |
| `get_amazon_report` | Read | Retrieve an async Amazon (Reporting v3) report by ID |
| `analyze_amazon_wasted_spend` | Read | Find keywords/targets spending without converting |
| `optimize_amazon_budget` | Read | Budget reallocation based on ACOS and ROAS |
| `get_amazon_product_performance` | Read | Per-ASIN/SKU performance breakdown |
| `analyze_amazon_placements` | Read | Compare performance across placements |
| `analyze_amazon_targeting` | Read | Evaluate keyword and product targeting effectiveness |
| `get_amazon_purchased_products` | Read | Cross-sell view of what shoppers actually bought |
| `amazon_unified_api` | Write | Direct Amazon Advertising API access for advanced operations |
## ChatGPT Ads Tools (31)
| Tool Name | Type | Description |
| --------------------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------- |
| `list_chatgpt_accounts` | Read | Connected ChatGPT Ads account(s) + review status |
| `list_chatgpt_campaigns` / `get_chatgpt_campaign` | Read | List campaigns or get one in detail |
| `create_chatgpt_campaign` | Write | Create a campaign (created PAUSED) |
| `update_chatgpt_campaign` | Write | Change budget, schedule, or targeting |
| `pause_chatgpt_campaign` / `resume_chatgpt_campaign` | Write | Stop serving, or resume to go live |
| `archive_chatgpt_campaign` | Write | Archive a campaign |
| `list_chatgpt_ad_groups` / `get_chatgpt_ad_group` | Read | List ad groups or get one |
| `create_chatgpt_ad_group` | Write | Add an ad group (bid + targeting) |
| `update_chatgpt_ad_group` | Write | Update bid, schedule, or targeting |
| `pause_chatgpt_ad_group` / `resume_chatgpt_ad_group` / `archive_chatgpt_ad_group` | Write | Control ad-group state |
| `list_chatgpt_ads` / `get_chatgpt_ad` | Read | List ads or get one |
| `create_chatgpt_ad` | Write | Create a chat\_card ad (title, body, image, URL) |
| `update_chatgpt_ad` | Write | Update an ad's creative |
| `pause_chatgpt_ad` / `resume_chatgpt_ad` / `archive_chatgpt_ad` | Write | Control ad state |
| `launch_chatgpt_ad` | Write | One-shot: campaign → ad group → upload → ad (PAUSED) |
| `upload_chatgpt_creative` | Write | Upload a chat\_card image from a public URL |
| `chatgpt_geo_lookup` | Read | Resolve a location to a targeting value |
| `get_chatgpt_performance` | Read | Impressions, clicks, spend, CTR, CPC |
| `get_chatgpt_insights` | Read | Scoped insights (fields, filters, sort, pagination) |
| `set_chatgpt_conversions_config` / `get_chatgpt_conversions_config` | Write | Configure or review Pixel / Conversions API |
| `list_chatgpt_conversion_events` | Read | Conversion events being recorded |
| `test_chatgpt_conversion` | Write | Send a test conversion to verify tracking |
## Audit Tools (1)
| Tool Name | Type | Description |
| --------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `audit_conversion_tracking` | Read | Audit conversion tracking health across platforms. Checks Meta Pixel (event volume, CAPI, dedup), LinkedIn (conversion rules, CAPI, Insight Tag), and Google Ads (conversion actions, enhanced conversions, attribution). Returns health score (0-100), grade (A-F), and actionable recommendations. |
## Automation Tools (16)
### Watch Agent (Proactive Signal)
| Tool Name | Type | Description |
| ---------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run_watch_now` | Read | Trigger an on-demand Watch Agent scan immediately. The agent reviews all connected ad accounts, writes a finding, and emails a re-entry prompt. Normally runs automatically every 15 minutes. |
| `get_signal_briefing` | Read | Pull the advisory briefing and pre-staged fix actions for a specific Watch Agent finding. Use after receiving a finding email or after `run_watch_now`. |
| `apply_signal_actions` | Write | Apply the pre-staged actions from a Watch Agent finding. Executes approved campaign adjustments (pause, bid change, add negatives) in one call. |
| `list_pending_actions` | Read | List all actions staged by the Watch Agent that are waiting for your approval (pending\_approval, executed, rejected, expired). |
| `manage_action` | Write | Approve or reject a specific pending action staged by the Watch Agent. |
### Monitors & Alerts
| Tool Name | Type | Description |
| --------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_monitor` | Write | Set a metric alert. Supports CPA, ROAS, CTR, CPC, spend, conversions, impressions, clicks, cost per lead, conversion rate, budget utilization. Same alerts visible in the [Monitors web UI](https://adspirer.ai/monitors). |
| `list_monitors` | Read | View all active performance monitors (excludes deleted/tombstoned alerts). |
| `delete_monitor` | Write | Remove a monitoring alert permanently. |
| `get_monitor_history` | Read | View all past trigger events for a specific alert — timestamps, metric values, and what triggered it. |
| `test_monitor` | Read | Dry-run a monitor against today's data. See whether the alert would fire right now without waiting for the next scheduled check. |
### Scheduled Briefs & Reports
| Tool Name | Type | Description |
| ----------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schedule_brief` | Write | Schedule daily/weekly performance summaries via email. Briefs now attach a PDF. |
| `generate_report_now` | Read | Generate an ad-hoc cross-platform performance report immediately. |
| `list_scheduled_tasks` | Read | View all scheduled briefs, monitors, and reports with status. |
| `manage_scheduled_task` | Write | Unified pause, resume, or delete for any scheduled task (brief, monitor, or report). Pass `task_id` from `list_scheduled_tasks` and `action`: `'pause'`, `'resume'`, or `'delete'`. |
| `start_research` | Write | Launch an async AI-powered research job (competitor analysis, keyword research, market landscape, audience insights, campaign strategy). |
| `get_research_status` | Read | Check the status and results of an in-progress or completed research job. |
## Marketing Stack Integrations (Plus and above)
Two router tools that proxy to third-party marketing tools through [Pipedream Connect](https://pipedream.com/connect). The agent calls `action="list_tools"` first to discover what's available, then `action="execute"` with the specific tool name.
| Tool Name | Type | Description |
| ------------------ | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `google_analytics` | Read | Pull GA4 property data — sessions, conversions, traffic sources, landing-page performance, real-time. See the [Google Analytics integration page](/integrations/google-analytics). |
| `klaviyo` | Read | Pull Klaviyo campaigns (email + SMS), flows, segments, profiles, and metrics. See the [Klaviyo integration page](/integrations/klaviyo). |
Both integrations require the user to connect the account in the [Connections panel](https://adspirer.ai/connections). Free-tier users see the integration cards with an Upgrade prompt.
## System Tools (5)
| Tool Name | Type | Description |
| ------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_connections_status` | Read | Show all connected ad platforms and account IDs |
| `list_connected_accounts` | Read | List ad accounts across platforms — including connected-but-not-yet-activated accounts and live Google MCC child accounts. Used by sequential sub-agents to fan out work. Optional `platform` filter. Zero API calls (reads from database). |
| `switch_primary_account` | Write | Change which ad account is active — by name, from chat, including switching between Google MCC child accounts. Respects your plan's active-account cap (replaces on single-account tiers, adds on multi-account tiers). Doesn't cost a tool call. |
| `get_usage_status` | Read | Check Adspirer plan limits (tool calls used/remaining this month) |
| `get_business_profile` | Read | View user's Adspirer account details and subscription info |
## Diagnostic & Helper Tools (13)
Read-only "get unstuck" tools — get-started guidance, pre-launch checks, error diagnosis, and value summaries. **All quota-free** (they never count against your tool-call limit) and available on **every plan, including Free**. Your assistant discovers them automatically; in ChatGPT and Claude their results render as interactive cards. See the [Diagnostic & Helper Tools reference](/agent-skills/diagnostic-helper-tools).
| Tool Name | Type | Description |
| -------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------ |
| `start_here` | Read | The single best next step for your exact state, with a worked example prompt |
| `suggest_next_action` | Read | Ranks the highest-value things to do right now from your live data |
| `list_what_i_can_do` | Read | Personalized capability menu by goal, filtered to your connected platforms |
| `get_campaign_spec` | Read | Required fields, character limits, and allowed values for a campaign type |
| `preflight_campaign` | Read | Checks an account is launch-ready (billing, notification email, connection, pixel/Page for Meta) |
| `validate_campaign_draft` | Read | Dry-run validates a campaign draft against the platform spec (no write) |
| `explain_platform_error` | Read | Translates a raw platform error into a plain-language cause and fix |
| `why_did_this_fail` | Read | Summarizes your recent failed actions and the errors behind them |
| `diagnose_my_setup` | Read | Full health check: AI-client connection, ad-platform sign-in, per-platform account health |
| `verify_campaign_is_live` | Read | Real live check that a campaign exists and is serving (all 6 platforms) |
| `whats_changed_since_last_visit` | Read | What moved since you were last here — spend, clicks, conversions, biggest movers |
| `weekly_opportunities` | Read | 1–3 concrete optimization opportunities from recent performance |
| `usage_value_summary` | Read | Tool calls used vs. included this period and what they accomplished |
## Raw data mode
All performance and analytics tools accept an optional `raw_data` parameter. When set to `true`, the tool returns a compact JSON code block with only raw metrics — no severity labels, suggested bids/budgets, industry benchmarks, or optimization recommendations. Default is `false` (full markdown output with recommendations).
Use `raw_data=true` when you run your own attribution model, want to minimize token usage, or need to pipe metrics into an external tool.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"raw_data": true, "date_range": "last_30_days"}
```
## Tool call best practices
* **Always start with `get_connections_status`:** Verify the correct ad account is active before using platform-specific tools
* **Chain Read tools before Write tools:** Research, validate, then create. Never jump straight to campaign creation.
* **Ask for user confirmation before Write tools:** Present the plan, get approval, then execute.
* **Never retry Write tools on error:** If a campaign creation fails, report the error and wait for user input. Don't auto-retry.
* **Format results as tables:** Performance data should be scannable (columns: metric, value, change vs. previous period)
* **Use `raw_data=true` for compact output:** When you need just the numbers without recommendations, pass `raw_data=true` to any performance tool.
## Input Format Requirements
Follow these rules when calling Adspirer tools to avoid validation errors:
### IDs Must Be Strings
All IDs (`campaign_id`, `ad_account_id`, `video_id`, `image_hash`, `ad_group_id`, `keyword_id`, `organization_id`, `creative_id`) must be passed as quoted strings, never as bare integers.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
// ✅ Correct
{"existing_video_id": "1333064875515942"}
// ❌ Wrong
{"existing_video_id": 1333064875515942}
```
### Never Modify IDs
Copy IDs exactly as returned by list/discover tools. Do not round, truncate, or change any digits.
### Always Call List/Discover Before Create/Update
Many tools require IDs from prior tool calls:
* `list_campaigns` → get `campaign_id` before update/pause/structure
* `get_campaign_structure` → get `ad_group_id` before keyword operations
* `discover_existing_assets` → get `image_hash`, `video_id` before campaign creation
* `get_linkedin_organizations` → get `organization_id` and `account_id`
### Text Length Limits
The server will reject text that exceeds platform limits:
| Field | Platform | Max Characters |
| ------------- | ---------- | -------------- |
| Headline | Google Ads | 30 |
| Description | Google Ads | 90 |
| Sitelink text | Google Ads | 25 |
| Callout | Google Ads | 25 |
| primary\_text | Meta Ads | 125 |
| Headline | Meta Ads | 40 |
### Meta Ad Copy Formatting
Meta `primary_text` supports emojis, line breaks (`\n`), and bullet points for higher engagement:
```
🔥 Limited Time Offer!
✅ Free Shipping
✅ 30-Day Returns
✅ Best Price Guarantee
👉 Shop now before it's gone!
```
Use emojis strategically (🔥 ✅ 🎯 💰 ⚡ 🚀 👉 ⭐ 💡 📈) and structure copy with line breaks and bullet points (•, ✅, ▸) for readability.
### Enum Values Are Case-Insensitive
The server auto-normalizes casing. Common enum values:
* **status:** `ENABLED`, `PAUSED`, `ACTIVE`, `ARCHIVED`
* **objective:** `OUTCOME_TRAFFIC`, `OUTCOME_SALES`, `OUTCOME_LEADS`
* **match\_type:** `EXACT`, `PHRASE`, `BROAD`
* **date\_range:** `last_7_days`, `last_30_days`, `last_90_days`
* **campaign\_type:** `search`, `pmax`, `image`, `video`, `carousel`
### Budgets Are Numbers
Pass budget fields as numbers, not strings. Budget is in the account's local currency (not cents).
### Keywords Format
For `add_negative_keywords`, each keyword must be an object with `text` and `match_type` fields:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
// ✅ Correct
{"keywords": [{"text": "free", "match_type": "BROAD"}]}
// ❌ Wrong
{"keywords": ["free", "cheap"]}
```
## Related Documentation
* [Core Workflows](/agent-skills/workflows) -- See how these tools fit into step-by-step processes
* [Skills Overview](/agent-skills/overview)
* [Google Ads Integration](/ad-platforms/google-ads)
* [Meta Ads Integration](/ad-platforms/meta-ads)
* [LinkedIn Ads Integration](/ad-platforms/linkedin-ads)
* [TikTok Ads Integration](/ad-platforms/tiktok-ads)