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.

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: 5c9bea8f.

Input Schema

TableJSON 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

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 23, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Beyond annotations that already declare read-only, idempotent, open-world behavior, the description adds important behavioral details: deduplication of near-identical keywords, rows that are not returned, null estimates when volume is too low, potential ranges or no data for new accounts, and rate limiting of roughly one request per second per account.

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?

The description is front-loaded with purpose and constraints, and the Args section is well organized. It is somewhat long, and the Returns section partially restates what the output schema already provides, but the length is largely justified by the tool's complexity.

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 tool with rate limits, deduplication behavior, and account-dependent edge cases, the description provides enough context for an agent to call it correctly. The existence of an output schema means the return-field list is not strictly required, but it is consistent and helpful.

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 must carry parameter meaning. It documents all nine parameters, including customer_id format, keyword limits, geo target maximum and default, language default, network values, CPC/trend toggles, and month-range pairing.

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

Purpose4/5

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

The description states a specific verb and resource: it gets Google's search volume, competition, and bids for keywords 'as written'. This is clear, but it does not explicitly name sibling tools such as get_keyword_ideas or get_keyword_forecast to differentiate when this tool is the right choice.

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?

The description gives clear usage context: it is for keywords an account runs or a list the user names, with call-size limits and the behavior when the list is too long. It does not explicitly state when to use alternative keyword-research tools instead, so it falls short of full when/when-not 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?