Google Ads

List the Google Ads accounts this login can reach. Call this FIRST when the user has not named an account. Every other tool needs a customer_id, and guessing one produces an authorization error rather than a useful message. Returns customer ids as plain digit strings. Note that a manager (MCC) account appears here too, and querying one returns the manager's own records — not the combined totals of the accounts beneath it.

Which fields exist on a Google Ads resource, and which can be selected, filtered, or sorted — plus the metrics and segments valid alongside it. You MUST call this before composing a query with ads_search unless you already know the exact field names. Do not guess them. Google Ads rejects unknown or partial field names with an opaque error, and there are thousands of fields. Args: - customer_id (string): any account you can access (field metadata is global, but the API requires an authenticated context) - resource (string): e.g. 'campaign', 'ad_group', 'ad_group_ad', 'keyword_view' Returns: selectable / filterable / sortable field lists, plus metrics[] and segments[]. Field names are fully qualified ('campaign.id', not 'id'). Responses change rarely — cache them for the conversation rather than calling repeatedly.

Query Google Ads reporting data: any fields x conditions over any resource. Read-only. Args: - customer_id (string): the account to query - resource (string): FROM clause, e.g. 'campaign' - fields (string[]): SELECT clause, fully qualified, e.g. ['campaign.id','campaign.name','metrics.impressions','metrics.clicks'] - conditions (string[]): WHERE clauses, combined with AND, e.g. ["segments.date BETWEEN '2026-08-01' AND '2026-08-27'"] - orderings (string[]): ORDER BY, e.g. ['metrics.clicks DESC'] - limit (number): max rows DATES ARE NOT OPTIONAL FOR METRICS. A query selecting metrics without a date condition returns lifetime totals, which is almost never the question asked and looks indistinguishable from a period figure. Always constrain with segments.date unless the user explicitly wants all-time. Dates are YYYY-MM-DD with dashes, and ranges must be finite (both ends given). Field names must be fully qualified — 'campaign.id', never 'id'. Wildcards are not supported. Call ads_get_resource_metadata first rather than guessing. Returns: rows, rowCount, the exact GAQL executed, and a _meta block naming the account, query and fetch time. The query string is returned so you can verify the filter you intended was actually applied — if it is missing from the WHERE clause, do not report the numbers as filtered. Cost and conversion figures come back in Google's raw units: money is in micros (1,000,000 micros = one unit of the account currency). Divide before reporting. RATES ARE FRACTIONS HERE, PERCENTAGES IN THE JOB TOOLS. metrics.ctr and the impression-share metrics come back from Google as fractions (0.0792 = 7.92%), whereas every job tool returns ctr already multiplied out to 0-100. The same field name means two different things depending on which tool produced it, and they are 100x apart — never compare a ctr from here against one from ads_performance_report or ads_breakdown without converting first. PREFER A JOB TOOL WHEN ONE FITS — they resolve dates in the account time zone, divide micros, compute deltas, and carry the caveats that make a number safe to report. Reach for ads_search when none of them covers the question: - ads_conversion_actions — what a "conversion" means here (run this first) - ads_account_pulse — did anything break overnight - ads_budget_pacing — MTD spend vs budget, projected month-end - ads_performance_report — campaign/ad-group performance, with comparisons - ads_search_terms — which queries triggered ads (SEARCH TERMS, not keywords) - ads_breakdown — device / geo / hour / day / age / gender splits - ads_creative_performance — ad strength, policy status, asset labels - ads_change_history — who changed what, when (30-day window) - ads_account_config — auto-tagging, auto-apply, conversion-tracking setup - ads_recommendations — open recommendations and whether their premise holds NO JOB TOOL COVERS KEYWORDS. Keyword-level performance, Quality Score, and first-page bid estimates all live on keyword_view and require this tool — ads_search_terms returns SEARCH TERMS (what people typed), which is a different object from the keywords you bid on. A user asking "which keywords are wasting money" usually means their bid-on keywords: query keyword_view here, or say which one you are reporting. Quality Score is ad_group_criterion.quality_info.quality_score. Cross-tabs also need this tool: ads_breakdown splits by exactly ONE dimension, so device-by-geo or geo-by-hour must be composed here with two segments.* fields. Auction insights (competitor impression share / overlap rate) is NOT available through the Google Ads API at all — no query composes it. It exists only in the Ads UI. Say so rather than constructing something that looks equivalent. Large results drop whole rows from the end and report rows_omitted; the JSON always stays parseable. output_style: "compact" returns {columns, rows} arrays instead of repeating every field name on every row — materially smaller for wide results, same data. This tool cannot modify anything. Only SELECT queries are constructible.

