Ad Superpowers

Duplicate a Meta ad with optional creative overrides (new headline, image, etc.). WRITE tool. Uses the Ad Copies API: creates a NEW ad from a source ad; fields you pass override, fields you omit are copied. The original is never changed. Created PAUSED by default. Account integrity protection: the server mirrors Meta's documented rate model (error-613 circuit breaker, usage-header backoff) - no artificial hourly cap; duplicating variants sequentially needs no self-pacing. If a write is throttled, the error says so - back off and retry. When to use: spin up A/B variants of a winning ad, or move an ad to another ad set (adset_id). To fix a typo/URL on a live ad WITHOUT losing its social proof, prefer meta_update (creative swap). To build a fresh ad, use meta_create_ad. Required: account_id ('act_...'), ad_id (source, e.g. '120210123456789'). Provide at least one override (headline, body, description, link_url, image_url, cta_type, url_tags, display_url) or adset_id. image_url is uploaded automatically. Note: ad_name does NOT set a custom name (Meta only auto-suffixes " - Copy"); rename afterwards with meta_update. Example: meta_duplicate(account_id, ad_id, headline="Summer Sale - 50% Off") Full field reference - every argument, known Meta breaking changes (deprecated standard enhancements / 191x100 crop), and examples: read MCP resource docs://tools/meta_duplicate

meta_duplicate

Generate keyword ideas using Google Ads Keyword Planner. Common user questions this tool can answer: - What keywords should I target? - What is the search volume for my keywords? - What CPC can I expect for these keywords? - What keywords are popular in the Netherlands? - What are Dutch search volumes for my keywords?

google_ads_run_keyword_planner

Get analytics data for LinkedIn Ads at account or campaign level. Returns account-level aggregates or performance for one campaign.

linkedin_get_analytics

Get LinkedIn ad creatives with performance data and optional images. Fetches creatives with their text content and performance metrics. Set include_images=True to also embed images/video thumbnails as base64. Supports all LinkedIn ad types: image ads, video ads, spotlight ads, text ads. Common user questions this tool can answer: - Which LinkedIn creative is performing best? - What ad copy am I running on LinkedIn?

linkedin_get_creatives_with_images

Get ad creative details, text content, and performance data. Unified creative tool that works at three scopes: - **single**: Get one creative's details (headline, body, CTA, optional image) - **campaign**: Get all creatives for a campaign with performance metrics - **account**: Get top-performing creatives across the entire account Always includes 'creative_text' with headline, body, description, CTA type, and link URL. Set include_images=True to embed images as base64 for visual analysis.

meta_get_creatives

Get performance insights for Meta Ads at any level. This unified tool provides insights for account, campaign, adset, or ad level. Use it to analyze performance metrics, conversions, and ROAS. Common user questions this tool can answer: - How many people am I reaching? - What is my cost per result? - Why is my frequency so high? - What is my ROAS?

meta_get_insights

Query organic search performance data from Google Search Console. The power tool for all organic search data. Returns clicks, impressions, CTR, and average position for your website in Google Search results. Date range: provide ONE of: (a) start_date+end_date, (b) date_range ("last 7 days"), or (c) days (lookback from today). If none given, defaults to last 28 days.

gsc_search_analytics

Get TikTok ads with creative text content and performance data. Returns ad text, CTA, landing page URL, and performance metrics. Set include_images=True to also embed creative images/video covers as base64. Common user questions this tool can answer: - What creative assets am I using? - Which ads are performing best? - What ad copy and CTAs am I running?

tiktok_get_ads_with_creatives

Get TikTok advertiser account information. Returns account details including name, status, currency, and timezone. Use this first to verify your connection is working.

tiktok_get_advertiser_info

