google-ads-api-account-diagnostics

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

### Pre-Flight Tool Verification
Before starting any diagnostic task, verify whether the Google Ads MCP Server tools (`search`, `list_accessible_customers`, `get_resource_metadata` — these may be exposed with a server prefix, e.g. `customers_list_accessible_customers`) are available in the runtime environment:
- **If MCP tools are available**: Proceed with live diagnostics — first [identify active client accounts](#identifying-active-client-accounts), then run GAQL via the `search` tool (arguments `customer_id` and `query`).
- **If MCP tools are missing**: Follow [Fallback When MCP Tools Are Unavailable](#fallback-when-mcp-tools-are-unavailable).

### 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:
```sql
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.

### Fallback When MCP Tools Are Unavailable
When Google Ads MCP tools (`search`, `list_accessible_customers`, `get_resource_metadata` — these may be exposed with a server prefix, e.g. `customers_list_accessible_customers`) are not registered in the runtime environment:
1. **Inform the User**: State that live account performance diagnostics require the Google Ads MCP Server.
2. **Reference Setup Guide**: Direct the user to the setup instructions in the [google-ads-api-mcp-setup](../google-ads-api-mcp-setup/SKILL.md) skill to install and configure the Google Ads MCP Server for their assistant environment.
3. **Provide GAQL Templates, Gotchas, and Remediation Guidance**: Formulate and output the complete diagnostic plan for manual execution in the Google Ads Query Builder or via API integration:
   - Provide all multi-step GAQL queries for the workflow, including current-vs-prior date window comparisons (e.g. traffic, impression share, conversion breakdowns, or change events).
   - Explain all metric conversion and constraint gotchas (`metrics.cost_micros / 1,000,000` for currency, impression share reported as decimals or `"< 0.10"`, `change_event` 30-day window and `LIMIT 10000` without `metrics.*`, and `successful_event_count / total_event_count` plus `status` for upload health).
   - Outline concrete **actionable next steps** for each diagnostic branch (e.g., raising campaign budgets when `search_budget_lost_impression_share` is high vs. improving ad quality or bids when `search_rank_lost_impression_share` is high).
4. **Do Not Attempt Unauthorized Local Probing**: Do **not** attempt to run shell commands, custom Python scripts, local SQL/database queries, or direct RPC CLI utilities to access account data. These commands lack credentials and API access and will fail.

### 1. Conversion and Conversion Value Loss

When conversions or conversion value suddenly decline, use the following steps to diagnose the issue.

**Steps:**
1.  **Discover Fields**: Use `get_resource_metadata` with resource `campaign` or `ad_group` to ensure you have the correct field names.
2.  **Query Performance**: Use `search` to retrieve performance data.
    *   **Resource**: `campaign` or `ad_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_micros` must be divided by 1,000,000 to get standard currency amounts.
    *   *Gotcha (conversion action segmentation)*: In GAQL, `metrics.cost_micros` cannot be selected when segmenting by `segments.conversion_action`. Query conversion action breakdowns separately without `metrics.cost_micros`.

    **Example GAQL Queries:**
    1. To query performance and cost by date and device:
    ```sql
    SELECT
      campaign.name,
      metrics.conversions,
      metrics.conversions_value,
      metrics.cost_micros,
      segments.date,
      segments.device
    FROM campaign
    WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}'
    ```

    2. To query conversion breakdown by conversion action (without `metrics.cost_micros`):
    ```sql
    SELECT
      campaign.name,
      metrics.conversions,
      metrics.conversions_value,
      segments.date,
      segments.conversion_action
    FROM campaign
    WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}'
    ```

3.  **Analyze**: Check if the loss is limited to certain devices (e.g., mobile vs desktop) or specific conversion actions.
4.  **Check Uploads**: If using offline imports, query `offline_conversion_upload_conversion_action_summary` to 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}`:
    ```sql
    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:**
1.  **Query Impression Share**: Use `search` to 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}`:
    ```sql
    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}'
    ```

2.  **Analyze**:
    *   High `search_budget_lost_impression_share` indicates opportunities lost due to limited budget.
    *   High `search_rank_lost_impression_share` indicates opportunities lost due to low ad rank (bid or quality issues).

### 3. Low Lead Flow Diagnostics

When a user asks "why is my lead flow low these past few days?", follow this systematic approach.

From google/skills, Apache-2.0.

More from google/skills