google-ads-tool-fundamentals

Foundation tool reference for any Google Ads task — GAQL syntax, common entity relationships, default reporting windows. Used internally when working with Google Ads tools.

SKILL.md

GitHub

Google Ads - Tool Fundamentals

How to use Google Ads tools effectively, plus the canonical metric definitions used across all Google Ads skills. Auto-loaded with every Google Ads skill request.

Tools

  • google_ads_run_gaql: primary read tool for Google Ads Query Language. Use for any structural or performance pull from campaign, ad_group, keyword_view, search_term_view, asset_group, geographic_view, shopping_performance_view, etc.
  • google_ads_propose_update_*: write tools for bid, budget, status, and structural changes (…_campaigns, …_adgroups, …_ads, …_asset, …_bid_modifiers, …_negative_keyword_list, …_pmax_asset_group). Money is in account currency, not micros. Always dry-run first and apply only after the user approves.
  • google_ads_keyword_discover / google_ads_keyword_metrics: keyword research; volume, CPC, competition, and forecast data.
  • google_ads_get_change_logs: audit account changes within a window.
  • google_ads_list_accounts: discover MCC structure and customer IDs.

Currency: Micros

Google Ads cost and bid fields are returned in micros (1,000,000 micros = 1 unit of the account currency).

Field Conversion
metrics.cost_micros divide by 1,000,000 to get cost in account currency
cpc_bid_micros divide by 1,000,000
amount_micros (campaign budget) divide by 1,000,000
metrics.average_cpc already in account currency — do NOT divide

Always confirm account currency before showing monetary values; never assume USD.

Date Filtering

Use GAQL relative ranges where possible — they're more reliable than fixed dates:

  • segments.date DURING LAST_7_DAYS
  • segments.date DURING LAST_30_DAYS
  • segments.date DURING LAST_90_DAYS
  • segments.date DURING THIS_MONTH / LAST_MONTH

For week-over-week or month-over-month comparison, run two queries with different DURING clauses and compute deltas locally.

Status Filtering

Always include campaign.status = 'ENABLED' (and ad_group.status = 'ENABLED' where relevant) when analyzing current performance — historical paused entities will otherwise pollute aggregates.

Pagination

GAQL responses can be large. Use LIMIT with ORDER BY metrics.cost_micros DESC to keep result sizes manageable; default to LIMIT 200 for entity-level pulls, LIMIT 100 for breakdown segments.

Account Context

Always run google_ads_list_accounts first to confirm the customer ID and check whether this is an MCC vs a leaf account. For MCC, ask the user which sub-account to operate on.

Metric Glossary

Canonical definitions used across all Google Ads skills. Workflow skills (google-ads-search-analysis, google-ads-pmax-evaluation, google-ads-shopping, google-ads-depth-of-analysis) reference these — they do NOT redefine them.

Direct Metrics (GAQL metrics.*)

Metric GAQL Field Notes
Cost metrics.cost_micros Divide by 1e6
Conversions metrics.conversions Includes all configured conversion actions unless filtered
Conversion value metrics.conversions_value Revenue for value-based conversions
Clicks metrics.clicks
Impressions metrics.impressions
Average CPC metrics.average_cpc Already in account currency
CTR metrics.ctr Decimal (0.05 = 5%)
Search IS metrics.search_impression_share
IS Lost (Rank) metrics.search_rank_lost_impression_share
IS Lost (Budget) metrics.search_budget_lost_impression_share
Top of Page Rate metrics.search_top_impression_percentage
Absolute Top Rate metrics.search_absolute_top_impression_percentage

Calculated Metrics

Metric Formula Notes
CPA (cost_micros / 1e6) / conversions Cost per conversion in account currency
ROAS conversions_value / (cost_micros / 1e6) Decimal multiple, e.g. 3.5 = 3.5×
CVR (Conversion Rate) conversions / clicks * 100
AOV total_conversions_value / total_conversions Account-level over the same window
CPC trend WoW (this_week_cpc - last_week_cpc) / last_week_cpc * 100 Use two relative-date queries
CPC trend MoM (this_month_cpc - last_month_cpc) / last_month_cpc * 100
Spend Share entity_cost / total_cost * 100 For prioritization within a campaign or account

Account-Type Inference

When the user has not stated account type, infer from data:

  • E-commerce: purchase conversion actions present AND non-zero metrics.conversions_value → use ROAS, AOV, CPA
  • Lead gen: conversions present AND metrics.conversions_value = 0 → use CPA only; ROAS unreliable unless offline conversion import is configured
  • Mixed: group campaigns by primary conversion action and apply each group's PCM separately
  • Unclear: ASK the user. Don't default.

Maturity & Statistical-Significance Gates

Gate Threshold Rationale
Smart Bidding minimum (Search) ≥ 30 conversions / 30 days Below this, tCPA/tROAS lacks signal
Smart Bidding minimum (PMax / Shopping) ≥ 50 conversions / 30 days Wider channel mix needs more signal
PMax maturity gate Age ≥ 30 days (ideally 60) OR conversions ≥ 50 Required before any PMax optimization
Segment-level recommendation ≥ 50 clicks AND ≥ 5 conversions Below this → flag as low-confidence
Scaling step cap ≤ 20% per move (search/shopping); ≤ 50% per move on mature PMax From guardrails / pmax-scaling
Lookback for Shopping 14 days if ≥ 100 purchases / month, else 30 days

PMax vs Search ROAS Comparison

Apply only after the PMax maturity gate passes.

PMax ROAS Ratio Assessment Default Action
< 0.5× Search ROAS Poor Monitor closely; consider pausing if not improving
0.5 – 0.9× Search ROAS Below par Optimize assets and negatives before any scaling
≥ 0.9× Search ROAS Healthy Optimize, scale eligible
> Search ROAS Outperforming Prioritize scaling

PMax Asset Performance Labels

Google returns performance_label per asset (NOT cost / conversion data per asset).

Label Interpretation Default Action
BEST Top performer in its asset group Create variations with similar style
GOOD Acceptable Keep, monitor
LOW Underperforming Remove; replace with BEST variations
PENDING / UNSPECIFIED Insufficient data Wait 14+ days

Shopping Item Classification (definitions only — workflow in google-ads-shopping skill)

Classification Trigger
KILL cost ≥ 2× AOV AND conversions = 0
DOWNGRADE ROAS < 0.7× target AND cost ≥ 0.5× AOV
PROMOTE conversions ≥ 2 AND ROAS ≥ target

Quality Score Components (when CPC is high)

Decompose Quality Score into:

  • Expected CTR
  • Ad relevance
  • Landing page experience

Identify which dragged and recommend fixes for that component — do NOT recommend bid changes alone to compensate for low QS.

Account-Purpose Classification (CRITICAL — must run before any KPI application)

Before computing or presenting CPA / ROAS / Conv. Value:

  1. Check chat title for keywords: "GMB", "footfall", "store visits", "calls", "directions", "awareness", "reach"
  2. Check campaign objectives loaded via google_ads_run_gaql:
    • , → footfall account
    • , → awareness account
    • , → conversion-tracking-capable
  3. Check conversion actions in the account: are they store visits, phone calls, directions — or actual purchases / leads?

If the account is footfall / awareness / local-service:

  • REPLACE CPA / ROAS in headline metrics with: Cost Per Footfall Action, Cost Per Call, Cost Per Direction, CPM, Reach, Frequency
  • State explicitly: "This account is configured for [footfall/awareness]; purchase-derived CPA/ROAS do not apply."