Get a TikTok Ads performance report at campaign, adgroup, or ad level. READ tool (single advertiser). Defaults to your primary connected advertiser; pass advertiser_id (discover via tiktok_list_advertisers) to target another. There is no `advertiser_ids` plural param. Dates: pass EITHER date_range (natural language, e.g. "last 7 days", "this month", "yesterday") OR start_date/end_date (YYYY-MM-DD) - not both. level: "campaign" (default) | "adgroup" | "ad". entity_ids filters by PARENT: for level="adgroup" pass campaign_ids; for level="ad" pass adgroup_ids; omit for level="campaign". metrics/dimensions optional (sensible defaults). page/page_size for paging. Example: tiktok_get_report(date_range="last 7 days", level="adgroup", entity_ids=["1800000000000001"]) Full field reference - the full metric list (traffic/cost/conversion/video/ engagement/commerce), dimensions, and example gallery: read MCP resource docs://tools/tiktok_get_report

tiktok_get_report

Look up TikTok assets by ID, or LIST the advertiser's whole asset library. Two modes, and the response always says which one ran via "mode": mode="lookup" asset_ids given -> metadata for exactly those IDs mode="list" asset_ids OMITTED -> browse the library, newest first List mode is how you find an asset whose ID you do not have — the case a tiktok_upload that failed to report its ID leaves you in. It returns each record verbatim, file_name included, so you can match on the name you uploaded with.

tiktok_get_asset_info

Discover + wire the Facebook Page and Instagram account onto a client's Meta-linked ad accounts, so meta_create_ad resolves them automatically. For each Meta ad account linked to `client`, this finds the promotable Page and the connected Instagram account. When exactly one of each exists and the linked account doesn't already have it, that id is the auto-wire candidate. Accounts with 0 or >1 options are returned as `page_choices` / `ig_choices` for you to pick and persist yourself with clients_update. apply=False (default): preview only — returns, per account, the current + discovered Page/IG and what would be wired. Nothing is written. apply=True: persist the unambiguous, currently-missing ids onto the client's linked accounts (via the client service). Ambiguous / already-set accounts are left untouched and reported.

meta_wire_pages

List Google Analytics 4 properties that you have connected. Returns only properties you've connected in Ad Superpowers. Connect properties via the dashboard to make them available here.

ga4_list_properties

List your connected Google Ads accounts. Returns a list of Google Ads accounts you've connected via the dashboard. Common user questions this tool can answer: - Which Google Ads accounts do I have access to? - How do I find my customer ID?

google_ads_list_accounts

List your connected LinkedIn ad accounts, or get details of a single account. When account_id is provided, returns detailed info for that specific account. Otherwise, returns a list of all connected ad accounts.

linkedin_list_ad_accounts

List Google Merchant Center accounts you can access. Returns top-level accounts plus their DIRECT sub-accounts (one level — sub-accounts that are themselves advanced accounts are not traversed). ``partial: true`` means at least one parent's sub-account listing failed; retry those via ``failed_parents``. Returns: {"success": true, "accounts": [{"accountId", "accountName", "advanced", "is_subaccount", "parent_account_id", ...}], "partial": bool, "failed_parents": [{"accountId", "error", "retry_hint"}]}

merchant_list_accounts

List your connected Meta ad accounts. Returns a list of ad accounts you've connected via the dashboard, with their names, IDs, status, and currency. Use this first to discover your available ad accounts before querying specific ones.

meta_list_ad_accounts

List Google Search Console properties (websites) and optionally their sitemaps. Returns only properties you've connected in Ad Superpowers. Connect properties via the dashboard to make them available here. Use include_sitemaps=True to also fetch sitemap status for each site (URL, type, last submitted, warnings, errors).

gsc_list_sites

List Google Tag Manager containers connected to your Ad Superpowers account. Returns only containers you have connected in the dashboard. Each container includes its GTM-XXXXXXX public ID, type (web/server/android/ios/amp), and the account it belongs to. Connect containers at the Ad Superpowers dashboard to make them available. Returns container path, account info, public GTM ID, and container type. Rate limit: GTM permits ~30 API calls per minute per user, and one tool call can fan out to several API calls. Call GTM tools sequentially, never in parallel, and pace batch or multi-container work; on a 429, wait ~60 seconds before retrying.