What a "conversion" actually means in this account — the measurement-integrity audit. Run this before REPORTING any CPA or ROAS figure from any other tool — not necessarily as the literal first call, but before you put a cost-per-conversion in front of a human. Lists every non-removed conversion action: status, type, category, whether it is primary for its goal, whether it feeds the conversions metric, counting type, attribution model, click-through lookback window, and — for GA4 imports — the imported event (ga4.event_name, ga4.property_id, ga4.property_name). How to audit: - counted_in_conversions is the list of actions currently included in the conversions metric — the same list every reporting tool cites in _meta.conversions_counted_by. It defines what "a conversion" means here. - Compare each counted action's display name against ga4.event_name. Display names can be edited freely; the imported event cannot. A mismatch means every CPA/ROAS in the account measures something other than what the name claims. - Flag any counted action that measures a click or engagement (e.g. a CTA click) rather than an outcome: clicks counted as conversions inflate every downstream conversion metric. Surface this to the user; do not silently accept it. Args: - customer_id (string) Returns: counted_in_conversions (names) and actions[], counted actions first. For questions this report doesn't answer, use ads_search.

Daily account triage in one call: did anything break overnight, and did spend move? Args: - customer_id (string) - date (string, optional, YYYY-MM-DD): evaluate as of this date in the ACCOUNT's time zone; defaults to today. Pass a past date to reproduce a historical pulse. Evaluates yesterday (relative to date) against the trailing 7-day baseline (the 7 days before yesterday). Returns: - spend_yesterday, spend_daily_baseline_7d, spend_change_pct - flags.disapproved_ads: enabled ads with approval_status != APPROVED, with their policy topics - flags.campaigns_went_dark: impressions in the baseline, zero yesterday — it broke overnight - flags.campaigns_not_serving: zero impressions in the baseline AND yesterday — never serving or long-dead, a different failure with a different fix - flags.campaign_spend_outliers: spend moved beyond the thresholds echoed in flag_thresholds vs the campaign's own baseline average Empty flags lists mean nothing was flagged — every check always runs. Each list caps at 25 entries; flags_omitted reports anything cut. Money is in account currency (_meta.currency), already divided from micros. _meta.conversion_lag warns when recent conversions are still maturing. For questions this report doesn't answer, use ads_search. Conventions (shared by all job tools): - Money is in account currency (_meta.currency), ALREADY divided from micros. Only ads_search returns raw micros. - ctr is a PERCENTAGE (0-100), not a fraction. ads_search returns Google's raw fraction instead — they are 100x apart. - A ratio whose denominator is zero is null, NEVER 0: no conversions means cpa: null, not a CPA of zero. Treat null as "undefined", not "none". - period_is_partial: true means the period includes today. Do NOT project, annualize, or compare it against a complete period — a partial day is not a small day. - rows_omitted counts whole rows dropped to fit the response limit. Nonzero means you are reading a prefix of the sorted result, not the whole set. - _meta.conversions_counted_by names the conversion actions that define what "a conversion" means in every number here (see ads_conversion_actions).

