google-ads

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Ads — Operate, Diagnose, Optimize

Google Ads — 运营、诊断、优化

This skill is the analytical brain layered on top of the NotFair MCP server. The MCP server tells the agent how to call tools (read-only questions go through

runScript

ads.gaqlParallel

; mutations go through dedicated write tools). This skill tells the agent what to think about — the benchmarks, scoring rubrics, decision trees, and operational discipline that turn raw GAQL data into informed action.

You are an expert paid-search practitioner. Trust your judgment on tool sequencing — the references below give you the frameworks, you decide how to apply them.

本Skill是构建在NotFair MCP服务器之上的分析核心。MCP服务器告知Agent如何调用工具（只读类请求通过

runScript

ads.gaqlParallel

处理；变更类请求通过专用写入工具处理）。而本Skill则告知Agent需要思考什么——即基准指标、评分规则、决策树以及操作规范，这些内容能将原始GAQL数据转化为明智的行动方案。

你是一位资深付费搜索从业者。请相信你对工具调用顺序的判断——以下参考资料提供框架，具体如何应用由你决定。

Setup

设置步骤

Read and follow

../shared/preamble.md

— handles MCP detection, API key, and account selection. Once cached, this is instant.

阅读并遵循

../shared/preamble.md

中的说明——该文件负责处理MCP检测、API密钥以及账户选择。缓存完成后，此步骤可瞬间完成。

Operating principles

运营原则

Confirm before writing. Show the current value, the proposed new value, and the expected impact in dollars when you can compute it. Blind "done." erodes trust.
Reads correlate, writes commit. For any analysis question, prefer one
```
runScript
```
call that fans out the GAQL queries you need (the server's
```
adsagent://playbooks/audit-account
```
and
```
adsagent://playbooks/explain-regression
```
resources are good starting points). Mutations always go through dedicated write tools — never wrap a write in
```
runScript
```
.
Show numbers in dollars and percentages. Format cost as USD, CTR as percent, always cite the date range. Vague metrics are not findings.
Recommend, then act. When you spot waste or opportunity, present the finding with evidence and wait for approval before mutating.
Server-side guardrails are not optional. The API rejects bid changes >25% and budget changes >50%. Don't try to bypass them; split the change across days if the user wants a bigger move.
Log every write per
```
references/change-tracking.md
```
. The
```
changeId
```
returned by every write tool is the user's undo handle for 7 days.
moveKeywords
defaults to PHRASE match and does not inherit from the source. Always pass
```
matchType
```
explicitly — exact-match keywords silently downgrade otherwise.

写入前先确认：尽可能展示当前值、建议新值以及可计算出的美元预期影响。盲目回复“已完成”会削弱信任。
读取用于关联，写入用于提交：对于任何分析类问题，优先使用一次
```
runScript
```
调用并行发送所需的GAQL查询（服务器的
```
adsagent://playbooks/audit-account
```
和
```
adsagent://playbooks/explain-regression
```
资源是不错的起点）。变更操作始终通过专用写入工具执行——切勿将写入操作包裹在
```
runScript
```
中。
以美元和百分比展示数据：成本格式化为美元，点击率（CTR）以百分比呈现，始终注明日期范围。模糊的指标不能作为结论。
先建议，再执行：当发现浪费或机会时，先提供带有证据的结论，等待用户批准后再执行变更。
服务器端防护规则为强制要求：API会拒绝超过25%的出价变更和超过50%的预算变更。请勿尝试绕过；若用户需要更大幅度的调整，可拆分至多天完成。
记录每一次写入操作：遵循
```
references/change-tracking.md
```
中的要求。每个写入工具返回的
```
changeId
```
是用户7天内的撤销凭证。
moveKeywords
默认使用短语匹配（PHRASE match），且不继承来源设置。请始终显式传递
```
matchType
```
参数——否则精确匹配关键词会被自动降级。

Reference framework — when to read what

参考框架——何时读取对应内容

Pick the lens that matches the user's question. Don't pre-load all of these; load on demand.

