Google Ads

Google Ads

Hierarchy: Account → Campaign (+Budget) → Ad Group → Keywords/Ads. Resolve account_id before any account-scoped call.

Multi-account (MCC)

One OAuth login can reach many client accounts under manager accounts.

Resolve first: (1) User names a client → search by name or ID fragment. (2) Single match → use that account_id; do not re-list. (3) Multiple matches → show list, user picks — never guess. (4) User gives an ID → use it unless account-not-found. (5) Do not auto-pick when default scope is unset.

Browse vs resolve: name search when one client was named; paginated account list only for exploration. Refresh discovery after linked/removed clients or MCC routing changes. Missing-ID errors include suggested_accounts — narrow by name before browsing all.

Interactive browse + detail panels

Two MCP App surfaces mount alongside chat:

• Browse (ui://google-ads/browse) — open the Studio home (not a raw account listing), pick an account, then pulse, campaigns, and search terms. Campaign cards open detail in a local overlay with campaign performance for the chosen range.
• Detail (ui://google-ads/detail) — agent mount for one campaign's trend + device breakdown.

Studio open: use the open-app action that mounts Browse — not paginated account discovery. Home offers tool chips (load pulse, campaigns, browse accounts) and chat prompts.

When the panel is open, read tools with ui.resourceUri forward results to the iframe — do not re-call the same read only to refresh the UI. Call the read that owns the data (account summary for pulse, search-term report for search terms, etc.); the widget routes on panel_view. Account selection uses the chat-visible select-account action.

Start here after account resolve: account summary for the date range · then drill with campaigns, keywords, search terms, pacing, or geo as needed.

Workflows

Research: keyword ideas from seed keywords, a page URL, or an entire domain (site — competitor Keyword Planner mode: pass a competitor domain as site to pull their keyword themes) · volume, CPC, competition for exact terms (up to 10k keywords per volume call). Read: account summary · budget pacing · keywords · ads · ad policy/disapprovals · search terms · geo/device/schedule · change history · custom GAQL · web UI deep links (open overview, keywords, search terms in ads.google.com) · billing posture (setup + account budget + campaign daily guardrails) · account budget (credits, served, caps). Write: create campaign (default PAUSED) → ad group → keywords → upsert RSA ad (omit ad_id = create; ad_id + status = pause/unpause without recreate) → enable campaign; pause/enable one ad group; update budget/bids; add negatives (campaign, ad group, or shared negative lists); create/link shared sets; sitelinks/callouts/snippets at account or campaign level; upload image assets for Search image extensions; propose account spending cap (monthly-invoicing accounts only). Keyword status/bid changes: read keywords for the ad group first; update one criterion at a time; on concurrent_modification, re-read once — never bulk-retry the same update. Search terms → negatives: pull search terms for the date range → flag irrelevant queries → add negatives at campaign, ad group, or shared-list level with match type PHRASE (default) or EXACT for precision. Delete: campaign (cascades ad groups/ads, not budget) · ad group · keywords · orphaned budgets (reference_count=0 via GAQL).

Write safety

New campaigns default PAUSED. Read billing posture before enabling spend. Read keywords/ads before mutating — update tools skip no-op changes. One keyword update per call; do not loop-retry removed resources or concurrent_modification responses.

Reporting (GAQL)

Built-in reads cover most weekly PPC work. Use custom GAQL when you need segment splits the dedicated tools omit.

Performance Max network split:

Demand Gen placement split (pair ad_network_type with ad_sub_network_type):

Prefer the campaign network breakdown read for the same split without hand-written GAQL.

RSAs

3–15 headlines (≤30 chars), 2–4 descriptions (≤90). Good+ strength: 11+ headlines, 4 descriptions, zero pins, ad-group keywords in 2–3 headlines, diverse lines (features/benefits/CTAs, social proof). Minimize pinning — each pin reduces combinations Google can test.

Upsert (create + edit): one RSA upsert tool — omit ad_id to create; pass ad_id to update. Set status=ENABLED or PAUSED to unpause/pause without removing the ad (keeps policy approval). Change headlines/descriptions/final_url on update only when creative must change (may re-review). Do not remove+recreate just to enable a paused approved ad. On create, pass synthetic_content_attestation=YES|NO when headlines/descriptions include AI-generated copy.

Remove is permanent — use upsert status=PAUSED for temporary stops. After remove, create again via upsert without ad_id (or stale DESTINATION_NOT_WORKING: remove, then upsert create with ignore_destination_check=true).

Policy & disapprovals

Three independent signals — do not conflate:

• approval_status — APPROVED/DISAPPROVED; compliance gate; blocks serving.
• ad_strength — Poor→Excellent; recommendation only; weak CTR/CPC correlation; often PENDING for a few minutes after create before scoring.
• UI "Not eligible" — usually PAUSED campaign/ad group, not a disapproval.

For disapprovals use ad policy status (approval, review, policy topics, strength, final URLs, RSA text). The performance-oriented ads report omits policy fields. GAQL nested fields need format="json"; format="table" may break on policy_summary.

DESTINATION_NOT_WORKING when the URL is live = stale crawl timestamp:

1. List disapproved ads (filter DISAPPROVED).
2. Confirm each final URL returns 2xx (AdsBot user-agent or browser).
3. Remove ad → upsert create (same copy/URL) with ignore_destination_check=true.
4. Poll policy status — REVIEW_IN_PROGRESS / UNKNOWN → APPROVED typically within ~15 minutes; multi-hour stalls usually mean destination crawl issues, not normal queue time.

ignore_destination_check applies at create only; cannot patch or API-appeal existing ads (Policy Manager appeals are UI-only).

Reference

• Micros: 1,000,000 = $1. Reads auto-convert; bid writes use micros, budgets use currency.
• Match types: BROAD/PHRASE/EXACT for positives and negatives. Campaign-level negatives block all ad groups; ad-group negatives scope one slice; shared negative lists apply to every linked campaign.
• Extensions: create_asset supports link_level CUSTOMER (account) or CAMPAIGN. Image assets use the same pattern.
• Dates: search terms and change history do not support TODAY — use YESTERDAY+.
• MCC: query child accounts (manager: true), not the manager account; login_customer_id for sub-accounts under MCC.
• developer_token: platform-level, not per-user credential.
• Remove is permanent — PAUSE for temporary stops. Removing a campaign does not remove its budget.
• Spend guardrails: Read billing posture before promo tests. Automatic card/bank billing usually cannot set account caps via API — use campaign daily budgets, pauses, and budget pacing. Monthly invoicing accounts may propose finite account limits.