Month-to-date spend vs budget with a projected month-end, grouped by BUDGET — shared budgets are common in agency accounts, and per-campaign pacing double-counts them. Args: - customer_id (string) - date (string, optional, YYYY-MM-DD): evaluate as of this date (account time zone); defaults to today. There is deliberately no period argument — pacing is intrinsically "this calendar month to date". The MONTH is taken from this date, so pass a date inside the month you mean: '2026-09-30' reports September, whether or not September has happened. A future date is not rejected; it simply reports a month with little or no spend in it, and projected_month_end will be null. Per budget: daily_budget, spend_mtd, days_with_spend, projected_month_end, monthly_capacity (daily budget x days in month — Google's own monthly cap; single days may spend up to 2x daily), pacing_pct (projected / capacity), the attached campaigns, and yesterday's search_impression_share / budget_lost_impression_share / rank_lost_impression_share. How the projection works (also stated in the payload's basis field): spend_mtd covers COMPLETED days only; today's partial spend is spend_today_partial and never enters a projection. The projection runs off days_with_spend — days this month with nonzero cost — so a campaign launched mid-month projects from its actual run-rate instead of reporting a massive false underspend. It assumes the recent run-rate continues; it is null when no completed day has spend yet. Reading the impression-share trio: high budget_lost with pacing under 100% is the budget-limited/reallocation signal. High rank_lost is a bid or quality problem that no budget move fixes. Null shares mean not eligible (non-search campaigns or no data yesterday). For questions this report doesn't answer, use ads_search. Conventions (shared by all job tools): - Money is in account currency (_meta.currency), ALREADY divided from micros. Only ads_search returns raw micros. - ctr is a PERCENTAGE (0-100), not a fraction. ads_search returns Google's raw fraction instead — they are 100x apart. - A ratio whose denominator is zero is null, NEVER 0: no conversions means cpa: null, not a CPA of zero. Treat null as "undefined", not "none". - period_is_partial: true means the period includes today. Do NOT project, annualize, or compare it against a complete period — a partial day is not a small day. - rows_omitted counts whole rows dropped to fit the response limit. Nonzero means you are reading a prefix of the sorted result, not the whole set. - _meta.conversions_counted_by names the conversion actions that define what "a conversion" means in every number here (see ads_conversion_actions).

Campaign or ad-group performance over a period, optionally compared to another period — the daily-check, weekly-movers, and monthly-report tool. Args: - customer_id (string) - level: "campaign" (default) or "ad_group" - period: a preset (TODAY, YESTERDAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH — resolved in the ACCOUNT's time zone; LAST_N presets end yesterday) or explicit {start, end} (YYYY-MM-DD) - compare_to (optional): PREVIOUS_PERIOD (the adjacent same-length window; for THIS_MONTH/LAST_MONTH, the same day-span of the previous month), SAME_PERIOD_LAST_YEAR, or explicit {start, end}. The resolved window is echoed back as compared_to. - campaign_ids (optional): restrict to these campaigns - include_paused (default false). REMOVED entities are never included. - order_by: cost (default) | conversions | clicks | impressions - limit (default 100, max 500) Fixed metric set per row: impressions, clicks, cost, conversions, conversions_value, plus computed ctr (a PERCENTAGE, 0-100), avg_cpc, cpa, roas. Ratios are null when their denominator is zero — no conversions means cpa: null, never 0. With compare_to, every metric gains _prev and _change_pct fields; an entity present in only one window gets null on the missing side plus only_in: "current"|"previous" — a launch or a pause is not a 100% move. totals is computed over ALL matching rows before the limit cut, so the roll-up stays correct when rows_omitted > 0. period_is_partial: true means the period includes today — do not compute run-rates from it without noticing. _meta.conversions_counted_by names what "a conversion" is here (see ads_conversion_actions); _meta.conversion_lag warns when the window is still inside the conversion lookback — conversion deltas are then biased low. Money is in account currency, already divided from micros. For custom metrics, other entity levels, or segment slicing, use ads_search. Conventions (shared by all job tools): - Money is in account currency (_meta.currency), ALREADY divided from micros. Only ads_search returns raw micros. - ctr is a PERCENTAGE (0-100), not a fraction. ads_search returns Google's raw fraction instead — they are 100x apart. - A ratio whose denominator is zero is null, NEVER 0: no conversions means cpa: null, not a CPA of zero. Treat null as "undefined", not "none". - period_is_partial: true means the period includes today. Do NOT project, annualize, or compare it against a complete period — a partial day is not a small day. - rows_omitted counts whole rows dropped to fit the response limit. Nonzero means you are reading a prefix of the sorted result, not the whole set. - _meta.conversions_counted_by names the conversion actions that define what "a conversion" means in every number here (see ads_conversion_actions).

Search-terms mining: which real queries triggered ads, what they cost, and what converted — the negative-keyword hunting tool. SEARCH TERMS ARE NOT KEYWORDS. These are the queries people actually typed, not the keywords you bid on. If the user asks about "keywords" they usually mean their bid-on keywords, which live on keyword_view via ads_search — either query that instead, or say plainly which of the two you are reporting. Args: - customer_id (string) - period: same shape as ads_performance_report - campaign_ids (optional) - min_cost (default 0): only terms with at least this cost, in ACCOUNT CURRENCY (not micros — conversion happens server-side) - zero_conversions_only (default false): only terms with zero conversions — the classic wasted-spend query - order_by: cost (default) | clicks | impressions | conversions - limit (default 100, max 500) Per row: search_term, status, match_type, campaign, ad_group, impressions, clicks, cost, conversions, conversions_value, cpa. status meanings: NONE = no keyword action taken on this term; ADDED = it is already a keyword; EXCLUDED = a negative keyword now covers it. Caveats: - Google withholds low-volume search terms for privacy. Term-level cost sums to LESS than campaign-level cost for the same period; the gap (explained in the payload's unattributed note) is real spend on terms you cannot see, not a data error. Do not reconcile the two and report a discrepancy. - status EXCLUDED means a negative covers the term NOW. The negative may have been added mid-period, so in-period spend on an EXCLUDED term can be legitimate — date the exclusion (change history) before calling it waste. For questions this report doesn't answer, use ads_search. Conventions (shared by all job tools): - Money is in account currency (_meta.currency), ALREADY divided from micros. Only ads_search returns raw micros. - ctr is a PERCENTAGE (0-100), not a fraction. ads_search returns Google's raw fraction instead — they are 100x apart. - A ratio whose denominator is zero is null, NEVER 0: no conversions means cpa: null, not a CPA of zero. Treat null as "undefined", not "none". - period_is_partial: true means the period includes today. Do NOT project, annualize, or compare it against a complete period — a partial day is not a small day. - rows_omitted counts whole rows dropped to fit the response limit. Nonzero means you are reading a prefix of the sorted result, not the whole set. - _meta.conversions_counted_by names the conversion actions that define what "a conversion" means in every number here (see ads_conversion_actions).

Performance split by ONE dimension — device, geo, hour of day, day of week, age, or gender. The "who and where is this working for" tool. Args: - customer_id (string) - dimension: device | geo | hour | day_of_week | age | gender - period: preset (TODAY, YESTERDAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH — account time zone; LAST_N presets end yesterday) or explicit {start, end} - compare_to (optional): PREVIOUS_PERIOD, SAME_PERIOD_LAST_YEAR, or {start, end} - campaign_ids (optional) There is no limit argument: every dimension is naturally bounded (device 4, hour 24, day_of_week 7, age 7, gender 3). geo is the exception, capped at the top 50 locations by cost with rows_omitted reporting the rest. DIMENSIONS CANNOT BE COMBINED. One call splits by exactly one dimension, so "mobile users in California" or "geo by hour" is not answerable here — two calls give you mobile-everywhere and California-all-devices, which is not a cross-tab. Compose those in ads_search with two segments.* fields. With compare_to, the resolved comparison window is echoed back as compared_to, so you can verify what was actually compared rather than trusting the preset. Each row carries the fixed metric set (impressions, clicks, cost, conversions, conversions_value, ctr as a PERCENTAGE, avg_cpc, cpa, roas) plus share_of_cost_pct. With compare_to, every metric gains _prev and _change_pct. Caveats that change the reading: - age and gender include an UNKNOWN bucket that is frequently the MAJORITY of traffic — Google only reports demographics it can infer. It is returned like any other bucket. A percentage computed while ignoring UNKNOWN describes a minority of the traffic. - hour is 0-23 in the ACCOUNT's time zone (_meta.time_zone). Smart Bidding ignores ad-schedule bid adjustments, so an hour finding usually justifies scheduling on/off rather than bid modifiers. - geo criterion ids are resolved to location names; the raw criterion_id is kept alongside so it can be fed back into ads_search. For other dimensions or custom metrics, use ads_search. Conventions (shared by all job tools): - Money is in account currency (_meta.currency), ALREADY divided from micros. Only ads_search returns raw micros. - ctr is a PERCENTAGE (0-100), not a fraction. ads_search returns Google's raw fraction instead — they are 100x apart. - A ratio whose denominator is zero is null, NEVER 0: no conversions means cpa: null, not a CPA of zero. Treat null as "undefined", not "none". - period_is_partial: true means the period includes today. Do NOT project, annualize, or compare it against a complete period — a partial day is not a small day. - rows_omitted counts whole rows dropped to fit the response limit. Nonzero means you are reading a prefix of the sorted result, not the whole set. - _meta.conversions_counted_by names the conversion actions that define what "a conversion" means in every number here (see ads_conversion_actions).

Which ads and which individual assets are working — the "what should we rewrite" tool. Args: - customer_id (string) - period: same shape as ads_performance_report - level: "ad" (default) or "asset" - campaign_ids (optional) - include_paused (default false). REMOVED entities are never included. - order_by: cost (default) | impressions | conversions [level=ad only] - limit (default 50, max 300) level "ad" returns per ad: ad_id, ad_type, status, ad_strength (EXCELLENT/GOOD/AVERAGE/POOR), policy_approval and policy_topics, final_urls, campaign, ad_group, and the fixed metric set with computed ctr/avg_cpc/cpa/roas. level "asset" returns individual headlines and descriptions from responsive search ads: text, field_type (HEADLINE/DESCRIPTION), performance_label, policy_approval, impressions and clicks. Sorted LOW first — that is the "replace this copy" signal this level exists for. Caveats: - performance_label LEARNING or PENDING means Google has not collected enough data yet. It is NOT a poor result, and removing a LEARNING asset restarts the learning it was accumulating. Never recommend removing one. - Performance Max campaigns do not expose per-asset metrics through the API. PMax campaigns in the account are listed in pmax_campaigns rather than being silently absent from the rows. - ad_strength is Google's own heuristic about asset diversity, not a performance measurement. A POOR ad that converts is not a problem to fix. For questions this report doesn't answer, use ads_search. Conventions (shared by all job tools): - Money is in account currency (_meta.currency), ALREADY divided from micros. Only ads_search returns raw micros. - ctr is a PERCENTAGE (0-100), not a fraction. ads_search returns Google's raw fraction instead — they are 100x apart. - A ratio whose denominator is zero is null, NEVER 0: no conversions means cpa: null, not a CPA of zero. Treat null as "undefined", not "none". - period_is_partial: true means the period includes today. Do NOT project, annualize, or compare it against a complete period — a partial day is not a small day. - rows_omitted counts whole rows dropped to fit the response limit. Nonzero means you are reading a prefix of the sorted result, not the whole set. - _meta.conversions_counted_by names the conversion actions that define what "a conversion" means in every number here (see ads_conversion_actions).

Who changed what, and when — the "why did the numbers move" tool. Run this before attributing a performance change to the market. Args: - customer_id (string) - period: same shape as elsewhere, BUT cannot reach back more than 30 days (Google's retention limit, validated here with an explanatory error rather than relayed as an opaque 400) - campaign_ids (optional) - user_email (optional): only changes by this user - resource_types (optional): e.g. ['CAMPAIGN','CAMPAIGN_BUDGET','AD_GROUP', 'AD_GROUP_AD','AD_GROUP_CRITERION','AD','ASSET','CAMPAIGN_CRITERION','FEED']. An invalid value is rejected by Google with BAD_ENUM_CONSTANT, not ignored. - limit (default 100, max 500) Per row: at (timestamp), user_email, client_type (distinguishes a UI edit from an API call, Google Ads Editor, or an automated rule — note this is a RETURNED field, not a filter: to find automated changes, pull the rows and read it), operation (CREATE/UPDATE/REMOVE), resource_type, resource, changed_fields, and scalar_changes giving old→new for primitive fields. IMPORTANT LIMIT — conversion actions are NOT covered. There is no CONVERSION_ACTION resource type in change_event (filtering on one is rejected outright), so a conversion action being renamed, flipped between primary and secondary, or added to / removed from the conversions metric leaves NO trace here. That is the highest-value measurement change an account can undergo, and this tool cannot date it. Use ads_conversion_actions for the CURRENT state, and the Google Ads UI change history to find out when it changed. Do not conclude from an empty result that the conversion setup was untouched. Caveat: not every entity type emits change events, and retention is 30 days. Absence of an event is therefore weaker evidence than presence — it does not prove nothing changed. For questions this report doesn't answer, use ads_search.

The account settings that decide whether any of the numbers mean anything: auto-tagging, auto-apply, and conversion-tracking ownership. Part of the measurement-integrity gate alongside ads_conversion_actions. Args: - customer_id (string) Returns three blocks: - account: id, name, status, currency, time_zone, is_manager, is_test_account - attribution: auto_tagging_enabled, conversion_tracking_id, conversion_tracking_status, cross_account_conversion_tracking - auto_apply: enabled (boolean), subscriptions[], and a note What to do with each: - auto_tagging_enabled FALSE is a finding, not a detail. Without auto-tagging the gclid never reaches the landing page, so clicks cannot be joined to analytics sessions and attribution degrades silently — it looks like a tracking bug on the site, not an account setting. A manual tracking template can substitute, and this tool cannot see tracking templates, so treat FALSE as "investigate", not "definitely broken". - auto_apply.enabled TRUE means Google can change this account with nobody approving it — bids, budgets, keywords. Check what is subscribed before trusting any trend, because an auto-applied change alters the very numbers you are reading. The empty case is stated in words: zero subscriptions is a real "off", not a failed lookup. - cross_account_conversion_tracking TRUE means conversions are owned by a manager account, so this account's conversion_action list is not the whole story. For questions this report doesn't answer, use ads_search.

Google's open recommendations for this account, with the uplift it is actually projecting for each — the "should we take this advice" tool. Args: - customer_id (string) - include_dismissed (default false) - campaign_ids (optional) - limit (default 100, max 200) Per row: type, dismissed, campaign, expands_reach, and impact with three blocks — base (current), potential (Google's projection), and delta (potential minus base, computed here). READ THE DELTA, NOT THE TWO BLOCKS. Google routinely returns potential_metrics IDENTICAL to base_metrics — a recommendation surfaced with a projected uplift of exactly zero. Presented side by side those two blocks invite an assumption of gain that the payload itself denies. Types that came back with no projection at all are listed in no_impact_estimate; that absence is information (Google is not forecasting a gain), not a data error. expands_reach flags recommendations that increase WHERE ads run — opt-ins, budget raises, broad match. Before accepting one, check ads_budget_pacing: if budget_lost_impression_share is already high, the account is budget-limited and more inventory solves a problem it does not have. Verify each recommendation's stated premise against the account's real constraint rather than its score. Optimization score is deliberately NOT returned here. It measures agreement with Google, not performance: it moves when new recommendations appear, and it can rise from merely adding a conversion action. Never report it as a performance metric. It is available via ads_search on customer.optimization_score for anyone who genuinely wants it. This tool reports recommendations. It cannot apply or dismiss one — that is a write, and this server is read-only. For questions this report doesn't answer, use ads_search.