1ClickReport
Your AI marketing analyst, connected to your marketing data.
Community: Submitted by a user or imported; check the owner before granting accessOnlineNo sign-inRU / CISFreeRead-only
What it can do
- Get Ga4 Metrics: Get Google Analytics 4 metrics for your connected GA4 property. Returns metrics like active users, sessions, bounce rate, page views, etc. CRITICAL PARAMETER FORMAT — DO NOT use raw G
- Get Ai Referral Traffic: Measure traffic referred FROM AI assistants / answer engines — ChatGPT, Perplexity, Gemini, Claude, Copilot, Bing Copilot, etc. This is the AEO (Answer Engine Optimization) sc
- Get Gsc Metrics: Get Google Search Console metrics — clicks, impressions, CTR, average position. Break down by one OR MORE dimensions, filter to a specific query/page, and pull up to 5,000 rows. DIAGN
What data it sees
Do you need an account
No: the server works without sign-in
Your AI marketing analyst, connected to your marketing data.
1ClickReport helps agencies, in-house marketers, and founders investigate campaign performance and prepare client reports from connected accounts. Use the web app or connect the hosted MCP server to a compatible AI client.
Start with one useful question
- What changed in my campaigns? Compare spend and conversions over consistent date ranges, then investigate the largest changes.
- Where should I look for wasted spend? Review search terms, campaign performance, and conversion data before deciding what to change.
- What should I tell my client? Draft a summary of what changed, the supporting evidence, and the next decisions.
- How is paid traffic performing alongside organic search? Bring advertising, GA4, and Search Console data into the same analysis.
Available integrations include Google Ads, Meta Ads, Google Analytics 4, Search Console, Shopify, Stripe, and WordPress. Features and management tools depend on your plan and connected accounts.
Try it with your own accounts
Start a seven-day free trial, with no credit card required: https://www.1clickreport.com/?utm_source=smithery&utm_medium=referral&utm_campaign=growth30_202609
For MCP access, connect to https://mcp.1clickreport.com/mcp and complete OAuth sign-in. Then connect a data source and ask your first question.
Suggested first prompt:
Compare the last seven complete days with the previous seven. Show spend, clicks, conversions, and cost per conversion by campaign. Flag missing data and suggest what to investigate next. Do not change anything.
Review the evidence and recommendations before acting. Analysis does not guarantee improved campaign results.
Links
- Setup guide: https://github.com/1clickreport/mcp/blob/main/docs/SETUP.md
- Tools and plan details: https://github.com/1clickreport/mcp
- Current pricing: https://www.1clickreport.com/#pricing
- Privacy: https://www.1clickreport.com/privacy-policy
- Support: support@1clickreport.com
Server tool list (60)
Raw names from tools/list. Only developers need these.
| get_ga4_metrics | Get Google Analytics 4 metrics for your connected GA4 property. Returns metrics like active users, sessions, bounce rate, page views, etc. CRITICAL PARAMETER FORMAT — DO NOT use raw GA4 API format: - metric: SINGLE STRING like "sessions" or "activeUsers". NOT an array. NOT an object. NOT [{"name":"sessions"}]. - dimensions: ARRAY OF STRINGS like ["sessionSource", "deviceCategory"]. NOT objects. NOT [{"name":"sessionSource"}]. - WRONG: metric=[{"name":"sessions"}], dimensions=[{"name":"sessionSource"}] - RIGHT: metric="sessions", dimensions=["sessionSource"] MULTI-PROPERTY SUPPORT: - Use list_ga4_properties tool to see all available properties - Specify EITHER propertyId OR propertyName to query a specific property - propertyName: Human-readable name (e.g., "Zyler AI", "My Blog") - EASIEST for users - propertyId: Numeric ID (e.g., "461664620") - use "format" value from list_ga4_properties - If neither specified, uses your default property FILTERING SUPPORT: - Filter data by country, page, device, or traffic source - Example: Get USA traffic only, or mobile users only - All filters are optional - omit for unfiltered data Queries the Google Analytics Data API (developers.google.com/analytics/devguides/reporting/data/v1). |
| get_ai_referral_traffic | Measure traffic referred FROM AI assistants / answer engines — ChatGPT, Perplexity, Gemini, Claude, Copilot, Bing Copilot, etc. This is the AEO (Answer Engine Optimization) scoreboard: which of your pages get clicked through from AI, by which engine, and the trend. WHAT IT DOES: queries GA4 sessions whose source is an AI assistant, broken down BY AI engine and BY landing page. Works for any site with GA4. USE WHEN: user asks about AI/LLM traffic, ChatGPT/Perplexity referrals, "are we getting cited by AI", or to measure whether SEO/AEO work is paying off. RETURNS: total AI-referral sessions, breakdown by AI source, and the top landing pages getting AI traffic. NOTE: this is GA4 *referral* traffic (clicks from AI tools) — NOT whether you appear inside an AI Overview/answer (no API exposes that). Requires GA4 connected. |
| get_gsc_metrics | Get Google Search Console metrics — clicks, impressions, CTR, average position. Break down by one OR MORE dimensions, filter to a specific query/page, and pull up to 5,000 rows. DIAGNOSIS vs REPORTING: - dimensions: ["query","page"] together reveals WHICH URL ranks for WHICH query — the difference between reporting and diagnosis. Pass multiple. - filters: target a specific keyword or URL instead of pulling the top N and hoping it's in there (equals/contains/notContains/regex). - rowLimit up to 5000 (+ startRow to page further) so records outside the top 100 aren't invisible. - aggregationType byPage vs byProperty changes how position/CTR are blended. The "summary" block is the TRUE site-level total for the (filtered) window — not an average of the returned rows. MULTI-SITE: pass siteUrl (from list_gsc_sites) to pick a site; otherwise the account default is used and disclosed in _resolved. Queries the Google Search Console API searchanalytics.query endpoint (developers.google.com/webmaster-tools/v1). |
| inspect_url | Inspect a single URL's Google index status via the Search Console URL Inspection API — the answer to "is this page indexed, and which version did Google pick?" RETURNS: index verdict + coverageState ("Submitted and indexed" / "Crawled - currently not indexed" / "Discovered - not indexed" / …), last crawl time, crawledAs (mobile/desktop), robots/fetch state, **Google-selected canonical vs your declared canonical** (and whether they match — the fastest way to confirm or DISPROVE a duplicate-content/canonical problem), mobile-usability and rich-results verdicts. USE WHEN: user asks whether a page is indexed, why a page isn't ranking/appearing, about canonicalization or duplicate content, or crawl problems. Pass the full URL; the property is auto-matched (or pass siteUrl). Queries searchconsole.urlInspection.index.inspect (developers.google.com/webmaster-tools/v1/urlInspection.index/inspect). |
| list_sitemaps | List the sitemaps submitted to Search Console for a property, with last-downloaded time, pending state, error/warning counts, and per-type submitted-vs-indexed URL counts. USE WHEN: user asks about sitemaps, why pages aren't getting indexed, or wants to check sitemap health/coverage. Queries searchconsole.sitemaps.list (developers.google.com/webmaster-tools/v1/sitemaps/list). |
| find_gsc_quick_wins | Surface "striking-distance" SEO quick wins from Search Console: query×page pairs ranking just outside the click zone (position ~4–20) with real impression volume — where a small ranking or CTR improvement yields outsized clicks. Ranked by opportunity. USE WHEN: user asks "where are my quick wins / easy SEO opportunities / what should I optimize first / striking distance keywords". Queries GSC query×page, then filters to position 4–20 with impressions ≥ minImpressions and ranks by an opportunity score (impressions × distance from the top). |
| get_google_ads_metrics | Get Google Ads paid advertising performance metrics. USE THIS TOOL FOR: - Google Search Ads and Display Ads performance - Ad spend, clicks, impressions, conversions - Campaign, Ad Group, Ad, or Keyword level data - ROAS (Return on Ad Spend) and conversion tracking - Quality Score and Impression Share metrics - Ad copy details (headlines, descriptions, URLs) at ad level THIS IS FOR GOOGLE PAID ADS ONLY - for organic Google search use get_gsc_metrics instead. MULTI-ACCOUNT SUPPORT: - Use list_google_ads_accounts tool to see all available accounts - Specify customerId parameter to query a specific account - If customerId not specified, uses your default account - Use the "format" value from list_google_ads_accounts (e.g., "1234567890") HIERARCHY LEVELS: - campaign: Overall campaign performance - ad_group: Ad group level data within campaigns - ad: Individual ad performance with headlines, descriptions, final URLs - keyword: Individual keyword performance with match types AVAILABLE METRICS: - Performance: impressions, clicks, ctr, interactions, interactionRate, videoViews, videoViewRate, engagements, phoneCalls, phoneImpressions, phoneCallRate - Cost: cost, averageCost, averageCpc, averageCpm, averageCpv - Conversions: conversions, conversionValue, costPerConversion, conversionRate, allConversions, allConversionsValue, viewThroughConversions - ROI: roas (Return on Ad Spend) - Competitive: searchImpressionShare, searchBudgetLostImpressionShare, searchRankLostImpressionShare, searchTopImpressionShare, searchAbsoluteTopImpressionShare, searchExactMatchImpressionShare - Quality: qualityScore AVAILABLE SEGMENTS (breakdowns): Segment compatibility varies by level: campaign level supports: - Time: date, day_of_week, week, month, quarter, year, hour - Device: device (Mobile, Desktop, Tablet) - Network: ad_network_type (Search, Display, YouTube) - Conversions: conversion_action (break down by conversion type name), conversion_action_category - Other: click_type ad_group level supports: - Time: date, day_of_week, week, month, quarter, year, hour - Device: device - Network: ad_network_type - Conversions: conversion_action, conversion_action_category - Other: click_type ad level supports: - Time: date, day_of_week, week, month, quarter, year, hour - Device: device - Network: ad_network_type - Conversions: conversion_action, conversion_action_category - Other: click_type keyword level supports: - Time: date, day_of_week, week, month, quarter, year, hour - Device: device - Network: ad_network_type - Conversions: conversion_action, conversion_action_category FILTERING: - campaignName: Filter campaigns by name (partial match, e.g., "Brand") - campaignStatus: Filter by status (ENABLED, PAUSED) - campaignType: Filter by type (search, display, shopping, video, performance_max, demand_gen) - adGroupName: Filter ad groups by name (partial match) SORTING & LIMITING: - sortBy: Sort results by any metric (e.g., "cost", "clicks", "conversions") - sortOrder: "asc" or "desc" (default: desc) - limit: Maximum number of rows to return COMPARISON: - compareWith: "previous_period" or "previous_year" to compare current period with a prior period - Returns both periods and percentage change for each metric EXAMPLES: - Campaign performance overall: level=campaign, metrics=[cost, clicks, conversions] - Campaign by device: level=campaign, segments=[device], metrics=[cost, clicks] - Top 10 keywords by cost: level=keyword, metrics=[cost, clicks, ctr], sortBy=cost, limit=10 - Search campaigns only: level=campaign, metrics=[cost, clicks], filters={campaignType: "search"} - Conversions by type: level=campaign, segments=[conversion_action], metrics=[conversions, conversionValue] - Ad copy performance: level=ad, metrics=[impressions, clicks, ctr, conversions] - Compare with last period: level=campaign, metrics=[cost, conversions, roas], compareWith=previous_period Queries the Google Ads API (developers.google.com/google-ads/api). |
| get_meta_ads_metrics | Get Meta Ads (Facebook & Instagram) advertising performance metrics. USE THIS TOOL FOR: - Facebook and Instagram ad performance - Ad spend, impressions, reach, clicks - Campaign, Ad Set, or individual Ad level data - ROAS (Return on Ad Spend) and conversion tracking - Audience demographics and geographic performance - Ad creative analysis (images, titles, body text, CTAs) - OPTIONAL, only when requested THIS IS FOR META PAID ADS ONLY - for organic social media use other analytics tools. AD CREATIVE ANALYSIS (OPTIONAL): - Set include_creatives=true to fetch ad creative data (images, titles, body text, CTAs) - Only available when level=ad (individual ad level) - Disabled by default for faster performance - When enabled, fetches: * Full-resolution ad images (1024x1024+) * Ad titles and body text * Call-to-action buttons * For dynamic creatives: all variations being tested - Use when user asks to "analyze my creatives", "show me ad images", etc. MULTI-ACCOUNT SUPPORT: - Use list_meta_ads_accounts tool to see all available accounts - Specify adAccountId parameter to query a specific account - If adAccountId not specified, uses your default account - Use the "format" value from list_meta_ads_accounts (e.g., "act_123456789") HIERARCHY LEVELS: - account: Overall account performance across all campaigns - campaign: Campaign-level performance (includes campaign_status and campaign_objective) - adset: Ad Set level data within campaigns - ad: Individual ad performance UNDERSTANDING CONVERSIONS — READ THIS: - 'results' is the PRIMARY conversion metric — it automatically matches the campaign's objective (e.g., Sales → purchases, Engagement → post_engagement, Messages → messaging_conversations) - 'conversions' only tracks pixel-based purchase events — returns 0 for engagement/traffic/messaging campaigns - For businesses that track WhatsApp/Messenger/Instagram DM messages as their main goal, use 'messaging_conversations' directly - When user asks for "conversions" or "results", ALWAYS include both 'results' and 'messaging_conversations' to show the full picture - If 'conversions' returns 0, check the campaign objective — the real results are likely in messaging_conversations, post_engagement, or link_clicks MESSAGING METRICS — WHAT THEY REALLY MEAN (relay this honestly, do not overstate): - messaging_conversations = conversations STARTED — an AD-attribution metric (a user's first message within a 7-day click window). It is NOT the number of messages sitting in a readable inbox, and it does NOT mean the business answered. - To show whether those conversations were actually HANDLED, also pull messaging_conversations_replied (how many the BUSINESS answered). A large gap (e.g. 211 started vs 19 replied) = leaking leads — frequently WhatsApp-routed conversations landing in a WhatsApp Business inbox nobody is monitoring. Proactively surface this gap when it is large. - messaging_depth_2 / messaging_depth_3 show how many turned into a real back-and-forth. - For the WhatsApp vs Messenger vs Instagram-Direct INBOX split, use get_meta_messaging_breakdown — that is different from publisher_platform (which is only where the AD was shown, FB feed vs IG feed). AVAILABLE METRICS: - Performance: impressions, reach, clicks, ctr, frequency, link_clicks, inline_link_click_ctr, unique_clicks, unique_ctr, unique_link_clicks - Results: results (auto-matches campaign objective), cost_per_result - Spending: spend, cpc, cpm, cpp, cost_per_unique_click, cost_per_inline_link_click - Link Engagement: outbound_clicks, cost_per_outbound_click, outbound_clicks_ctr - Conversions (from actions): purchases, leads, messaging_conversations, landing_page_views, add_to_cart, initiate_checkout, view_content, complete_registration, conversions (legacy pixel only) - Messaging funnel (answered-rate): messaging_first_reply, messaging_conversations_replied (business answered), messaging_depth_2, messaging_depth_3, total_messaging_connections - Cost per Action: cost_per_purchase, cost_per_lead, cost_per_messaging_conversation, cost_per_landing_page_view, cost_per_conversion - Revenue: purchase_value (total revenue from purchases) - Engagement: post_engagement, page_engagement, post_reactions, comments, shares - ROI: roas, website_purchase_roas, mobile_app_purchase_roas - Video: video_play_actions, video_p25_watched_actions, video_p50_watched_actions, video_p75_watched_actions, video_p100_watched_actions, video_30_sec_watched_actions, video_thruplay_watched_actions, video_avg_time_watched_actions - Quality: quality_ranking, engagement_rate_ranking, conversion_rate_ranking AVAILABLE BREAKDOWNS: - Demographics: age, gender - Geography: country, region, comscore_market (market area — replaces the retired 'dma') - Placement: publisher_platform (Facebook, Instagram, Messenger, Audience Network), device_platform - Time: date (for daily breakdown) - Creative Assets: body_asset (ad body text), title_asset (headlines), image_asset (images), video_asset (videos) * Shows performance split by individual creative elements * Example: See which body text variation got highest CTR * Most useful at ad level with dynamic creatives - Products: product_id — splits performance by individual product/SKU for catalog / Dynamic Product Ads (Advantage+ catalog) * THE view for e-commerce: which catalog products drive impressions/clicks/spend (and purchases/ROAS when the pixel tracks them) * Each row carries product_id and, when Meta provides it, product_name * Works at account/campaign/adset/ad level; pair with purchases/purchase_value/roas to rank SKUs by return FILTERING (narrow results before display): - campaignName: partial match on campaign name (e.g., "Brand" matches "Brand Awareness Q1") - campaignNameExact: exact match on campaign name - campaignStatus: filter by status — ACTIVE, PAUSED, DELETED, ARCHIVED (can be single or array) - campaignObjective: filter by objective — CONVERSIONS, LINK_CLICKS, REACH, etc. - adsetName: partial match on ad set name (only for adset/ad levels) Example: filters={campaignStatus: "ACTIVE"} → only active campaigns SORTING & LIMITING: - sortBy: sort rows by any metric (e.g., sortBy="spend") - sortOrder: "asc" or "desc" (default: desc) - limit: return top N rows (e.g., limit=5 for top 5) - Totals are always calculated from the FULL dataset before limiting Example: sortBy="spend", sortOrder="desc", limit=10 → top 10 by spend COMPARISON (period-over-period): - compareWith: "previous_period" or "previous_year" - Returns current totals, previous totals, and % change for each metric - previous_period = same number of days immediately before the date range - previous_year = same dates one year ago Example: compareWith="previous_period" → shows how metrics changed vs prior period DELIVERY STATUS (on vs off) — READ THIS BEFORE REPORTING WHAT'S RUNNING: - Every campaign/adset/ad row includes delivery_status — the ACTUAL delivery state of THAT row's entity (ACTIVE / PAUSED / CAMPAIGN_PAUSED / ADSET_PAUSED / etc.). Use delivery_status to say whether a campaign/ad set/ad is on or off. NEVER infer on/off from spend — a paused entity can still show spend in a past date range. - Also per row: campaign_status/campaign_effective_status/campaign_configured_status, and (at adset level) adset_status/adset_effective_status, and (at ad level) ad_status/ad_effective_status. effective_status = real delivery; configured_status = what the user set. status = effective||configured. - Plus campaign_objective. Useful for seeing which paused entities still had spend in the range. - At adset (and ad) level, rows also carry optimization_goal (what Meta optimizes delivery for — e.g. CONVERSATIONS, OFFSITE_CONVERSIONS, LINK_CLICKS) and destination_type (where the click goes — e.g. WHATSAPP, WEBSITE). These are enum STRINGS, not numbers. READ optimization_goal before making any claim about what an ad set is optimizing for — do NOT infer it from which metric is highest. - BUDGET STRUCTURE: every row carries is_cbo (boolean) + budget_level ("campaign (CBO)" or "ad_set (ABO)"). CBO = the budget lives on the CAMPAIGN (campaign_daily_budget / campaign_lifetime_budget) and Meta shifts it across ad sets automatically. ABO = each ad set has its OWN fixed budget (adset_daily_budget / adset_lifetime_budget). To answer "will budget shift between ad sets / to the best performer?": is_cbo=true → YES (shared, Meta reallocates); is_cbo=false → NO (per-ad-set, fixed). Budgets are in the account's major currency unit. IMPORTANT CONSTRAINTS: - CANNOT combine demographic breakdowns (age, gender) with geographic breakdowns (country, region, comscore_market) - Valid: age + gender together - Valid: country + region together - Invalid: age + country (will return error) - Invalid: gender + region (will return error) - CAN use 'date' breakdown with most other breakdowns for daily trends LEVEL BEHAVIOR: - Level determines which entity names are returned (campaign_name, adset_name, ad_name) - Do NOT use entity names as breakdowns - they are controlled by the level parameter - Example: level=campaign automatically includes campaign_name in results EXAMPLES: - Account overview: level=account, metrics=[spend, impressions, clicks] - Campaigns by age: level=campaign, breakdowns=[age], metrics=[spend, conversions] - Daily campaign performance: level=campaign, breakdowns=[date], metrics=[spend, roas] - Ads by platform: level=ad, breakdowns=[publisher_platform], metrics=[impressions, clicks] - Active campaigns only: level=campaign, metrics=[spend, roas], filters={campaignStatus: "ACTIVE"} - Top 5 campaigns by spend: level=campaign, metrics=[spend, clicks, ctr], sortBy="spend", limit=5 - Month-over-month comparison: level=account, metrics=[spend, roas], compareWith="previous_period" Queries the Meta Marketing API /act_{id}/insights endpoint (developers.facebook.com/docs/marketing-apis). |
| list_ga4_properties | Get all GA4 properties (Google Analytics 4) the user has access to. USE THIS TOOL WHEN: - User asks "What GA4 properties do I have?" - User mentions a specific property name (e.g., "ZylerAI", "My Blog") - You need to know available properties before querying - User wants to query a non-default property RETURNS: - List of all GA4 properties with their IDs and names - The correct format to use when calling get_ga4_metrics - Which property is set as default - Total count of available properties IMPORTANT: When calling get_ga4_metrics with a specific property, use the "format" value from this list. Queries the Google Analytics Admin API (developers.google.com/analytics/devguides/config/admin/v1). |
| list_google_ads_accounts | Get all Google Ads accounts the user has access to. USE THIS TOOL WHEN: - User asks "What Google Ads accounts do I have?" - User mentions a specific account name - You need to know available accounts before querying - User wants to query a non-default account RETURNS: - List of all Google Ads accounts with their IDs and names - The correct format to use when calling get_google_ads_metrics - Which account is set as default - Account status and type (manager vs regular account) IMPORTANT: - Only non-manager accounts can be queried for metrics - When calling get_google_ads_metrics, use the "format" value (customerId without dashes) Queries the Google Ads API (developers.google.com/google-ads/api). |
| list_meta_ads_accounts | Get all Meta Ads (Facebook/Instagram) accounts the user has access to. USE THIS TOOL WHEN: - User asks "What Meta Ads accounts do I have?" - User mentions a specific account name - You need to know available accounts before querying - User wants to query a non-default account RETURNS: - List of all Meta Ads accounts with their IDs and names - The correct format to use when calling get_meta_ads_metrics - Which account is set as default - Account currency and status IMPORTANT: When calling get_meta_ads_metrics, use the "format" value (with act_ prefix) for the adAccountId parameter Queries the Meta Marketing API /me/adaccounts endpoint (developers.facebook.com/docs/marketing-apis). |
| list_gsc_sites | Get all Google Search Console sites the user has access to. USE THIS TOOL WHEN: - User asks "What GSC sites do I have?" - User mentions a specific site/domain - You need to know available sites before querying - User wants to query a non-default site RETURNS: - List of all GSC sites with their URLs and permission levels - The correct format to use when calling get_gsc_metrics - Which site is set as default - Site type (domain property vs URL-prefix property) IMPORTANT: When calling get_gsc_metrics, use the "format" value exactly as shown (including sc-domain: prefix or full URL) Queries the Google Search Console API sites.list endpoint (developers.google.com/webmaster-tools/v1). |
| list_ga4_events | List all events tracked in your GA4 property with their event counts. This is essential for funnel analysis - use this first to see what events are available before creating funnels. USAGE: - Shows all events with their counts (e.g., "page_view: 15,234 events") - Helps users discover what events they're tracking - Required before using analyze_ga4_funnel MULTI-PROPERTY SUPPORT: - Use list_ga4_properties tool to see all available properties - Specify propertyId parameter to query a specific property Queries the Google Analytics Data API (developers.google.com/analytics/devguides/reporting/data/v1). |
| analyze_ga4_funnel | Analyze a conversion funnel using GA4's built-in funnel report API. This tracks actual user journeys through multiple steps and calculates drop-off rates. FEATURES: - Tracks SAME users completing steps in sequence - Calculates drop-off rates between steps - Shows overall conversion rate - Optional breakdown by dimension (device, source, country, etc.) USAGE: 1. First call list_ga4_events to see available events 2. Define funnel steps using event names 3. Get detailed conversion analysis EXAMPLE: { "steps": [ {"name": "Page View", "eventName": "page_view"}, {"name": "Add to Cart", "eventName": "add_to_cart"}, {"name": "Purchase", "eventName": "purchase"} ], "breakdown": "deviceCategory" } Queries the Google Analytics Data API funnelReport endpoint (developers.google.com/analytics/devguides/reporting/data/v1). |
| get_google_ads_search_terms | Get the Search Terms Report showing actual search queries that triggered your Google Ads. USE THIS TOOL FOR: - Discovering what users actually searched to trigger your ads - Finding negative keyword opportunities (irrelevant queries) - Identifying high-performing search terms to add as exact match keywords - Understanding match type behavior (broad/phrase/exact) - Analyzing search intent behind your ad traffic RETURNS FOR EACH SEARCH TERM: - The actual search query users typed - Which campaign and ad group it triggered - Performance metrics (clicks, impressions, cost, conversions, etc.) FILTERING: - campaignName: Filter to specific campaign(s) - campaignId: Filter by campaign ID SORTING: - Default: sorted by clicks descending - Use sortBy to sort by any metric - Use limit to control number of results (default: 50) EXAMPLES: - Top search terms by clicks: metrics=[clicks, impressions, cost, ctr] - Expensive search terms: metrics=[cost, clicks, conversions], sortBy=cost - Search terms for a specific campaign: campaignName="Brand Campaign", metrics=[clicks, cost] Queries the Google Ads API (developers.google.com/google-ads/api). |
| get_google_ads_budgets | Get Google Ads campaign budget information including daily budgets, total budgets, and budget utilization. USE THIS TOOL FOR: - "How much budget do I have?" - "Which campaigns are budget-limited?" - "What's my daily budget for each campaign?" - Campaign budget planning and optimization - Identifying underspending or overspending campaigns RETURNS FOR EACH CAMPAIGN: - Campaign name, status, and type - Daily budget amount - Total budget (if set) - Delivery method (standard vs accelerated) - Whether the budget is shared across campaigns - Amount spent and budget utilization percentage - Impressions and clicks FILTERING: - campaignStatus: Show only ENABLED or PAUSED campaigns - campaignName: Filter by campaign name (partial match) Queries the Google Ads API (developers.google.com/google-ads/api). |
| list_google_campaigns | List EVERY campaign in a Google Ads account — including PAUSED and zero-spend ones. USE THIS TOOL WHEN: - You need to find a campaign to UPDATE it (update_google_campaign needs its id) — especially one just created or paused - The user refers to "my campaign" and you need its id / status / type - Before creating a campaign, to check whether one already exists (avoid duplicates) WHY THIS EXISTS: get_google_ads_metrics only returns campaigns with delivery data; a paused / zero-spend campaign is INVISIBLE there. This lists from the campaign resource, so every campaign shows up regardless of spend. RETURNS: campaigns with id, name, status (ENABLED/PAUSED), type (channel), and dailyBudget. Pass a campaign id to update_google_campaign. |
| create_google_campaign | Create a Google Ads campaign with budget. The campaign is created in PAUSED state — no money is spent until manually enabled. This tool ONLY creates the campaign + budget. Use separate tools for targeting, assets, and ads. WORKFLOW (each step is a separate tool call): 1. create_google_campaign → returns campaignId (THIS TOOL) 2. set_campaign_targeting → locations, language, schedule, negative keywords (recommended) 3. set_campaign_assets → callouts, structured snippets (optional) 4. set_google_ads_audiences → demographics, remarketing lists (optional) 5. create_google_ad_group → ad group + keywords 6. create_google_ad → write ad copy If any step fails, retry just that step — the campaign already exists. IDEMPOTENT: If a campaign with the same name already exists, returns the existing campaign instead of creating a duplicate. CAMPAIGN TYPES: - SEARCH: Text ads on Google search results (most common for leads/sales) ✅ supported - DISPLAY: Banner ads across websites ✅ supported - PERFORMANCE_MAX / SHOPPING / VIDEO / DEMAND_GEN: ❌ NOT yet supported by this tool. Performance Max needs an asset group (images, logos, headlines, descriptions, optionally video) plus conversion goals to serve — asset-group creation is not yet built, so a PMax campaign made here would be an empty shell that cannot run. Shopping/Video/Demand Gen need Merchant Center, a linked YouTube channel, or creative assets this tool does not pass to Google. The tool rejects all of these upfront with a clean error. Use the Google Ads UI directly for these campaign types, or pick SEARCH / DISPLAY here. BIDDING STRATEGIES: - MAXIMIZE_CLICKS: Get most clicks within budget (best for new campaigns, no conversion history needed) - MAXIMIZE_CONVERSIONS: Get most conversions — requires at least one conversion action set up in Google Ads - TARGET_CPA: Hit a target cost-per-acquisition — requires conversion tracking + targetCpa parameter (recommend 30+ historical conversions) - TARGET_ROAS: Hit a target return on ad spend — requires conversion value tracking + targetRoas parameter - MANUAL_CPC: Set your own max CPC bids (full control, no conversion tracking needed) If a user does NOT yet have conversion tracking set up, recommend MAXIMIZE_CLICKS or MANUAL_CPC. Conversion-based bidding without conversion actions configured will be rejected by Google. SAFETY: Campaign is ALWAYS created as PAUSED. Budget capped at $500/day. TESTING TIP: For testing/review, prefer accounts where isTestAccount=true (visible in list_google_ads_accounts output) to avoid affecting production accounts. Calls the Google Ads API mutate endpoint to create the campaign (developers.google.com/google-ads/api). |
| create_google_campaign_full | Create a COMPLETE Google Ads Search campaign in ONE call: campaign + budget, ad group + keywords, and a responsive search ad — plus optional location targeting and negative keywords. Everything is created PAUSED; no money is spent until activated. PREFER THIS over the 4-6 step granular flow (create_google_campaign -> set_campaign_targeting -> create_google_ad_group -> create_google_ad) for new Search campaigns. SAFE TO RE-RUN with the same arguments after a partial failure: the campaign and ad group dedupe by name (existing ones are reused, not duplicated). Only re-run the full call if the AD step never succeeded. SEARCH campaigns only. For Display/PMax use the granular create_google_campaign; Shopping/Video/Demand Gen are not supported via API tools. Calls the Google Ads API campaign/adGroup/adGroupAd/criterion mutate endpoints. |
| get_google_ads_change_history | See WHO changed WHAT in a Google Ads account, and WHEN — budgets, bid strategies, statuses, keywords, targeting. USE THIS TOOL WHEN: - Performance shifted and the user asks "why did my CPA/cost/CTR change?" — check what changed right before the shift - User asks "what changed in my account this week?" / "did anyone touch my campaigns?" - Auditing an account: pair metric anomalies with the change that caused them - Verifying whether an automation/rule or a person made a change (the "via" field) RETURNS (newest first): when, who (user email), via (web UI / API / automated rule), resource type, operation (CREATE/UPDATE/REMOVE), campaign/ad group context, the changed fields, and best-effort old→new values (money fields already converted from micros). LIMITS (Google API): history covers only the LAST 30 DAYS, max 1000 rows per query. Date range outside that window is clamped automatically (noted in the response). ANALYST PATTERN: fetch metrics with segments=["date"], spot the day performance shifted, then fetch change history around that day — "your CPA jump started Tuesday; Monday 4pm someone switched the bid strategy." Queries the Google Ads API change_event resource (read-only). |
| manage_google_conversions | List or create Google Ads conversion actions — the prerequisite for smart bidding. WHY THIS MATTERS: MAXIMIZE_CONVERSIONS / TARGET_CPA / TARGET_ROAS bidding REQUIRE at least one enabled conversion action. Without one, campaign creation with those strategies fails. This tool closes that gap without leaving Claude. ACTIONS: - list: see every conversion action (name, category, status, counting, whether it counts toward the "conversions" metric). ALWAYS list first before creating — the account may already track what the user needs. - create: create a WEBPAGE conversion action (category: PURCHASE / SUBMIT_LEAD_FORM / QUALIFIED_LEAD / PHONE_CALL_LEAD / SIGNUP / PAGE_VIEW / ADD_TO_CART / BEGIN_CHECKOUT / BOOK_APPOINTMENT / REQUEST_QUOTE / CONTACT). Returns the TRACKING SNIPPETS (global site tag + event snippet) — the user MUST install these on their website before conversions record. Creating the action alone does not track anything. AFTER CREATING, tell the user clearly: 1. The conversion action exists in Google Ads (no spend impact) 2. They must add the event snippet to their site's conversion page (or via Google Tag Manager) 3. Once the tag fires, smart bidding strategies become usable SAFETY: non-spending writes only. No delete — removed actions break historical reporting; pause in the Google Ads UI instead. Calls the Google Ads API ConversionActionService (developers.google.com/google-ads/api). |
| get_google_recommendations | Read Google's OWN optimization recommendations for the account — the suggestions that sit unread in the Google Ads Recommendations tab. USE THIS WHEN: - User asks "how can I improve my campaigns?" / "any optimization ideas?" - During an account audit (pair with metrics + change history) - Before scaling: Google often flags budget-limited campaigns here RETURNS: each recommendation with its type, campaign, estimated impact (clicks/cost/conversions now vs potential), and payload details (e.g. current vs recommended budget, suggested keyword). Plus whether each type is APPLYABLE via apply_google_recommendation. WORKFLOW: present the recommendations to the user grouped by type with impact numbers → user picks → apply_google_recommendation ONE at a time for approved ones. NEVER apply without the user explicitly choosing — these change a live account. Queries the Google Ads API recommendation resource (read-only). |
| apply_google_recommendation | Apply (or dismiss) ONE Google recommendation by its resource name — only after the user explicitly approved it. ALLOWLISTED types (additive/cheap/reversible, parameter-free): KEYWORD, CAMPAIGN_BUDGET, MOVE_UNUSED_BUDGET, RESPONSIVE_SEARCH_AD. For CALLOUT_ASSET / SITELINK_ASSET recommendations, do NOT apply here — implement the suggestion via set_campaign_assets with explicit texts instead (Google's apply demands parameters we don't pass). EVERYTHING ELSE (bid strategy changes, match-type migrations, target adjustments) is REFUSED by design — those reshape account economics and must be done by a human in the Google Ads UI. SAFETY: - Budget recommendations are re-checked against the $500/day USD-equivalent cap before applying — over-cap applies are refused - Applying on an ENABLED campaign changes live spend behavior — confirm with the user that they understand - action="dismiss" hides a recommendation Google keeps resurfacing (no account change) Calls the Google Ads API RecommendationService apply/dismiss. |
| create_google_ad_group | Create an ad group with keywords inside an existing Google Ads campaign. BEFORE CALLING THIS TOOL: - You need a campaignId (from create_google_campaign or an existing campaign) - Gather keyword list from the user — recommend 10-20 keywords per ad group - Ask about match type preference if not specified (PHRASE is recommended for new campaigns) MATCH TYPES: - BROAD: Widest reach, Google matches related searches (default) - PHRASE: Matches searches containing your keyword phrase (recommended for new campaigns) - EXACT: Only matches exact searches (most restrictive, highest relevance) TIPS FOR THE AI: - Group keywords by theme (e.g., "running shoes" keywords in one group, "hiking boots" in another) - Recommend PHRASE match for new campaigns — gives control while gathering data - Suggest 10-20 keywords per ad group — too many dilutes relevance - If the user gives a broad topic, suggest specific keywords for them WORKFLOW: 1. create_google_campaign → returns campaignId 2. create_google_ad_group (with campaignId) → returns adGroupId ← YOU ARE HERE 3. create_google_ad (with adGroupId) → creates the ad TESTING TIP: For testing/review, prefer accounts where isTestAccount=true (visible in list_google_ads_accounts output) to avoid affecting production accounts. Calls the Google Ads API mutate endpoint to create the ad group (developers.google.com/google-ads/api). |
| create_google_ad | Create a responsive search ad (RSA) inside an existing ad group. Created in PAUSED state. BEFORE CALLING THIS TOOL: - You need an adGroupId (from create_google_ad_group or existing) - Write headlines and descriptions that fit character limits BEFORE calling - Headlines: 3-15 required, each MAX 30 characters (count carefully!) - Descriptions: 2-4 required, each MAX 90 characters (count carefully!) CHARACTER LIMIT RULES — STRICTLY ENFORCED: - If a headline exceeds 30 characters, shorten it BEFORE calling this tool - If a description exceeds 90 characters, shorten it BEFORE calling this tool - Common fixes: use "&" instead of "and", abbreviate words, remove filler words - The API will reject any headline >30 or description >90 — do not submit and hope TIPS FOR WRITING GOOD ADS: - Use all 15 headline slots for best performance - Include target keywords in headlines (improves Quality Score) - Use numbers and specific claims ("4.9/5 Rated", "100+ Clients") - Include a call-to-action ("Book Free Meeting", "Get Started Today") - Mention pricing if competitive ("From AED 760/Month") - Use path1/path2 to show relevant URL path (e.g., path1="tutoring", path2="dubai") WORKFLOW: 1. create_google_campaign → campaignId 2. create_google_ad_group (campaignId) → adGroupId 3. create_google_ad (adGroupId) → ad created ← YOU ARE HERE TESTING TIP: For testing/review, prefer accounts where isTestAccount=true (visible in list_google_ads_accounts output) to avoid affecting production accounts. Calls the Google Ads API mutate endpoint to create the ad (developers.google.com/google-ads/api). |
| create_meta_campaign | Create a new Meta Ads (Facebook/Instagram) campaign. CREATES A CAMPAIGN IN PAUSED STATE — no money will be spent until activated in Meta Ads Manager. WORKFLOW: 1. create_meta_campaign → Get campaignId 2. create_meta_adset (with campaignId) → Get adSetId 3. create_meta_ad (with adSetId) → Ad is ready (still paused) OBJECTIVES (v21 outcome-based): - OUTCOME_TRAFFIC: Drive traffic to a website or app - OUTCOME_LEADS: Generate leads via forms or messages - OUTCOME_SALES: Drive purchases or conversions - OUTCOME_AWARENESS: Maximize reach and brand awareness - OUTCOME_ENGAGEMENT: Get more post engagement, video views, or page likes - OUTCOME_APP_PROMOTION: Drive app installs BUDGET: - Daily budget in the AD ACCOUNT'S currency (e.g. 50 = 50 units/day, so 50 ZAR on a ZAR account) - A ≈$50-equivalent/day safety ceiling applies (currency-aware) — raise it directly in Meta Ads Manager if you need more - Budget can also be set at ad set level (CBO vs ABO) SPECIAL AD CATEGORIES: - Required by Meta for regulated industries - HOUSING, EMPLOYMENT, CREDIT, ISSUES_ELECTIONS_POLITICS - If your ads relate to these, you MUST include the category MULTI-ACCOUNT: - Specify metaAdsAccountId to target a specific account - Use list_meta_ads_accounts to see available accounts Calls the Meta Marketing API POST /act_{id}/campaigns endpoint (developers.facebook.com/docs/marketing-apis). |
| create_meta_campaign_full | Create a COMPLETE Meta Ads campaign (campaign + ad set + ad with creative) in ONE call, from a plain-language goal. Everything is created PAUSED — nothing spends until activated. PREFER THIS TOOL over the 3-step create_meta_campaign -> create_meta_adset -> create_meta_ad flow. You give a goal; the server picks the correct Meta objective / optimization / destination / CTA combination and validates the config BEFORE any write (so doomed configs fail instantly with the exact fix, instead of half-creating things). GOALS: - whatsapp_messages: click-to-WhatsApp ads (needs pageId with WhatsApp connected + an image) - messenger_messages: click-to-Messenger (needs pageId + image) - lead_form: instant on-Facebook lead form (needs pageId + image + leadForm or leadGenFormId; Page must have accepted Lead Gen ToS — checked automatically) - website_traffic: clicks to a website (needs linkUrl) - website_sales: conversions/sales (needs linkUrl; account should have an active Pixel) - awareness: reach/brand awareness IF A STEP FAILS MIDWAY the error tells you exactly what was already created (all PAUSED, safe) and how to RESUME with the granular tools — do NOT re-run this tool from scratch after a partial failure, it would duplicate the campaign. NO CREATIVE YET? Pass stopAfter="adset" to build the campaign + ad set and stop cleanly before the ad — no image/message/headline needed. It returns the campaign + ad-set ids (ad:null, success, not an error); add the ad later with create_meta_ad. Use this when the user wants a campaign + ad set but has no image yet, instead of falling back to create_meta_campaign alone and stranding the ad set. Calls POST /campaigns, /adsets, /adcreatives, /ads on the Meta Marketing API. |
| create_meta_adset | Create an ad set inside an existing Meta Ads campaign. BEFORE CALLING THIS TOOL: - You need a campaignId from create_meta_campaign or an existing campaign - Know the target countries (ISO codes like US, GB, AE) - Know the optimization goal that matches the campaign objective AD SET = TARGETING + BUDGET + SCHEDULE - In Meta, targeting lives on the ad set (unlike Google where it's on the campaign) - Budget can be at campaign level (CBO) or ad set level (ABO) - If campaign has a daily budget (CBO), you don't need one here OPTIMIZATION GOALS (must match campaign objective): - OUTCOME_TRAFFIC → LINK_CLICKS or LANDING_PAGE_VIEWS - OUTCOME_LEADS → LEAD_GENERATION - OUTCOME_SALES → OFFSITE_CONVERSIONS - OUTCOME_AWARENESS → REACH or IMPRESSIONS - OUTCOME_ENGAGEMENT → IMPRESSIONS or REACH TARGETING: - countries: ISO country codes ["US", "GB", "AE"] — required UNLESS you pass locations - locations: city/region targeting. When the user names a city (e.g. "Dubai"), call search_meta_targeting type="location" FIRST to get its key, then pass locations=[{type:"city", key:"<key>"}]. Can be combined with countries. - ageMin/ageMax: 18-65 range - genders: [0]=all, [1]=male, [2]=female - interests: [{id: "6003139266461", name: "Fitness"}] — use Meta interest IDs WORKFLOW: 1. create_meta_campaign → campaignId ✓ 2. create_meta_adset (this tool) → adSetId 3. create_meta_ad (with adSetId) → Ad is ready Calls the Meta Marketing API POST /act_{id}/adsets endpoint (developers.facebook.com/docs/marketing-apis). |
| create_meta_ad | Create a Meta Ads ad with creative (image + text + link). This tool creates BOTH the Ad Creative and the Ad in one call. BEFORE CALLING THIS TOOL: - You need an adSetId from create_meta_adset - pageId is OPTIONAL — if omitted and the user has exactly one Facebook Page, we'll auto-pick it. If they have multiple, call list_meta_pages first. - For the creative image, prefer imageHash (from list_meta_creatives) over imageUrl. imageHash reuses an existing image without re-upload. WHAT THIS TOOL DOES (in order): 1. Resolves pageId — uses provided id, or auto-picks if user has only one Page 2. Creative source — uses imageHash (no upload), or downloads imageUrl and uploads, or uses link preview if neither provided 3. Creates an Ad Creative with the copy + image + CTA 4. Creates an Ad that links the creative to the ad set AD COPY COMPONENTS: - message: Primary text shown above the image (the main ad body) - headline: Bold text below the image - description: Additional text below the headline (optional) - linkUrl: Where users go when they click - imageHash: Hash of an existing image in the account's library (preferred — call list_meta_creatives first) - imageUrl: URL of an image to download and upload (used if imageHash not provided) - For WhatsApp/Messenger/lead ads (destinationType set), an image is REQUIRED — there is no link preview to auto-generate one. Pass imageHash (from list_meta_creatives) or imageUrl. CALL TO ACTION OPTIONS: LEARN_MORE, SHOP_NOW, SIGN_UP, BOOK_TRAVEL, CONTACT_US, GET_QUOTE, APPLY_NOW, DOWNLOAD, WATCH_MORE, SUBSCRIBE, GET_OFFER, ORDER_NOW WORKFLOW: 1. create_meta_campaign → campaignId ✓ 2. create_meta_adset → adSetId ✓ 3. (optional) list_meta_pages — confirm pageId if user has multiple Pages 4. (optional) list_meta_creatives — pick an existing image to reuse 5. create_meta_ad (this tool) → Ad is ready (still paused) Calls the Meta Marketing API POST /act_{id}/ads endpoint (developers.facebook.com/docs/marketing-apis). |
| list_meta_pages | Get all Facebook Pages the user can post ads from. USE THIS TOOL WHEN: - Before calling create_meta_ad (every ad must post from a Page) - User asks "what FB pages do I have?" - User mentions a specific Page name and you need its ID RETURNS: - Lean list of Pages: id, name, category, linked Instagram account, and "source" (pictureUrl only if includePicture=true) - The "id" field is the pageId you pass to create_meta_ad - Includes Pages the AD ACCOUNT can advertise from (source: "ad_account_promotable"), so a client's Page is found even when your connected login has NO direct role on it — pass metaAdsAccountId to scope to that account. This is how the clinic/client Page shows up for agency accounts. - If the user only manages one Page, create_meta_ad will use it automatically — but it's still useful to surface it for confirmation TIP: to build a campaign for a specific account, prefer get_meta_build_assets — it returns just that account's business's Page (+ pixels/IG) in one small response, instead of every Page you manage. Queries the Meta Graph API /me/accounts + businesses' owned/client pages, merged with /act_<id>/promote_pages (developers.facebook.com/docs/graph-api). |
| get_meta_build_assets | Resolve EVERYTHING needed to build a Meta campaign for an ad account — in ONE small, targeted call. USE THIS TOOL WHEN: - Before building a Meta campaign/ad set/ad (create_meta_campaign_full, create_meta_adset, create_meta_ad) - You need the account's Page (to post from / for click-to-WhatsApp), a pixel (sales/conversions), the Instagram account, or a product catalog - INSTEAD of calling list_meta_pages + pixel lookups separately (those return large lists that can truncate a small context — the "listed all pages, cut off before the clinic" failure) WHY THIS EXISTS: it maps the ad account to its owning Business (account.business.id) and returns just THAT business's build assets — the RIGHT Page (not a dump of every brand you manage), its pixels, IG, and catalog. Small, focused, no truncation. RETURNS: - account { id, name, currency, timezone }, business { id, name } - pages: the business's Page(s) — { id, name, category, instagramAccount, canAdvertise }. Pass id as pageId to create_meta_adset / create_meta_ad. - pixels: [{ id, name }] — pass id as pixelId for OUTCOME_SALES / OFFSITE_CONVERSIONS. - instagramAccounts, catalogs - whatsapp { available:false, note }: the WhatsApp NUMBER is not readable (needs a Meta permission this connection doesn't hold). You do NOT need it to build a click-to-WhatsApp ad — pass the pageId and Meta uses the Page's linked number. Resolves account → business (owned_pages/client_pages, account adspixels, owned_product_catalogs), with /act/promote_pages as a Page fallback. |
| list_meta_campaigns | List EVERY campaign in a Meta Ads account — including PAUSED and zero-spend ones. USE THIS TOOL WHEN: - You need to find a campaign to UPDATE it (update_meta_campaign / update_meta_adset need its id) — especially one just created that hasn't spent yet - The user refers to "my campaign" / "the campaign we made" and you need its id or status - Before creating a campaign, to check whether one already exists (avoid duplicates) WHY THIS EXISTS: get_meta_ads_metrics only returns campaigns that DELIVERED (have spend). A brand-new or paused campaign has no insights, so it is INVISIBLE there. This lists from the /campaigns edge, so every campaign shows up regardless of spend. RETURNS: campaigns with id, name, status (configured ACTIVE/PAUSED), effectiveStatus (actual delivery), objective, budgetLevel (CBO/ABO), dailyBudget/lifetimeBudget, and adSets[] (id, name, status, optimizationGoal) — the ids you pass to update_meta_adset. Queries the Meta Marketing API /act_{id}/campaigns edge (developers.facebook.com/docs/marketing-apis). |
| get_meta_page_engagement | Get organic engagement metrics on posts from a Facebook Page. USE THIS TOOL WHEN: - User asks "how did my Facebook page perform last week?" - User asks about post-level engagement (reactions, comments, shares, reach) - User wants to compare organic Page performance vs paid ad performance - User mentions a specific Page name and wants its recent post activity RETURNS: - Page info (name, category) - Top posts in the date range, ranked by total engagement (reactions + comments + shares) - Per-post metrics: reactions, comments, shares, impressions, reach, engaged_users - A snippet of each post's text + permalink URL WORKFLOW: 1. (optional) list_meta_pages — if the user has multiple Pages and you don't know which one 2. get_meta_page_engagement with pageId — fetches organic engagement on that Page This is for ORGANIC Page posts only. For paid Meta Ads performance, use get_meta_ads_metrics instead. Queries the Meta Graph API /{page-id}/posts and /{post-id}/insights endpoints (developers.facebook.com/docs/graph-api). |
| get_meta_messaging_breakdown | Break down Meta click-to-message CONVERSATIONS by which messaging app (inbox) they went to — WhatsApp vs Messenger vs Instagram Direct. USE THIS TOOL WHEN: - User asks "how many conversations on WhatsApp vs Messenger vs Instagram?" - User wants messaging results split by INBOX/app. - NOTE: this is different from where the ad was SHOWN (Facebook feed vs Instagram feed) — for that, use get_meta_ads_metrics with breakdowns=["publisher_platform"]. HOW IT WORKS: - The messaging app is decided at the AD-SET level (destination_type), not via an insights breakdown. This groups ad-set conversations + spend by that destination. IMPORTANT LIMITATION (always relay the returned 'note'): - Ad sets using Advantage+ MULTI-destination messaging (e.g. "Instagram Direct + WhatsApp") let Meta route each conversation to one app dynamically and Meta does NOT report which. Those land in a "Multi-app (not splittable)" bucket. Only single-destination ad sets give an exact inbox. RETURNS: per-app conversations, % share, spend, cost per conversation, single_app flag; plus totals and a note about any multi-app portion. |
| list_wordpress_posts | List posts on the user's connected WordPress site (inventory + search) — the content you'd audit or improve for SEO. USE WHEN: - User asks "what posts/pages do I have?" - You need to find a post before auditing or refreshing it. RETURNS: id, title, slug, status, modified date, URL, word_count. For one post's full content + SEO meta, use get_wordpress_post. Requires a connected WordPress site. Queries the hikmah-publisher plugin (/wp-json/hikmah/v1/list-posts). |
| get_wordpress_post | Get the full content + SEO meta of one WordPress post (for SEO analysis or before a refresh). RETURNS: title, slug, status, full content, word_count, SEO meta (Rank Math + Yoast title/description), faq_count, and elementor_built. IMPORTANT: if elementor_built is true, the visible page renders from Elementor — editing post_content will NOT change what visitors see. Get postId from list_wordpress_posts. Queries /wp-json/hikmah/v1/get-post. |
| audit_wordpress_seo | Audit the user's WordPress site for SEO opportunities — fuses their post inventory with Google Search Console rankings into a PRIORITIZED "fix these pages" list. This is the SEO audit. WHAT IT DOES: - Pulls published posts (content + word_count) from the connected WordPress site. - Pulls page-level GSC data (clicks, impressions, CTR, avg position) for the matching property. - Joins them BY URL PATH (so a staging/dev host still matches the live GSC property) and flags: * low_ctr_quick_win — ranks (position <=20) with impressions but low CTR -> rewrite title/meta (highest ROI) * striking_distance — avg position 5-20 -> push to page 1 with content / internal links * thin_content — short posts worth expanding * no_gsc_data — published but getting no search impressions (indexing / relevance) - Returns opportunities ranked by opportunity_score. USE WHEN: user asks "audit my SEO", "which pages should I improve", "where's my SEO opportunity". Then use get_wordpress_post to read a target page and propose the specific fix. Requires WordPress connected; GSC optional (without it -> content-only audit). Pass gscProperty to force a specific GSC site. |
| list_wordpress_authors | List the connected WordPress site's authors (and categories) — so you set the RIGHT author on a post. For E-E-A-T, content should be attributed to a real, named author (not "admin"); search engines and AI cite the credentialed author. RETURNS: authors [{id, login, name}], categories [{id, slug, name, count}], post_types. USE WHEN: before publish_blog_post / update_wordpress_post, to choose authorId (and categoryId). The right author for a given topic is the CUSTOMER's call (an agency maps its own topics→experts). Queries the plugin /wp-json/hikmah/v1/diagnostics. |
| audit_keyword_cannibalization | Find keyword CANNIBALIZATION — search queries where MULTIPLE of the user's OWN pages compete, splitting clicks + authority (e.g. several near-duplicate articles ranking for the same term). Complements audit_wordpress_seo (which is per-page); this is the cluster-level diagnosis. GSC-based, works for ANY site (no WordPress required). WHAT IT DOES: pulls GSC by query×page, groups by query, flags queries where 2+ of your pages get meaningful impressions. Returns the cannibalized queries with each competing page (URL, impressions, clicks, position), ranked by total impressions. USE WHEN: user asks about cannibalization, overlapping/duplicate content, or "which of my pages compete for the same keyword". Fix: consolidate the weaker pages into the best one, then 301-redirect or noindex them. Requires Google Search Console connected. |
| update_wordpress_post | Edit an existing WordPress post — rewrite SEO title/meta, refresh/append content, change slug, set noindex, or bump the modified date. This is how you ACTION an SEO audit finding (e.g. rewrite the title/meta on a high-impression / low-CTR page). To EXPLICITLY BLANK a field (not just overwrite it), pass clearFields, e.g. ["meta_title"] — use this to remove a wrong/leftover SEO title or description entirely (a value can't be cleared by passing an empty string). SAFETY: status changes to "publish" are BLOCKED unless live publishing is enabled for this connection (off by default) — other edits still apply. If the post is Elementor-built, content edits won't show on the live page (the response warns you). Get postId from list_wordpress_posts / audit_wordpress_seo. Premium feature. |
| set_post_faq_schema | Add or replace FAQPage structured data (JSON-LD in the page head) for a WordPress post — boosts Google rich results AND citations in AI search (ChatGPT/Perplexity). Elementor-safe: does NOT touch the visible content, only the schema. Pass faqs as [{question, answer}, ...], or clear:true to remove the FAQ schema. Get postId from list/audit. Premium feature. |
| publish_blog_post | Create a NEW blog post on the connected WordPress site from HTML you provide. DRAFT BY DEFAULT — never goes live unless live publishing is explicitly enabled for the connection. INPUT: pass the full article as html. Include an <h1> (becomes the post title), and optionally embed SEO meta as HTML comments: <!-- META TITLE: ... --> and <!-- META DESCRIPTION: ... -->. An FAQ section (an H2 "Frequently Asked Questions" followed by H3 question / P answer pairs) is auto-extracted into FAQPage schema. SAFETY: status defaults to "draft". status="publish" is BLOCKED unless live publishing is enabled (off by default) — saved as a draft instead. Author is auto-resolved from the connection if authorId is omitted. Premium feature. FLOW: audit_wordpress_seo / GSC finds a content gap -> you write the article -> publish_blog_post (draft) -> user reviews + publishes in WordPress. |
| set_wordpress_featured_image | Set a post's FEATURED IMAGE by sideloading an image from a URL. The image is downloaded into the WordPress media library and attached as the post's featured image (the social-share / blog-thumbnail picture). A missing featured image hurts click-through on social + blog listings. Pass postId + imageUrl (a publicly reachable image). Optional alt text (recommended for SEO + accessibility). Get postId from list_wordpress_posts / audit_wordpress_seo. Premium feature. |
| manage_wordpress_redirects | Manage 301/302 REDIRECTS on the connected WordPress site — forward an old/changed URL to a new one so visitors and Google don't hit a dead page and the old page's link equity flows to the new one. The natural follow-up after consolidating cannibalized pages (audit_keyword_cannibalization) or changing a slug. ACTIONS: - list — list all managed redirects. - create — add/replace a redirect. Requires from (old path, e.g. "/old-post") + to (new URL or path). Optional type (301 permanent [default] | 302 temporary). - delete — remove a redirect by its from path. NOTE: redirect management requires the connection's WordPress user to be an ADMIN (manage_options capability). Premium feature. |
| create_wordpress_author | Create a NEW author (byline) on the connected WordPress site — use when you want to attribute a post to a named expert who doesn't exist yet. ALWAYS check list_wordpress_authors first; only create if the author is genuinely missing. For E-E-A-T, content should be authored by a real, named, credentialed person — the bio you pass becomes the author profile that feeds Person/author schema. SAFE BY DESIGN: the author is created as a MINIMAL-PRIVILEGE profile with a random, unknown password — it cannot log in or change the site; it exists purely for attribution + the author archive/bio. Returns author_id so you can immediately pass it to publish_blog_post. NOTE: requires the connection's WordPress user to be an ADMIN (create_users). Premium feature. |
| open_seo_pr | Apply an SEO change to a connected GitHub repo (code-based site: Next.js / Astro / Hugo / Jekyll / static HTML) by opening a PULL REQUEST — never a direct push. The PR is the review gate; nothing goes live until the human merges it. Edits the file at `path`: - pass `title` and/or `description` for a targeted SEO-meta edit (frontmatter keys for .md/.mdx; <title> / <meta name="description"> for .html), OR - pass `content` to replace the whole file (full rewrite), OR - for a NEW post: pass `title` + `description` + `content` (the ARTICLE BODY) — it's wrapped in the customer's OWN site template automatically (md → their layout; static HTML → a skeleton cloned from their existing posts), so footer/logo/menu match. The repo's content path + template were auto-detected when the repo was connected. Use this after the SEO audit identifies a page to improve. Premium feature. Uses the GitHub REST API (docs.github.com/en/rest) to create the branch, commit the change, and open the pull request. |
| list_meta_creatives | List a Meta Ads account's creatives — both the ad creatives IN USE (with the ad names that reference them) and the raw uploaded image library. USE THIS TOOL WHEN: - The user names a creative ("use the Dr Tala static", "my summer promo creative") and you need to find it - Before create_meta_ad, to reuse an existing image or an existing creative - You want to suggest which existing creative/image fits the prompt TO FIND A NAMED CREATIVE, pass nameContains (e.g. "Tala"). The human label a user gives a creative lives on the AD, not on the image library (uploads are auto-named "untitled"/"bytes"). This searches BOTH ad names and creative names, across ALL ads (paused/old included) — so don't add a date filter in your head; if it exists, this finds it. RETURNS two lists: - "creatives" = ad creatives actually in use. Each has creativeId, creativeName, creativeType (SHARE = post-backed), a loadable imageUrl (+ permalinkUrl when permanent), imageHash (only when library-backed), reusableBy ("imageHash" or "creativeId"), and usedByAds (the ads using it, with status + campaign). This is where a named creative like "Dr Tala" is found. Post-backed creatives (image lives in a Page post, no hash) appear ONLY here, never in the image library. - "images" = the raw uploaded image library (hash, permalinkUrl, dimensions). Pass a hash as imageHash to reuse an uploaded image in a NEW ad. (Omitted during a nameContains search.) TO REUSE: a creative/image with an imageHash → pass imageHash to create_meta_ad. A post-backed creative (reusableBy "creativeId") is reused by its creativeId, not a hash. TO VIEW an image use permalinkUrl (permanent); "url" is a temporary signed link that can expire. Queries the Meta Marketing API /act_{id}/ads (creatives in use) + /act_{id}/adimages (library). |
| search_meta_targeting | Resolve detailed-targeting NAMES (interests, behaviors, life events, fields of study, job titles, industries, etc.) into the real Meta targeting IDs that create_meta_adset needs. WHY THIS EXISTS: Meta detailed targeting requires numeric IDs. You CANNOT invent them — Meta rejects fake IDs, and if you skip them the ad set silently falls back to BROAD geo+age targeting. So whenever a user asks to target specific interests/behaviors/etc., ALWAYS call this FIRST. HOW TO USE THE RESULTS: each result has {id, name, type, path, audience_size}. The "type" matters — it tells create_meta_adset which targeting field to use (e.g. "Pediatrics" comes back as type "education_majors", "Engaged Shoppers" as "behaviors"). Pass the chosen results straight through to create_meta_adset (or create_meta_campaign_full) as the detailedTargeting array — keep each item's id, name, AND type exactly as returned. (For plain interests you may also use the interests param, but detailedTargeting is preferred because it preserves the type.) TARGETING A CITY OR REGION (geo): Meta creates target at COUNTRY level unless you give a real location KEY. So whenever the user names a city or region (e.g. "Dubai", "California"), call this tool with type="location" FIRST to resolve the key — you CANNOT invent it. Results come back as {key, name, type ("city"/"region"/"country"), country_code, region}. Then pass the chosen one to create_meta_adset / create_meta_campaign_full / update_meta_adset as locations:[{type:"city", key:"<key>"}] (a city may add an optional radius + distanceUnit). countries still works unchanged for whole-country targeting, and can be combined with locations. Queries the Meta Marketing API /act_{id}/targetingsearch for detailed targeting, and /search?type=adgeolocation for locations (developers.facebook.com/docs/marketing-api). |
| list_meta_audiences | List the ad account's custom audiences (website visitors, customer lists, LOOKALIKES) and saved audiences, so you can target or exclude them by ID. Pass the chosen id(s) to create_meta_adset via customAudienceIds (to target) or excludedCustomAudienceIds (to exclude). Lookalikes appear here as custom audiences with subtype=LOOKALIKE. Queries the Meta Marketing API /act_{id}/customaudiences + /saved_audiences (developers.facebook.com/docs/marketing-api). |
| create_meta_custom_audience | Create a NEW Meta custom audience the user can then target (via create_meta_adset customAudienceIds) or model further. Two source types are supported: 1. WEBSITE — people who visited the user's site, captured by a Meta Pixel. Needs a pixel on the account (auto-selected if the account has exactly one; otherwise pass pixelId). Optional urlContains narrows to visitors of specific pages (e.g. "/pricing"). 2. LOOKALIKE — a new audience Meta models to resemble an existing source audience (originAudienceId). Needs a country and a ratio (1%–20%; 1% = closest match, smaller and higher-intent; larger = broader reach). NOT SUPPORTED here (by design): customer-list / email-upload audiences (they involve uploading personal data). Do not attempt them with this tool. WORKFLOW: - LOOKALIKE: call list_meta_audiences FIRST to get a valid originAudienceId (the source must already exist and be populated). - WEBSITE: if the account has multiple pixels, pass pixelId; otherwise it's auto-selected. - After creating, TARGET it by passing the returned id to create_meta_adset as customAudienceIds (or excludedCustomAudienceIds). IMPORTANT: a new audience takes time to populate before it can be used in a live ad set — the response returns its build status, which may show a small or still-building size at first. This creates a PERSISTENT, account-level audience (it is NOT auto-deleted). Requires Team or Agency plan. Queries the Meta Marketing API /act_{id}/customaudiences (developers.facebook.com/docs/marketing-api/audiences). |
| delete_meta_custom_audience | PERMANENTLY delete a Meta custom audience by ID. This cannot be undone. USE THIS TOOL WHEN: - The user explicitly asks to delete/remove a custom audience (or clean up test/old audiences). - Get the audienceId from list_meta_audiences first. IMPORTANT / SAFETY: - Deletion is irreversible — Meta does not restore deleted audiences. ALWAYS confirm the exact audience (name + id) with the user before calling. - Any ad sets currently targeting this audience will LOSE that targeting (their delivery may change). Warn the user if the audience might be in use. - Lookalikes built FROM this audience as their source may also be affected. Requires Team or Agency plan. Queries the Meta Marketing API DELETE /{custom-audience-id} (developers.facebook.com/docs/marketing-api/audiences). |
| update_meta_adset | Edit an existing Meta (Facebook/Instagram) ad set — change status, budget, targeting, optimization goal, schedule, or name. USE THIS TOOL FOR: - Pausing or activating an ad set - Changing daily/lifetime budget - Adjusting targeting (countries, age, gender, interests) - Switching optimization goal or billing event - Updating start/end schedule - Renaming an ad set IMPORTANT: - At least one update field is required - Daily budget capped at a ≈$50-equivalent/day safety ceiling, converted to the account currency (e.g. ~183 on an AED account); users can raise it in Meta Ads Manager - Status changes are reversible (PAUSED ↔ ACTIVE) - Setting status=ACTIVE will start spending money according to the budget — confirm with the user before calling - Targeting changes are partial: any targeting field provided REPLACES the corresponding section. To preserve existing targeting, omit the field. EXAMPLES: - Pause an ad set: adSetId="123", status="PAUSED" - Increase budget: adSetId="123", dailyBudget=40 - Change targeting countries: adSetId="123", countries=["US", "CA"] - Reschedule: adSetId="123", endTime="2026-12-31T23:59:59+0000" - Multiple changes: adSetId="123", status="ACTIVE", dailyBudget=25, ageMin=25, ageMax=55 Calls the Meta Marketing API POST /{adset-id} endpoint (developers.facebook.com/docs/marketing-apis). |
| update_meta_campaign | Edit an existing Meta (Facebook/Instagram) campaign — change status, budget (CBO only), bid strategy, special ad categories, or name. USE THIS TOOL FOR: - Pausing or activating a whole campaign (cascades to all ad sets) - Changing daily/lifetime budget when the campaign uses Campaign Budget Optimization (CBO) - Switching bid strategy (e.g. LOWEST_COST_WITHOUT_CAP → COST_CAP) - Adding or changing special ad categories (HOUSING, CREDIT, EMPLOYMENT, ISSUES_ELECTIONS_POLITICS) - Renaming a campaign IMPORTANT: - At least one update field is required - Daily budget capped at a ≈$50-equivalent/day safety ceiling, converted to the account currency (e.g. ~183 on an AED account); users can raise it in Meta Ads Manager - Status changes are reversible (PAUSED ↔ ACTIVE) - Setting status=ACTIVE on a campaign will resume spending across ALL its ad sets — confirm with the user first - Budget update only works on CBO campaigns. If the campaign uses ABO (per-ad-set budgets), update the ad set with update_meta_adset instead. - Objective cannot be changed after creation — recreate the campaign if you need a different objective. EXAMPLES: - Pause a campaign: campaignId="123", status="PAUSED" - Increase CBO budget: campaignId="123", dailyBudget=30 - Switch bid strategy: campaignId="123", bidStrategy="COST_CAP" - Add special ad category: campaignId="123", specialAdCategories=["HOUSING"] - Multiple changes: campaignId="123", status="ACTIVE", dailyBudget=25 Calls the Meta Marketing API POST /{campaign-id} endpoint (developers.facebook.com/docs/marketing-apis). |
| update_meta_ad | Edit an existing Meta (Facebook/Instagram) ad — pause/activate, rename, or swap to a different creative. USE THIS TOOL FOR: - Pausing or activating an individual ad (without affecting others in the same ad set) - Renaming an ad - Swapping the creative — replace the image/copy with a different creative from the ad account's library IMPORTANT: - At least one update field is required - Status changes are reversible (PAUSED ↔ ACTIVE) - Setting status=ACTIVE will start spending money against this ad — confirm with the user first - Creative swaps require an existing creativeId from the ad account. Use list_meta_creatives to find candidates, or create a new creative first. - Most other ad fields (headline, body, link URL) are baked into the creative — to change them, create a new creative and swap to it. - The ad's parent ad set must be accessible (writable account, etc.) for changes to apply. EXAMPLES: - Pause an ad: adId="123", status="PAUSED" - Rename: adId="123", name="My better ad name" - Swap creative: adId="123", creativeId="987" - Edit copy (no new campaign): adId="123", headline="New headline" — builds a new creative with your change and swaps the ad to it. Meta creatives are immutable, so editing copy ALWAYS means a new creative + swap; this tool does it for you on the SAME ad. - Activate (with money warning): adId="123", status="ACTIVE" Calls the Meta Marketing API POST /{ad-id} endpoint (developers.facebook.com/docs/marketing-apis). |
| get_google_keyword_ideas | Get keyword research data from Google Keyword Planner — search volume, competition, and CPC estimates. USE THIS TOOL FOR: - Keyword research for SEO or Google Ads campaigns - Finding search volume for specific keywords - Discovering related keyword ideas from a seed keyword or URL - Getting competition level and estimated CPC for keywords - Planning content strategy based on search demand SEED OPTIONS (at least one required): - seedKeywords: Provide keyword phrases (e.g., ["running shoes", "best sneakers"]) - seedUrl: Provide a webpage URL to extract keyword ideas from - Both: Combine keywords + URL for more relevant ideas LOCATION & LANGUAGE: - location: Target country, state/province, city, or region for localized search volume. Any location worldwide is resolved live against Google's geo-target database — use the plain name as-is (e.g., "United Arab Emirates", "Dubai", "California", "Johannesburg"); add the country to disambiguate (e.g. "Ajman, UAE"). - language: Target language (e.g., "English", "Arabic"). Default: English - IMPORTANT: Always specify location when the user's target market is in a specific country or region — search volumes vary dramatically by location. RETURNS FOR EACH KEYWORD: - keyword: The keyword text - avgMonthlySearches: Average monthly search volume - competition: LOW, MEDIUM, or HIGH - competitionIndex: 0-100 competition score - lowTopOfPageBid: Estimated low CPC bid (currency) - highTopOfPageBid: Estimated high CPC bid (currency) - monthlySearchVolumes: Monthly breakdown (when includeMonthlyVolumes=true) NOTE: Requires a Standard Google Ads developer token. If you get a PERMISSION_DENIED error, the account may have a Basic (test) developer token. EXAMPLES: - Keyword ideas for a topic: seedKeywords=["digital marketing dubai"] - Ideas from a webpage: seedUrl="https://example.com/services" - Localized volume: seedKeywords=["tutoring"], location="Dubai", language="English" - Combined seed: seedKeywords=["running shoes"], seedUrl="https://nike.com" Queries the Google Ads API Keyword Planner endpoint (developers.google.com/google-ads/api/docs/keyword-planning). |
| update_google_campaign | Edit an existing Google Ads campaign — change status, budget, bidding strategy, name, or UTM tracking. USE THIS TOOL FOR: - Pausing or enabling a campaign - Changing daily budget - Switching bidding strategy (e.g., maximize clicks → maximize conversions) - Renaming a campaign - Adding UTM parameters to all ads in a campaign (via finalUrlSuffix) - Setting a tracking template for click URL wrapping IMPORTANT: - At least one update field is required - Budget changes are capped at $500/day for safety - Status changes are reversible (PAUSED ↔ ENABLED) - Budget and bidding changes take effect immediately - finalUrlSuffix appends UTM params to ALL ads in the campaign (no need to edit individual ads) - trackingUrlTemplate wraps the final URL for 3rd-party tracking (must contain {lpurl}) - Switching to MAXIMIZE_CLICKS applies a max-CPC cap (pass cpcBidCeiling, else a default of 15 in account currency). TARGET_CPA needs targetCpa; TARGET_ROAS needs targetRoas. EXAMPLES: - Pause a campaign: campaignId="123", status="PAUSED" - Change budget: campaignId="123", dailyBudget=75 - Switch to maximize clicks with a cap: campaignId="123", biddingStrategy="MAXIMIZE_CLICKS", cpcBidCeiling=4 - Add UTM tracking: campaignId="123", finalUrlSuffix="utm_source=google&utm_medium=cpc&utm_campaign={_campaign}" - Set tracking template: campaignId="123", trackingUrlTemplate="{lpurl}?utm_source=google&utm_medium=cpc" - Multiple changes: campaignId="123", status="ENABLED", dailyBudget=100 TESTING TIP: For testing/review, prefer accounts where isTestAccount=true (visible in list_google_ads_accounts output) to avoid affecting production accounts. Calls the Google Ads API mutate endpoint to update the campaign (developers.google.com/google-ads/api). |
| update_google_ad | Pause, enable, or remove an individual Google Ads ad. USE THIS TOOL FOR: - Pausing a specific under-performing ad WITHOUT pausing its whole ad group - Re-enabling a paused ad - Removing an ad you no longer want to serve IMPORTANT: - The ad's creative (headlines/descriptions) is immutable — this tool only changes the ad's serving STATUS. To change copy, create a new ad (create_google_ad) and remove the old one. - ENABLED ↔ PAUSED is reversible. REMOVED is permanent — you can't un-remove; you'd recreate the ad. - Pass adId from get_google_ads_metrics with level="ad". If the same ad id exists in more than one ad group, also pass adGroupId to disambiguate (otherwise it's resolved automatically). EXAMPLES: - Pause an ad: adId="123456789", status="PAUSED" - Re-enable it: adId="123456789", status="ENABLED" - Remove it: adId="123456789", status="REMOVED" TESTING TIP: For testing/review, use an account you own — never a live client account, since pausing a real ad stops it serving. Calls the Google Ads API mutate endpoint on the ad_group_ad resource (developers.google.com/google-ads/api). |
| update_google_ad_group | Edit an existing Google Ads ad group — change status, name, or default CPC bid. USE THIS TOOL FOR: - Pausing or enabling an ad group - Renaming an ad group - Changing the default CPC bid IMPORTANT: - At least one update field is required (status, name, or defaultBid) - Pausing an ad group stops all ads and keywords in it - Status changes are reversible (PAUSED ↔ ENABLED) EXAMPLES: - Pause an ad group: adGroupId="456", status="PAUSED" - Change default bid: adGroupId="456", defaultBid=2.50 - Rename: adGroupId="456", name="Brand Keywords - US" TESTING TIP: For testing/review, prefer accounts where isTestAccount=true (visible in list_google_ads_accounts output) to avoid affecting production accounts. Calls the Google Ads API mutate endpoint to update the ad group (developers.google.com/google-ads/api). |
| manage_google_keywords | Bulk manage keywords in a Google Ads ad group — add, pause, enable, remove, update bids, change match types, or add/remove ad-group-level negative keywords. USE THIS TOOL FOR: - Adding new keywords to an existing ad group - Pausing or enabling keywords (by text or criterion ID) - Removing keywords permanently - Changing keyword CPC bids - Changing keyword match types (BROAD ↔ PHRASE ↔ EXACT) - Adding negative keywords AT THE AD GROUP LEVEL (use set_campaign_targeting for campaign-level negatives) OPERATIONS (batch multiple in one call): - add: Add new keywords with optional match type and bid - pause: Pause active keywords - enable: Re-enable paused keywords - remove: Permanently remove keywords (cannot be undone) - updateBid: Change CPC bid for existing keywords - changeMatchType: Change match type (removes and re-adds the keyword) - add_negative: Add an AD-GROUP-LEVEL negative keyword (blocks the term in this ad group only — siblings are unaffected). For campaign-wide negatives, use set_campaign_targeting instead. - remove_negative: Remove an ad-group-level negative keyword (by text + matchType, or by criterionId) KEYWORD IDENTIFICATION: - By text: Provide keyword text — the tool looks up the criterion ID automatically - By criterionId: Provide the criterion ID directly (from get_google_ads_metrics at keyword level) EXAMPLES: - Add keywords: operations=[{ action: "add", keywords: [{ text: "running shoes", matchType: "PHRASE" }] }] - Pause by text: operations=[{ action: "pause", keywords: [{ text: "cheap shoes" }] }] - Update bid: operations=[{ action: "updateBid", keywords: [{ text: "best shoes", bid: 3.50 }] }] - Change match type: operations=[{ action: "changeMatchType", keywords: [{ text: "shoes", matchType: "EXACT" }] }] - Add ad-group negative: operations=[{ action: "add_negative", keywords: [{ text: "free", matchType: "BROAD" }] }] - Remove ad-group negative: operations=[{ action: "remove_negative", keywords: [{ text: "free", matchType: "BROAD" }] }] - Multiple operations: operations=[{ action: "pause", keywords: [...] }, { action: "add", keywords: [...] }] TESTING TIP: For testing/review, prefer accounts where isTestAccount=true (visible in list_google_ads_accounts output) to avoid affecting production accounts. Calls the Google Ads API mutate endpoint on AdGroupCriterion (developers.google.com/google-ads/api). |
| get_campaign_negative_keywords | Get the list of negative keywords on a Google Ads campaign. USE THIS TOOL FOR: - Viewing which negative keywords are set on a campaign - Auditing negative keyword coverage before adding more - Checking if specific terms are already negated RETURNS: List of negative keywords with match type and status. Queries the Google Ads API (developers.google.com/google-ads/api). |