| name | google-ads-tool-fundamentals |
| description | Foundation tool reference for any Google Ads task — GAQL syntax, common entity relationships, default reporting windows. Used internally when working with Google Ads tools. |
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_update_entity: write tool for bid, budget, status, and structural mutations. Always require user approval per the operation flow.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_DAYSsegments.date DURING LAST_30_DAYSsegments.date DURING LAST_90_DAYSsegments.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 (search-analysis, pmax-evaluation, shopping, 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 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.
