AdCopilot

Google Ads: keyword search volume and bids

get_keyword_metrics

Read-onlyIdempotent

Gets Google's search volume, competition and bids for keywords as written.

The keywords can be any words, and the figures describe searches across
Google, not this account's own traffic.

For the keywords an account runs or a list the user names: up to 1,000
per call, or 200 with include_monthly_trend; a longer list is refused,
not cut. Google counts near-identical keywords (plurals, spellings)
under one row: deduped_away names each with the row it is counted under,
and not_returned names those with no figures. Figures are Google's
estimates; avg_monthly_searches is null where too few to report. A new
account, or one that has never spent, can get ranges or none. It reads
only.

Each call is one request to Google. Google accepts about one keyword
planning request per second per account, so a request within a second
of the last one for the same account waits for the rest of that second.

Args:
    customer_id: The Google Ads customer ID (numbers only, no hyphens).
    keywords: The keywords, as written, 1 to 1,000.
    geo_target_ids: Location ids (geo target constants), at most 10.
        Default: every location.
    language_id: Language id (language constant). Default 1000, English.
    network: GOOGLE_SEARCH (default) or GOOGLE_SEARCH_AND_PARTNERS.
    include_average_cpc: Add the average cost per click. Default true.
    start_year_month: First month, YYYY-MM, with end_year_month.
        Default: the last 12 months.
    end_year_month: Last month, YYYY-MM.
    include_monthly_trend: Add each keyword's searches month by month.

Returns:
    metrics (text, avg_monthly_searches, competition, competition_index,
    low_top_of_page_bid, high_top_of_page_bid, average_cpc,
    close_variants), requested, returned, deduped_away, not_returned,
    query and notes.

Tools revision: d80f65c0.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "customer_id": "<customer_id>",
      "keywords": "<keywords>"
    },
    "name": "get_keyword_metrics"
  }
}

Input Schema

Name	Required	Default
`network`	No	GOOGLE_SEARCH
`keywords`	Yes
`customer_id`	Yes
`language_id`	No
`end_year_month`	No
`geo_target_ids`	No
`start_year_month`	No
`include_average_cpc`	No
`include_monthly_trend`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 23, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond them: hard list-size caps with refusal rather than truncation, deduplication semantics via deduped_away and not_returned, null avg_monthly_searches when volume is too low, degraded results for new or never-spent accounts, and a ~1 request/second per-account rate limit that causes waiting. This is exactly the operational context an agent needs before calling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and scope, then limits, then edge cases, then args and returns. Dense but nearly every sentence carries operational information. It is on the long side and the Returns block partially duplicates the output schema, which keeps it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a nine-parameter, open-world, rate-limited read tool, the description covers scope, limits, failure modes, deduplication, rate limiting, and parameter defaults. An output schema exists, so the brief Returns listing is sufficient rather than redundant.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden, and it documents every one of the nine parameters: customer_id format (numbers only, no hyphens), keyword count range, geo_target_ids max of 10 with default all locations, language_id default 1000, network enum values, include_average_cpc default, paired start/end year-month with a 12-month default, and include_monthly_trend. This fully compensates for the empty schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Gets Google's search volume, competition and bids for keywords') and immediately scopes it: figures describe Google-wide searches, not the account's own traffic. That distinction separates it from account-traffic tools and from siblings like get_keyword_ideas and get_keyword_forecast.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage context ('For the keywords an account runs or a list the user names') and practical limits that shape when it can be called (1,000 keywords, 200 with monthly trend, longer lists refused). It does not explicitly name the alternative tools (get_keyword_ideas, get_keyword_forecast, keyword_opportunities) or state when to prefer them, so it stops short of full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All AdCopilot tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?