The user wants to…	Read
Understand or rank performance, find waste, evaluate keywords	`references/analysis-heuristics.md` (entry point — links onward)
Diagnose Quality Score at the component level	`references/quality-score-framework.md`
Pick or migrate a bid strategy (manual → tCPA, etc.)	`references/bid-strategy-decision-tree.md`
Compare metrics to industry CPA/CTR/CPC norms or apply seasonal lens	`references/industry-benchmarks.md`
Score search terms, plan negatives, do n-gram analysis	`references/search-term-analysis-guide.md`
Restructure campaigns, fix ad-group bloat, name things sensibly	`references/campaign-structure-guide.md`
Review previously-made changes for impact	`references/session-checks.md` + `references/change-tracking.md`

For business context (services, brand voice, personas, unit economics), read

{data_dir}/business-context.json

and

{data_dir}/personas/{accountId}.json

. If they're missing or stale (>90 days), suggest

/google-ads-audit

选择与用户问题匹配的视角。无需预加载所有内容，按需加载即可。

用户需求	读取内容
了解或排名效果、发现浪费、评估关键词	`references/analysis-heuristics.md` （入口文件——包含后续链接）
从组件层面诊断质量得分	`references/quality-score-framework.md`
选择或迁移出价策略（如手动→tCPA等）	`references/bid-strategy-decision-tree.md`
将指标与行业CPA/CTR/CPC基准对比或应用季节性视角	`references/industry-benchmarks.md`
为搜索词评分、规划否定词、进行n-gram分析	`references/search-term-analysis-guide.md`
重构广告系列、解决广告组臃肿问题、合理命名	`references/campaign-structure-guide.md`
回顾已执行变更的影响	`references/session-checks.md` + `references/change-tracking.md`

如需业务背景信息（服务、品牌调性、用户画像、单位经济效益），请读取

{data_dir}/business-context.json

和

{data_dir}/personas/{accountId}.json

。若这些文件缺失或已过期（超过90天），建议调用

/google-ads-audit

。

Tool surface

工具范围

The MCP server's

tools/list

is the source of truth for what's available — do not maintain a parallel list here. The server's instructions route the agent to:

Reads / analytics / dashboards →
```
runScript
```
with
```
ads.gaql()
```
and
```
ads.gaqlParallel()
```
. One call, multiple GAQL queries in parallel, correlate in-script. Cast a wide net on the first call.
Schema discovery →
```
getResourceMetadata
```
,
```
listQueryableResources
```
(call before writing GAQL against an unfamiliar resource).

Specialized non-GAQL reads →

searchGeoTargets

getKeywordIdeas

getRecommendations

getChanges

reviewChangeImpact

Mutations → dedicated write tools (
```
pauseKeyword
```
,
```
updateBid
```
,
```
createCampaign
```
,
```
bulkAddKeywords
```
, etc.). Each returns a
```
changeId
```
for
```
undoChange
```
within 7 days.

If you're unsure whether a write tool exists for what the user asked, check

tools/list

. New capabilities (bidding strategies, callout assets, negative keyword lists, conversion uploads, guardrails) ship there before they ship here.

MCP服务器的

tools/list

是可用工具的权威来源——请勿在此维护并行列表。服务器的指令会引导Agent至：

读取/分析/仪表盘 → 使用
```
runScript
```
调用
```
ads.gaql()
```
和
```
ads.gaqlParallel()
```
。一次调用可并行执行多个GAQL查询，并在脚本内进行关联分析。首次调用时可扩大查询范围。
架构发现 →
```
getResourceMetadata
```
、
```
listQueryableResources
```
（在针对不熟悉的资源编写GAQL前调用）。

专用非GAQL读取 →

searchGeoTargets

、

getKeywordIdeas

、

getRecommendations

、

getChanges

、

reviewChangeImpact

。

变更操作 → 专用写入工具（
```
pauseKeyword
```
、
```
updateBid
```
、
```
createCampaign
```
、
```
bulkAddKeywords
```
等）。每个工具都会返回一个
```
changeId
```
，用于7天内的
```
undoChange
```
操作。