gtm_list_containers

List GTM tags, triggers, variables, and built-in variables. Runs against the Google Tag Manager API v2 (https://developers.google.com/tag-platform/tag-manager/api/v2). Use this tool to obtain the ``tag_path`` and ``fingerprint`` required by ``gtm_manage`` for ``update_tag`` and ``delete_tag``. ``source="workspace"`` lists an explicit workspace or auto-resolves the container's default workspace. ``source="live"`` shows the published truth, but its version paths are not writable: use paths from a workspace for writes. Results combine requested types in tag, trigger, variable, built-in-variable order, with numeric ids ascending inside each type. ``page`` is 1-based; ``page_size`` is clamped to 200 for slim results and 25 when ``include_config=True``. ``total`` covers all matching entities and ``has_more`` indicates whether a later page exists. Rate limit: GTM permits ~30 API calls per minute per user, and one tool call can fan out to several API calls. Call GTM tools sequentially, never in parallel, and pace batch or multi-container work; on a 429, wait ~60 seconds before retrying.

gtm_list_entities

List ALL TikTok advertiser accounts you've connected. tiktok_get_advertiser_info returns only your default advertiser. Use this to discover every connected advertiser (id, name, status, currency, timezone), then pass advertiser_id to the other tiktok_* tools to target a specific one.

tiktok_list_advertisers

Get TikTok audiences for targeting. This tool fetches custom audiences, lookalike audiences, or both. Use audiences for retargeting existing customers or finding similar users.

tiktok_get_audiences

Read your organization's client profiles (agency clients, not users). Actions: - action="list" (default): compact rows for the WHOLE portfolio in one call — id, slug, name, status, budget_total, currency, channel platforms and linked-accounts count. No attention_points in list rows (use action="get" for the full profile). - action="get": the full profile (budgets, channels with goals, linked ad accounts, attention_points). Identify the client with either: * client — its slug or UUID, or * account_id — an ad-account id; answers "which client owns ad account X?" via the profile's linked_accounts. Profiles are business context written by your organization (goals, budgets, attention points) to make reports client-aware. Edit them with `clients_update` or in the dashboard.

clients

Manage URLs and sitemaps in Google Search Console. Three actions for URL-specific operations: - inspect: Check a page's indexing status, mobile usability, and rich results - submit_sitemap: Tell Google about a new or updated sitemap - delete_sitemap: Remove a sitemap from GSC tracking

gsc_manage_url

Manage GTM workspaces, entities, versions, imports, synchronization, and publishing. All writes validate access against container_path; workspace_path auto-resolves to the default workspace when omitted. Actions (required params): - create_workspace (name) · create_version (name) · publish (version_path — WARNING: goes live immediately) · sync_workspace - create_tag / create_trigger / create_variable ({tag,trigger,variable}_data) - update_tag / update_trigger / update_variable ({...}_path + {...}_data) - delete_tag / delete_trigger / delete_variable ({...}_path) - enable_built_in_variables (built_in_types) - import_container (import_data: GTM export JSON, max 20 entities; variables → triggers → tags with trigger-ID remapping). merge overlays imported fields on same-name entities and skips identical results; overwrite replaces same-name configurations and always writes. Both modes create absent entities. Updates: include a fingerprint to PUT directly; omit it and the entity is fetched, expected_name checked when supplied, your partial payload merged over it, and PUT with the fetched fingerprint (GTM 412 = race backstop). Get writable paths + fingerprints from gtm_list_entities. dry_run=True: client-side structural checks only, never writes (the GTM API has no server-side validateOnly; compiler feedback only via create_version). Rate limit: GTM permits ~30 API calls per minute per user, and one tool call can fan out to several API calls. Call GTM tools sequentially, never in parallel, and pace batch or multi-container work; on a 429, wait ~60 seconds before retrying. Full field reference, per-action requirements and the GTM tag-type code table: read the docs://tools/gtm_manage resource.

gtm_manage

Unified tool for knowledge skills and analysis scripts (system + custom Pro+ skills). READ tool. Note: with the Ad Superpowers plugin installed, skills load locally and automatically - use this tool for custom user skills, cross-skill search, running analysis scripts, or live connection health. Actions (action=): - "list": browse skills (filters: phase, category, skill_type; paginated). - "get": fetch one skill's content (requires skill_id = id/uuid/slug; options section, sections_only, include_references). - "search": keyword search (requires query). - "run": execute a skill's Python script (Pro+; skill_id + script_name + input_data). - "connection_health": live per-platform connection status with reconnect links (no params). Use when platform tools seem missing or a connection looks broken. Parameter coupling: skill_id is ONLY valid with get/run; query ONLY with search. Passing them with the wrong action returns a clear error (no silent fallback to the full catalogue). Example: skill(action="get", skill_id="meta-bid-strategy-selector") Full field reference - every argument, pagination fields, and key system-skill names: read MCP resource docs://tools/skill

skill

Unified workflow tool for marketing analysis templates. Workflows are pre-built analysis templates that guide you through complex advertising tasks like campaign audits, performance analysis, and optimization. ## Actions **list** - List all activated workflows ``` workflow(action="list") ``` **info** - Get workflow details and required parameters ``` workflow(action="info", workflow_name="workflow:campaign-audit") ``` **run** - Execute a workflow with parameters (supports background execution) ``` workflow(action="run", workflow_name="workflow:campaign-audit", parameters={"account_id": "123"}) ```

workflow

Build one confirmable plan for a single paused Meta video ad. Writes nothing. Returns the overview the customer must read plus the token that confirms it. Pass the message through to the customer unchanged: it is the text they are confirming. Call meta_ad_execute with the token the customer gives back.

meta_ad_plan

Execute the plan the customer confirmed by giving this token back. Pass the customer's own words. A refusal ("nee", "laat maar") is handled here too and creates nothing.

meta_ad_execute

Query LinkedIn Ads entities (campaigns, campaign_groups, or creatives). Runs against the LinkedIn Marketing API (https://learn.microsoft.com/en-us/linkedin/marketing/). This flexible tool replaces individual get_* functions for all entity types. Use it to fetch lists of entities or single entity details. Common user questions this tool can answer: - What campaigns are active? - What is the status of my campaign groups?

linkedin_query

Read Merchant Center entities polymorphically. Runs against the Google Merchant API (https://developers.google.com/merchant/api). - "What's this account's status?" → entity_type="account" - "What's wrong with this account?" → entity_type="issues" - "Which products are listed?" → entity_type="products" - "Why is this product disapproved?" → entity_type="product_statuses" - "Show one product" → entity_type="product" + entity_id (resource fragment "{channel}~{contentLanguage}~{feedLabel}~{offerId}") - "Which feeds exist?" → entity_type="datasources" ``account_id`` must be an active, selected Merchant connection. An unselected or unknown id fails before provider I/O; call ``merchant_list_accounts`` to refresh accessible accounts. Paginate via ``page_token`` from ``next_page_token``.

merchant_query

Query Meta Ads entities, activity logs, or fetch the next page of a result. Runs against the Meta Marketing API (https://developers.facebook.com/docs/marketing-apis/). READ tool. Handles all entity types, change history, targeting search, and pagination in one place. When to use: list or inspect campaigns, ad sets, ads, creatives, audiences, images/videos, pixels, pages, IG accounts, targeting, or activities. For PERFORMANCE metrics (spend, CTR, ROAS) use meta_get_insights instead; for full creative detail on one ad use meta_get_creatives. Required: account_id ('act_...'), entity_type. Common entity_type values: account, campaigns, adsets, ads, creatives (needs parent_id=ad_id), customaudiences, savedaudiences, activities, adimages, advideos, adspixels, connected_instagram_accounts, promotepages, targetingsearch (needs query), ads_volume. (productcatalogs is scope-gated - use meta_catalog_query.) Filter with parent_id (by parent entity), effective_status, since/until (YYYY-MM-DD). limit default 50. To page, pass pagination_url from a prior response (all other params are then ignored). Example (ad sets of one campaign; IDs are numeric strings): meta_query(account_id, "adsets", parent_id="120210123456789") Full field reference - every entity_type with its fields and requirements, targeting validation/suggestions, all arguments and examples: read MCP resource docs://tools/meta_query

meta_query

Query TikTok Ads entities (campaigns, adgroups, or ads). Runs against the TikTok Business API (https://business-api.tiktok.com/portal/docs). This flexible tool replaces individual get_* functions for all entity types. Use it to fetch lists of entities or single entity details. Common user questions this tool can answer: - What campaigns are running? - What ad groups do I have?

tiktok_query

Run a Google Analytics 4 report with any metrics x dimensions combination. Runs against the Google Analytics Data API v1 (https://developers.google.com/analytics/devguides/reporting/data/v1). READ tool. Breaks GA4 data down by country, device, page, source/medium, channel, date, event, and more. Required: property_id (numeric), metrics (list). Dates: pass EITHER date_range (natural language, e.g. "last 7 days", "last 30 days", "this month", "yesterday") OR the start_date/end_date pair (YYYY-MM-DD) - not both. dimensions optional. limit: rows per call (omitted = the GA4 API's own default of 10,000). When more rows exist the response has partial=true and next_offset — pass that as offset to page. Common metrics: sessions, totalUsers, activeUsers, newUsers, screenPageViews, bounceRate, engagementRate, keyEvents (conversions), totalRevenue. Common dimensions: country, deviceCategory, pagePath, landingPage, source, medium, sessionDefaultChannelGroup, date, eventName. Example - traffic by channel: ga4_run_report(property_id, metrics=["sessions", "keyEvents"], dimensions=["sessionDefaultChannelGroup"], date_range="last 30 days") Full field reference - the full metric and dimension catalogues plus 14 ready-to-use recipes: read MCP resource docs://tools/ga4_run_report

ga4_run_report

Execute a GAQL (Google Ads Query Language) read query. Runs against the Google Ads API query service (https://developers.google.com/google-ads/api/docs/query/overview). READ tool for all Google Ads reporting and ID discovery: performance (impressions, clicks, CTR, CPC, cost, conversions), keywords, search terms, assets, audiences, Merchant Center detection, PMax/Shopping data. To CHANGE anything use google_ads_mutate instead. Required: customer_id: 10 digits, no dashes. query: the GAQL query string. manager_id auto-detects for sub-accounts. page_token: pass back a prior response's next_page_token to fetch the next page (partial:true means more pages remain). DURING date ranges: TODAY, YESTERDAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH, THIS_WEEK_SUN_TODAY, THIS_WEEK_MON_TODAY, LAST_WEEK_SUN_SAT, LAST_WEEK_MON_SUN. LAST_90_DAYS is NOT valid - use BETWEEN with explicit dates. cost_micros is millionths (5000000 = $5.00). Example: SELECT campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC Full field reference - 20+ ready-to-use GAQL recipes (campaigns, keywords, search terms, assets, Shopping, PMax, conversions, portfolio bidding): read MCP resource docs://tools/google_ads_run_gaql

google_ads_run_gaql

Run a validated Merchant Center report preset. Presets: - product_performance: clicks/impressions/CTR/conversions per product, last 30 days (conversions cover FREE traffic only). - disapproval_impact: disapproved products ranked by click potential (the Merchant API has no cost metric — join Google Ads for spend). - clicks_without_conversions: >10 clicks, 0 conversions, last 30 days (conversions cover FREE traffic only). There is no raw-query mode; these three presets are the entire report surface of this slice. Returns: {"success": true, "preset": str, "description": str, "view": str | null, "rows": [{...}], "next_page_token": str | null} ``rows`` are flat objects. The Merchant API wraps each row in its view name; that wrapper is stripped and the view is reported once in ``view``. Field names stay exactly as Google spells them — camelCase, e.g. ``offerId`` — even though the preset query selects snake_case; ``view`` tells you which reference page defines them (AD-368).

merchant_get_report

Show the active workspace and the credential binding used for this request.

workspace_info

Update a Meta entity - campaigns, ad sets, ads, and in-place creative fixes. WRITE tool; changes take effect immediately. Account integrity protection: the server mirrors Meta's documented rate model (error-613 circuit breaker, usage-header backoff) - no artificial hourly cap; sequential edits need no self-pacing. Two real Meta caps: ad-set budget changes 4/hour per ad set, spend-cap changes 10/day per account. If a write is throttled, the error says so - back off and retry. Required: account_id ('act_...'), entity_type ("campaign"|"adset"|"ad"), entity_id. Three modes, by which fields you set: 1. Direct update: status, name, daily_budget/lifetime_budget (CENTS; 2000 = $20.00), end_time, targeting, etc. 2. Creative swap (entity_type="ad" plus any creative field: headline, primary_text, description, link_url, cta_type, image_hash, video_id, url_tags). Meta creatives are immutable, so this attaches a NEW creative; ad_id and social proof (comments/reactions/shares) are preserved. PREFERRED over meta_duplicate for fixing typos, URLs, or CTAs on live ads that already have engagement. 3. Learning-reset fields (targeting, optimization_goal, bid_strategy, bid_amount, or a budget change >20%) are REJECTED unless acknowledge_learning_reset=True. status: ACTIVE | PAUSED | ARCHIVED. Example - fix a live ad's URL (creative swap, keeps social proof): meta_update(account_id, "ad", "345678", link_url="https://correct-url") Full field reference - every argument, bid_strategy / optimization_goal enums, DSA fields, per-entity field matrix, response shape, and examples: read MCP resource docs://tools/meta_update

meta_update

Upload a video to a Meta ad account's media library from a public URL. Meta fetches the video server-side from the URL you provide. The upload returns immediately with a video_id; Meta then processes the video asynchronously (typically 30-120 seconds depending on length and resolution).

meta_upload_video

Upload an image or video to a TikTok advertiser's ad asset library. WRITE tool. Returns the `asset_id` you pass to tiktok_manage when building an ad creative. An asset never delivers and never spends, so there is no paused-by-default gate here -- the pause lives on the ad. Required: advertiser_id: the TikTok advertiser whose library receives the asset. asset_type: image | video. file_name: a descriptive name, e.g. "spring sale 1080x1080". NOT cosmetic -- TikTok stores one asset per set of bytes and the newest upload's file_name renames it for everyone, so a generic name renames what the advertiser already had. There is no delete. Exactly one of: file_data: base64-encoded raw bytes. IMAGE ONLY, max 4 MB raw. file_url: a public HTTPS URL. Both types, and the ONLY route for video. TikTok downloads it server-side, so nothing large crosses the MCP transport. At TikTok, file_url becomes image_url or video_url depending on asset_type, so a TikTok error naming `video_url` refers to this parameter. After a VIDEO upload the response carries `suggested_cover_image_ids`: a SINGLE_VIDEO creative requires `image_ids` for its cover. Read the asset back with tiktok_get_asset_info. An empty first read means "not yet", never "not created" -- do NOT repeat the upload on that basis. Uploads need a grant carrying the Creative Management permissions; one with only Ads Management is refused before any API call. Field reference, both end-to-end recipes, the identity fields an ad create needs, how TikTok stores assets, and what is NOT measured about its limits: docs://tools/tiktok_upload

tiktok_upload