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.

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

Input Schema

TableJSON 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

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?

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial extra context: Google's forecasting window semantics, accuracy caveats for new accounts, null handling via unavailable_metrics, per-account rate limits (~1 keyword planning request/second with throttling behavior), and a minimum amount threshold of 10,000 micros. This is well beyond what structured fields convey.

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 the crucial non-promise caveat, then a compact bidding-strategy block, then per-argument notes. It is long but nearly every sentence adds information; the 'Returns:' section is somewhat redundant given the output schema, and a few lines (e.g., TARGET_SPEND aliasing) could be tightened.

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 14-parameter tool with zero schema descriptions, the definition covers parameter contracts, constraints, rate limiting, forecast semantics, null results, and error/refusal behavior (amounts under 10,000). Nothing an agent needs to call it correctly is missing.

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 full parameter burden and does so thoroughly: per-parameter semantics, defaults (PHRASE match type, MANUAL_CPC, GOOGLE_SEARCH), mutual exclusivity (keywords vs ad_groups), which bid fields each bidding_strategy requires, micros conversion rules, and explicit limits (200 keywords/negatives, 10 geo/language ids, 20 ad groups, 364-day horizon).

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?

Specifies verb and resource precisely: 'Forecasts clicks, impressions and cost for keywords at a bid or a daily budget.' It also distinguishes itself from the other keyword tools by noting they take a single language_id, and its read-only, simulated nature separates it from mutating siblings.

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?

Usage context is implied by the description (planning/estimating, nothing saved or spent) and it notes when Google will return rougher figures or none. However, it never explicitly states when to use this versus get_keyword_ideas, get_keyword_metrics or keyword_opportunities, so alternative selection is left to inference.

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?