google-ads-api-account-diagnostics
Diagnoses Google Ads account performance issues such as conversion loss (value or volume), low lead flow/volume, and lost impression share (opportunities) due to ad rank, bids, or budgets. Use when troubleshooting sudden performance drops, analyzing campaign impression share metrics, investigating low lead flow, or searching for bidding and budget constraints. Don't use for setting up new campaigns, uploading conversion events directly, or general Google Mobile Ads SDK integration issues (use gma-android-integrate instead).
google · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add google/skills --skill google-ads-api-account-diagnostics技能说明
name: google-ads-api-account-diagnostics description: >- Diagnoses Google Ads account performance issues such as conversion loss (value or volume), low lead flow/volume, and lost impression share (opportunities) due to ad rank, bids, or budgets. Use when troubleshooting sudden performance drops, analyzing campaign impression share metrics, investigating low lead flow, or searching for bidding and budget constraints. Don't use for setting up new campaigns, uploading conversion events directly, or general Google Mobile Ads SDK integration issues (use gma-android-integrate instead). metadata: category: GoogleAds author: google-ads-api-team version: "1.0"
Google Ads API Account Performance Diagnostics Skill
This skill provides instructions on how to use the Google Ads MCP server tools to diagnose common account performance issues.
Workflows
Identifying Active Client Accounts
Most diagnostics tasks require sending GAQL queries to a specific customer account. If the customer ID is not explicitly provided by the user, you must first call the list_accessible_customers (or customers_list_accessible_customers) tool to retrieve the customer resource names/IDs you have access to.
Once you have the list of accessible customer IDs, query the customer_client resource using the search tool under those customer accounts to find active client customer accounts. Make sure to select only enabled client accounts and filter out manager accounts:
SELECT
customer_client.id,
customer_client.descriptive_name,
customer_client.status,
customer_client.manager
FROM customer_client
WHERE customer_client.status = 'ENABLED' AND customer_client.manager = FALSE
Only run subsequent diagnostic queries against the enabled client customer IDs retrieved from this list. Do not query deactivated or manager accounts, as doing so will cause API errors.
Using the MCP Tools Directly
To retrieve information and run queries, you must call the search tool on the MCP server directly (with arguments like customer_id, fields, resource, and conditions). Do not write or execute custom Python scripts or use the Google Ads client library to query the API, as they will fail authentication inside the evaluation sandbox.
1. Conversion and Conversion Value Loss
When conversions or conversion value suddenly decline, use the following steps to diagnose the issue.
Steps:
-
Discover Fields: Use
get_resource_metadatawith resourcecampaignorad_groupto ensure you have the correct field names. -
Query Performance: Use
searchto retrieve performance data.- Resource:
campaignorad_group - Fields: Include
campaign.name,metrics.conversions,metrics.conversions_value,metrics.cost_micros. - Segments: To isolate the loss, include segments like
segments.date,segments.device,segments.conversion_action. - Conditions: Compare the period of decline with a previous period (e.g.,
segments.date >= '{start_date}'). - Gotcha:
metrics.cost_microsmust be divided by 1,000,000 to get standard currency amounts.
Example GAQL Query: To query performance data for a customer account
{customer_id}between{start_date}and{end_date}:SELECT campaign.name, metrics.conversions, metrics.conversions_value, metrics.cost_micros, segments.date, segments.device, segments.conversion_action FROM campaign WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}' - Resource:
-
Analyze: Check if the loss is limited to certain devices (e.g., mobile vs desktop) or specific conversion actions.
-
Check Uploads: If using offline imports, query
offline_conversion_upload_conversion_action_summaryto verify upload pipeline health. If the query returns no results, report that no offline uploads exist for the account and proceed.Example GAQL Query: To check upload pipeline health for a customer account
{customer_id}:SELECT offline_conversion_upload_conversion_action_summary.conversion_action_name, offline_conversion_upload_conversion_action_summary.successful_event_count, offline_conversion_upload_conversion_action_summary.total_event_count, offline_conversion_upload_conversion_action_summary.status FROM offline_conversion_upload_conversion_action_summary
2. Opportunities Lost (Impression Share)
To identify lost opportunities due to ad rank, bids, or budgets, analyze impression share metrics.
Steps:
-
Query Impression Share: Use
searchto retrieve impression share metrics.- Resource:
campaign - Fields: Include
campaign.name,metrics.search_impression_share,metrics.search_rank_lost_impression_share,metrics.search_budget_lost_impression_share. - Gotcha: Impression share values in the API are returned as decimals (e.g., 0.35 = 35%) or formatted strings (e.g.,
"< 0.10").
Example GAQL Query: To query impression share metrics for a customer account
{customer_id}between{start_date}and{end_date}:SELECT campaign.name, metrics.search_impression_share, metrics.search_rank_lost_impression_share, metrics.search_budget_lost_impression_share FROM campaign WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}' - Resource:
-
Analyze:
- High
search_budget_lost_impression_shareindicates opportunities lost due to limited budget. - High
search_rank_lost_impression_shareindicates opportunities lost due to low ad rank (bid or quality issues).
- High
3. Low Lead Flow Diagnostics
When a user asks "why is my lead flow low these past few days?", follow this systematic approach.
Steps:
- Confirm Drop: Query conversions segmented by date for the last few days vs the previous period.
- **Isolate Cau