Skip to main content
Glama

Keyword ideas (Keyword Planner)

keyword_ideas
Read-only

Generate Google Keyword Planner ideas from seed keywords, a landing page URL, or a whole site, with search volumes, competition, and bid ranges ranked highest first. See what your account already targets or blocks.

Instructions

Google Keyword Planner ideas from seed keywords, a landing-page URL or a whole site: average and monthly searches, competition and the top-of-page bid range in the account's currency, biggest first. Ideas the account already targets, or already blocks as negatives, are marked in_account. Changes nothing.

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": "keyword_ideas"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlNoA page to pull ideas from, such as the ad's landing page
siteNoA whole site's domain, yours or a competitor's (example.com), on its own
limitNoMost ideas to return
monthsNoMonths of history to last month: 12 if left out, 48 most
keywordsNoUp to 20 seed keywords
customer_idYesGoogle Ads customer ID, with or without dashes (from list_accounts)
language_idNoLanguage id (1000 English, 1001 German), name or code ("de"). Leave out for the campaigns' language, or every language when you name locations
location_idsNoWhere to count searches; leave out for where the account's campaigns target. Each a geo target id (2840 United States, 2040 Austria), a country or its code ("Austria", "AT"), a place ("Springfield, Illinois"), or "worldwide" alone for every location
min_searchesNoDrop ideas below this many average monthly searches

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.46.0
    • changedInput schema / properties / location_ids / description
      Previous value: -"Where to count searches; leave out for where the account's campaigns target. Each a geo target id (2840 United States, 2040 Austria), a country or its code (\"Austria\", \"AT\"), or a place (\"Springfield, Illinois\")"New value: +"Where to count searches; leave out for where the account's campaigns target. Each a geo target id (2840 United States, 2040 Austria), a country or its code (\"Austria\", \"AT\"), a place (\"Springfield, Illinois\"), or \"worldwide\" alone for every location"
  2. Changed12 schema fields changedv0.42.0
    • removedInput schema / properties / language_id / default
      Removed value: -"1000"
    • changedInput schema / properties / language_id / description
      Previous value: -"Google language ID. 1000 English, 1003 Spanish, 1002 French, 1001 German, 1014 Portuguese"New value: +"Language id (1000 English, 1001 German), name or code (\"de\"). Leave out for the campaigns' language, or every language when you name locations"
    • addedInput schema / properties / language_id / maxLength
      Added value: +40
    • addedInput schema / properties / language_id / minLength
      Added value: +1
    • removedInput schema / properties / language_id / pattern
      Removed value: -"^\\d+$"
    • removedInput schema / properties / location_ids / default
      Removed value: -[
      -  "2840"
      -]
    • changedInput schema / properties / location_ids / description
      Previous value: -"Google geo target IDs. 2840 United States, 2826 United Kingdom, 2124 Canada, 2036 Australia, 2356 India. For a state, city or other country, look the ID up with run_gaql: SELECT geo_target_constant.id, geo_target_constant.canonical_name FROM geo_target_constant WHERE geo_target_constant.name = 'Denver'"New value: +"Where to count searches; leave out for where the account's campaigns target. Each a geo target id (2840 United States, 2040 Austria), a country or its code (\"Austria\", \"AT\"), or a place (\"Springfield, Illinois\")"
    • addedInput schema / properties / location_ids / items / maxLength
      Added value: +80
    • addedInput schema / properties / location_ids / items / minLength
      Added value: +1
    • removedInput schema / properties / location_ids / items / pattern
      Removed value: -"^\\d+$"
    • addedInput schema / properties / months
      Added value: +{
      +  "description": "Months of history to last month: 12 if left out, 48 most",
      +  "maximum": 48,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedInput schema / properties / site
      Added value: +{
      +  "description": "A whole site's domain, yours or a competitor's (example.com), on its own",
      +  "maxLength": 253,
      +  "minLength": 3,
      +  "type": "string"
      +}
  3. Changed1 schema field changedv0.17.0
    • removedInput schema / properties / confirm_switch
      Removed value: -{
      -  "description": "Only after the user has agreed to spend their plan's account switch (a call answered \"Account switch:\"). Leave out otherwise",
      -  "type": "boolean"
      -}
  4. Changed1 schema field changedv0.14.1
    • addedInput schema / properties / confirm_switch
      Added value: +{
      +  "description": "Only after the user has agreed to spend their plan's account switch (a call answered \"Account switch:\"). Leave out otherwise",
      +  "type": "boolean"
      +}
  5. First observedv0.11.0

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already cover read-only and open-world behavior, but the description adds genuine context beyond them: results are sorted biggest-first, values are in the account's currency, and ideas already targeted or negated are flagged in_account. The main omission is pagination/volume behavior, though limit is documented in the schema.

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?

Three tightly packed sentences with the core purpose front-loaded and no filler. The first sentence is dense and run-on, but every clause carries information about inputs or outputs.

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

Completeness4/5

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

With nine parameters and no output schema, the description does the needed work by naming the returned metrics, sort order, currency, and the in_account marker. What remains thin is guidance on seed-source combinations and result volume, but nothing critical to calling it correctly is missing.

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

Parameters3/5

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

Schema coverage is 100% and the parameter descriptions are unusually rich (geo IDs, language codes, defaults). The description adds only the framing of url/site/keywords as alternative seed sources and the currency context, so the baseline 3 is appropriate.

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 ("Google Keyword Planner ideas") plus the three accepted seed sources, and lists the returned fields. An agent can distinguish it from a metrics-lookup sibling because this one generates ideas from seeds/URL/site rather than reporting on named keywords.

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 implies the discovery use case and notes "Changes nothing," which tells the agent this is a safe read used before creating campaigns. However, it never states when to prefer this over keyword_metrics or other siblings, nor any prerequisites (e.g., that customer_id must come from list_accounts, which is only in the schema).

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