Gads

---
name: gads
description: "Google Ads multi-agent toolkit. Audits, campaign-type analysis (Search, Performance Max, App, Display, Demand Gen, Shopping, YouTube), conversion-action checks and static Google tag detection, keyword research, auction insights, placement safety with built-in scam/bot/politics/religion/games/adult exclusions, and campaign planning. End-user Google SSO via gcloud, 24h session cap. Triggers on: google ads, adwords, search campaign, performance max, pmax, uac, app campaign, display campaign, shopping campaign, youtube ads, video campaign, auction insights, keyword research, conversion tracking, gtag, ga4 link."
user-invokable: true
argument-hint: "[command] [customer-id] [options]"
license: MIT
metadata:
  version: "0.1.0"
  category: google-ads
---

# Google Ads router skill

Top-level entry point. `/gads <command> <args>`.

## Commands

| Command | What it does |
|---------|-------------|
| `/gads auth` | Print the `gcloud auth application-default login` command, set developer token / login-customer-id |
| `/gads customers` | List accessible Google Ads customers |
| `/gads audit <customer-id>` | Collect configured read adapters in parallel |
| `/gads search <customer-id>` | Search campaigns |
| `/gads pmax <customer-id>` | Performance Max |
| `/gads uac <customer-id>` | App campaigns, ads and asset links |
| `/gads display <customer-id>` | Display campaigns and ads |
| `/gads demandgen <customer-id>` | Demand Gen campaigns, ads, assets and channel controls |
| `/gads shopping <customer-id>` | Shopping |
| `/gads youtube <customer-id>` | YouTube / Video campaigns, ads, formats and brand suitability |
| `/gads conversions <customer-id>` | Conversion tracking |
| `/gads gtag <customer-id> --site <url>` | Static tag detection and tracking IDs |
| `/gads keywords <customer-id> --seeds w1 w2` | Keyword ideas |
| `/gads competitors <customer-id>` | Campaign search impression share |
| `/gads placements <customer-id>` | Display + YouTube placement audit with safety exclusions |
| `/gads recommendations <customer-id>` | Google's account recommendations, triaged |
| `/gads anomalies <customer-id>` | Day-level metric anomaly detector |
| `/gads bidstrategy <customer-id>` | Per-campaign bid strategy fit |
| `/gads pacing <customer-id>` | Budget pacing, MTD vs target |
| `/gads assets <customer-id> rsa\|pmax-assets` | RSA strength and PMax asset inventory |
| `/gads brands <customer-id> suggest` | Brand lookup and reviewed PMax list exclusions |
| `/gads geos <customer-id> --query NAME [...]` | Resolve names to GeoTargetConstant IDs |
| `/gads quality <customer-id>` | Per-keyword Quality Score with deficient-component grouping |
| `/gads demographics <customer-id> age\|gender\|device\|location\|all` | Demographic and geographic outliers |
| `/gads creative <customer-id> <site-url>` | Draft creative briefs/prompts, upload supplied images and videos, attach, edit Video and Display ads |
| `/gads notify --setup\|--test\|--send TEXT` | Telegram bot setup and manual sends |
| `/gads history <customer-id>` | Change-event log; list and diff saved audits |
| `/gads apply <customer-id>` | Write paths: negative keywords, placement exclusions and Display optimized targeting |
| `/gads create <customer-id>` | Campaign planning and reviewed PAUSED Search, Demand Gen and App campaigns |
| `/gads audit --all-customers` | Audit directly accessible customers in parallel |

## Routing

| Input | Route to |
|-------|----------|
| `audit <id>` | gads-audit |
| `search <id>` | gads-search |
| `pmax <id>` | gads-pmax |
| `uac <id>` or `app <id>` | gads-uac |
| `display <id>` | gads-display |
| `demandgen <id>` or `demand-gen <id>` | gads-demandgen |
| `shopping <id>` | gads-shopping |
| `youtube <id>` or `video <id>` | gads-youtube |
| `conversions <id>` | gads-conversions |
| `gtag <id>` | gads-gtag |
| `keywords <id>` | gads-keywords |
| `competitors <id>` | gads-competitors |
| `placements <id>` | gads-placements |
| `recommendations <id>` | gads-recommendations |
| `anomalies <id>` | gads-anomalies |
| `bidstrategy <id>` | gads-bidstrategy |
| `pacing <id>` | gads-pacing |
| `assets <id> ...` | gads-assets |
| `brands <id> ...` | gads-brands |
| `geos <id> ...` | scripts/gads_geos.py |
| `quality <id>` | gads-quality |
| `demographics <id> ...` | gads-demographics |
| `creative <id> ...` | gads-creative |
| `notify ...` | scripts/gads_notify.py |
| `history <id>` | scripts/gads_history.py |
| `apply <id>` | scripts/gads_apply.py |
| `create <id>` | gads-creation |
| `auth` | Run `python scripts/gads_auth.py --adc` and friends |
| `customers` | Run `python scripts/gads_auth.py --customers` |

## Auth gate

Before any read/write, verify the session:

```
python scripts/gads_auth.py --check
```

If the session is older than 24h or the developer token is missing,
guide the user through:

1. `gcloud auth application-default login --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform,openid,email`
2. `python scripts/gads_auth.py --set-developer-token <TOKEN>`
3. Optionally `--set-login-customer-id <MCC>` for manager-account flows.

## Natural-language routing

- "How are my search campaigns doing?" → gads-search
- "Audit my Google Ads account" → gads-audit
- "Find scam placements" → gads-placements
- "I want to launch a new campaign" → gads-creation (it will collect
  context before proposing anything)
- "Why am I losing impression share?" → gads-search and gads-competitors
- "Is my conversion tracking right?" → gads-conversions + gads-gtag

## Defaults

- Lookback: 28 days
- Output: markdown (no emoji)
- Mutate: always `PAUSED` first, never auto-unpause

New profiles do not require developer tokens. API access is approved for the
Cloud project owning the OAuth client. Use docs/SETUP.md; preserve session checks.

## Read failures

Read CLI failures return exit code 3 with a redacted JSON error. Explain
`authentication_required`, `permission_denied`, `not_found` or
`temporarily_unavailable`; never interpret a failed report as zero spend or
healthy tracking. Python calls still raise, and audits keep per-agent failed
blocks. See docs/REPORTING.md. Do not retry writes based on a retryability hint.

For an occasional read missing from a dedicated adapter, use
`python scripts/gads_export.py --customer <id> --query-file report.gaql
--limit 1000 --format json --output report.json` on one line. Review the GAQL
against the selected API reference first. This command preserves the session
gate, accepts only reads and reports truncation; see docs/REPORTING.md.

For offline safety task fixtures and the transcript rubric, see docs/EVALUATION.md.
Passing adapter tests does not establish that a language-model runtime follows the rubric.

For read-only handoff to external tools, follow docs/INTEROPERABILITY.md.
An independent MCP server does not inherit this toolkit's session gate.