AdCopilot

Google Ads: forecast keyword clicks and cost

get_keyword_forecast

Read-onlyIdempotent

Forecasts clicks, impressions and cost for keywords at a bid or a daily budget.

The keywords can be any words, not only the account's own, and the
forecast simulates them in Google's whole search auction.

Google's estimate for the 30 days from two days ahead, or the dates
given, simulated for this account: not a promise, and a new account or
one that has never spent gets rougher figures or none. Nothing is
created, saved or spent. A figure Google does not return is null and
listed in unavailable_metrics with the reason (Google forecasts
conversions for MAXIMIZE_CONVERSIONS).

MANUAL_CPC needs max_cpc_bid_micros (daily_budget_micros optional);
MAXIMIZE_CLICKS (TARGET_SPEND is the same) needs daily_budget_micros,
with max_cpc_bid_ceiling_micros as an optional cap; MAXIMIZE_CONVERSIONS
needs daily_budget_micros. Amounts are micros of the account's currency
(1,000,000 is 1 unit); an amount under 10,000 is refused.

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: [{"text": ..., "match_type": "EXACT", "PHRASE" (default)
        or "BROAD"}], at most 200. Or ad_groups.
    bidding_strategy: MANUAL_CPC (default), MAXIMIZE_CLICKS or
        MAXIMIZE_CONVERSIONS.
    max_cpc_bid_micros: The most to pay for a click (MANUAL_CPC).
    daily_budget_micros: The daily budget.
    max_cpc_bid_ceiling_micros: A cap per click (MAXIMIZE_CLICKS).
    network: GOOGLE_SEARCH (default) or GOOGLE_SEARCH_AND_PARTNERS.
    geo_target_ids: Location ids (geo target constants), at most 10.
    language_ids: Language ids, at most 10 (a list here; the other two
        keyword tools take one language_id).
    negative_keywords: Words the ads stay away from (broad match), at
        most 200.
    start_date: First day, YYYY-MM-DD, after today.
    end_date: Last day, YYYY-MM-DD, at most 364 days from today.
    currency_code: An ISO code to state amounts in. Default: the
        account's currency.
    ad_groups: Instead of keywords, keywords in separate ad groups:
        [{"keywords": [...], "max_cpc_bid_micros": ...,
        "negative_keywords": [...]}], at most 20 (bids on MANUAL_CPC).

Returns:
    forecast (clicks, impressions, click_through_rate, average_cpc,
    cost, conversions, conversion_rate, average_cpa; null when not
    returned), unavailable_metrics, forecast_period, currency_code,
    bidding_strategy, network, keyword_count, ad_group_count, caveat 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>"
    },
    "name": "get_keyword_forecast"
  }
}

Input Schema

Name	Required	Default
`network`	No	GOOGLE_SEARCH
`end_date`	No
`keywords`	No
`ad_groups`	No
`start_date`	No
`customer_id`	Yes
`language_ids`	No
`currency_code`	No
`geo_target_ids`	No
`bidding_strategy`	No	MANUAL_CPC
`negative_keywords`	No
`max_cpc_bid_micros`	No
`daily_budget_micros`	No
`max_cpc_bid_ceiling_micros`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 23, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Beyond the annotations, the description discloses a rate limit of about one keyword planning request per second per account, the behavior when called within that window, the fact that nothing is created, saved, or spent, how missing metrics appear, and why a metric may be in unavailable_metrics. It also explains the forecast horizon and caveats for new or inactive accounts. This is rich behavioral context consistent with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false.

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 the core purpose and is generally well organized, moving from purpose to constraints to parameter details. It is necessarily long for a 14-parameter tool with no schema descriptions, but there is some redundancy between the prose and the explicit Args and Returns sections.

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 complex 14-parameter forecasting tool, the definition covers purpose, return shape, null handling, caveats, rate limits, date limits, amount units, and parameter-specific requirements. Although an output schema exists, the description still adds enough about returned fields and unavailable_metrics to be complete for an agent to call it correctly.

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 the full burden, and it does: it documents all 14 parameters, including keyword match-type structure and default, ad_groups structure, bidding-strategy-dependent requirements, micros formatting, minimum amount rejection, per-list maximums, date constraints, and currency defaults. This goes well beyond the bare types and defaults in the schema.

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 opens with a specific verb and resource: 'Forecasts clicks, impressions and cost for keywords at a bid or a daily budget.' It clearly distinguishes forecast behavior by noting the keywords can be 'any words, not only the account's own' and are simulated in Google's whole search auction. It does not explicitly route against the sibling tools get_keyword_ideas, get_keyword_metrics, or keyword_opportunities, which keeps it from a 5.

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

Usage Guidelines3/5

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

The description gives useful context about when forecasts are reliable, including that a new account or one that has never spent 'gets rougher figures or none.' However, it never says when to choose this tool over get_keyword_ideas, get_keyword_metrics, or keyword_opportunities, so the when-to-use guidance is implied rather than explicit.

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?