google-ads-tool-fundamentals

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_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 (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.