google-ads-insights git:20260716.bdcbb3dA

Immutable. This exact content never changes and is served at /api/v1/blob/3bbef99f92cccf57.

---
name: google-ads-insights
description: Use when the user asks AdsAgent Google Ads MCP questions about Google Ads accounts, MCC, customer IDs, Search, PMax, spend, conversions, CPA, ROAS, campaigns, ad groups, ads, keywords, assets, or multi-account Google performance summaries.
---

# Google Ads Insights Through AdsAgent

Use Google Ads fields and tools only.

## First Steps

1. Run `setup_get_status` before analysis.
2. Inspect `setup_get_status.capabilities.agent_method_profile` before choosing a query tool.
3. Discover accessible Google Ads accounts with `google_ads_accounts_list`.
4. Choose an `enabled`, `non-manager` account; never analyze an MCC as a spend account.
5. Verify named customer IDs, and report customer/date/grouping.

## Freshness Boundary

Google is a read-only ledger. Report `as_of` as observation time. It accepts only `consistency=cached`; it does not advertise require_fresh, mutation receipts, since-launch, product refresh, or live config verification. Shared tool names add no capability.

## Query Pattern

- When `agent_method_profile.profile_id=adsagent_agent_methods_v1`, call its advertised `consistent_query_tool` once with root `query_contract_version=1`, `consistency=cached`, and exactly one `scope` or one ordered `scopes` batch up to advertised `max_scopes`.
- Trust top-level `complete=true`, ordered result contracts, and server `summary/total`; missing scopes are unknown, never zero.
- Follow returned `next_action` only; poll its task tool with exact `task_ref` and `poll_after_ms`. Consume a completed bounded terminal `result` directly; never rerun page 1 or invent a refresh task.
- Without the profile, use `google_ads_insights_overview_query` for one scope and `google_ads_insights_overview_batch` for multiple scopes.
- Do not create client-side fan-out by customer or date.
- If the server returns `mcp_fanout_detected`, stop the loop and combine current plus pending scopes through profile `insights_query_consistent` when advertised, otherwise `google_ads_insights_overview_batch`.
- Never sum visible rows; distinguish rows shown from totals.

## Retry And Backoff

If Google Ads MCP returns `429` with `mcp_concurrency_limited`:

1. Honor `Retry-After + jitter`.
2. Retry serially within a small budget.
3. Prefer one profile `scopes` request or the native server-side batch tool instead of parallel calls.
4. Do not use token rotation or multiple sessions to bypass limits.

Parse backoff from the header, top-level `data`, or JSON-RPC `error.data`; never regex messages.

Treat `503` as dependency unavailable, not as a concurrency cap. Follow `/adsagent-reliability` for retry boundaries.

On `snapshot_expired`, restart at page 1 with the same customer, dates, grouping, filters, and order. Do not reuse the continuation, broaden scope, or fan out.

If Google Ads MCP returns `429` with `mcp_fanout_detected`, do not backoff-retry the same call. Switch to the profile batch shape or native batch overview tool.

## User-Facing Output

Return Markdown with a direct answer, customer/date/grouping, compact metrics table, `as_of`, completeness, and rows shown versus total. Do not dump raw JSON, diagnostics, schemas, or every field.

For explicit full-table/export requests, poll the returned task handle to terminal and return the artifact link instead of raw rows.