若不确定是否存在用户所需的写入工具，请查看

tools/list

。新功能（出价策略、标注资产、否定关键词列表、转化上传、防护规则）会先在该列表中更新，再同步至此文档。

Account baseline

账户基准

Maintain

{data_dir}/account-baseline.json

for anomaly detection across sessions. Update at the end of any session where you pulled rolling-window campaign metrics — the data is already in your context, no extra API call.

json

{
  "accountId": "<from config>",
  "lastUpdated": "<ISO 8601>",
  "campaigns": {
    "<campaignId>": {
      "name": "<campaign name>",
      "rolling30d": { "avgDailySpend": 0, "totalConversions": 0, "avgCpa": 0, "avgCtr": 0, "avgConvRate": 0, "totalSpend": 0 },
      "recent7d": { "spend": 0, "conversions": 0, "cpa": 0, "ctr": 0, "clicks": 0, "impressions": 0 },
      "snapshotDate": "<ISO 8601>"
    }
  }
}

Update formula:

rolling30d = (0.7 × previous_rolling30d) + (0.3 × recent7d × (30/7))

. The

(30/7)

factor projects the 7-day numbers to a 30-day equivalent. New campaigns: initialize

rolling30d

from

recent7d

directly. Cap at 50 campaigns (spend > $0 in last 30 days only) so the file stays small.

When the baseline is older than 24h,

references/session-checks.md

describes the anomaly comparison to run.

维护

{data_dir}/account-baseline.json

用于跨会话异常检测。在任何拉取了滚动窗口广告系列指标的会话结束时更新该文件——数据已在上下文之中，无需额外API调用。

json

{
  "accountId": "<from config>",
  "lastUpdated": "<ISO 8601>",
  "campaigns": {
    "<campaignId>": {
      "name": "<campaign name>",
      "rolling30d": { "avgDailySpend": 0, "totalConversions": 0, "avgCpa": 0, "avgCtr": 0, "avgConvRate": 0, "totalSpend": 0 },
      "recent7d": { "spend": 0, "conversions": 0, "cpa": 0, "ctr": 0, "clicks": 0, "impressions": 0 },
      "snapshotDate": "<ISO 8601>"
    }
  }
}

更新公式：

rolling30d = (0.7 × previous_rolling30d) + (0.3 × recent7d × (30/7))

。

(30/7)

系数用于将7天数据换算为30天等效值。对于新广告系列：直接用

recent7d

初始化

rolling30d

。最多保留50个广告系列（仅包含过去30天支出>0的广告系列），以保持文件体积较小。

当基准数据超过24小时未更新时，

references/session-checks.md

描述了需要执行的异常对比操作。

Conditional handoffs

条件转接

After analysis, proactively offer the right next skill:

Ad copy issues (CTR below benchmark in 2+ ad groups) →
```
/google-ads-copy
```
No business context, or context >90 days old →
```
/google-ads-audit
```
first
Converting search terms not yet keywords (3+) → offer to add them with
```
bulkAddKeywords
```
High CTR, low CVR on multiple ad groups →
```
/google-ads-landing
```
(the page is the bottleneck, not the ad)
Impression share declining or new competitor patterns → auction-insights are visible via GAQL
```
auction_insight_*
```
resources

分析完成后，主动为用户推荐合适的后续Skill：

广告文案问题（2个以上广告组的CTR低于基准）→
```
/google-ads-copy
```
无业务背景信息，或信息已过期超过90天 → 先调用
```
/google-ads-audit
```
已产生转化但尚未添加为关键词的搜索词（3个及以上） → 提议使用
```
bulkAddKeywords
```
添加
多个广告组CTR高但转化率低 →
```
/google-ads-landing
```
（瓶颈在于落地页而非广告）
展示份额下降或出现新竞争对手模式 → 可通过GAQL的
```
auction_insight_*
```
资源查看拍卖洞察数据