Skip to main content
Glama

Visibility Genies

Get keyword metrics

get_keyword_metrics

Metrics for a known list: returns search volume, keyword difficulty, intent, CPC, competition and monthly trends for up to 700 keywords you already have, in one call, with no new ideas. For ideas from a seed keyword, use research_keywords. For countries served from Google Ads data, difficulty and intent are null. Estimated price: ~$0.05 for 100 keywords and ~$0.20 for 700, doubled with clickstream, and ~$0.18 a call of up to 700 keywords for countries served from Google Ads data. The same keywords asked for again within 24 hours are answered from the saved copy at no charge. Bought stats also update keywords already in Saved Keywords. Each call may spend up to the workspace's agent spend limit ($2.00 unless changed in Settings) without asking: it holds at most its estimate plus a margin while it runs and is charged what it bought, never more. A call whose maximum is above the limit is refused before anything is bought, with its estimate and maximum: ask the user, then call again with approvedMaxCostUsd set to the amount they approved.

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": {
      "projectId": "<projectId>",
      "keywords": "<keywords>"
    },
    "name": "get_keyword_metrics"
  }
}

Input Schema

NameRequiredDescriptionDefault
sortByNoSort order, highest first. Defaults to search_volume.
keywordsYes
projectIdYesRequired. The Visibility Genies project this call works in and is billed to. Call list_projects to find one.
languageCodeNoLanguage code such as en, es or vi. When left out, the language of the project's default market is used (see list_projects).
locationCodeNoMarket location code, for example 2840 for the United States. When left out, the project's default market is used (shown by list_projects and changed in project settings). A few countries, Iceland (2352) among them, only have Google Ads data: search volume, CPC and trends are available there, but keyword difficulty, search intent and domain analytics are not.
approvedMaxCostUsdNoThe most, in USD, the user approved for this call after seeing its estimate and maximum. Only needed after a call was refused for costing more than the workspace's agent spend limit; never set it without asking the user.
includeMonthlyTrendsNoInclude each keyword's monthly searches. Defaults to true; false leaves them out.
includeClickstreamDataNoRefine volumes with clickstream data, which splits Google Ads grouped close-variant volumes (plurals and misspellings). Doubles the price. No effect for countries served from Google Ads data. Defaults to false.

Output Schema

NameRequiredDescriptionDefault
costNo
metaNo
keywordsYes
savedResultIdNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=false, openWorldHint=true and destructiveHint=false; the description supplies the behavior that actually matters for a billable call: concrete price points per volume tier, the clickstream doubling, a free 24-hour cached re-query, the side effect of updating Saved Keywords, and the hold-then-charge spend-limit mechanics. It even documents the refusal path and how the retry with approvedMaxCostUsd works, which no annotation conveys.

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, then the sibling alternative, then the caveats and cost model, so an agent can stop reading early. The pricing and spend-limit sentences are dense and partly restate the approvedMaxCostUsd schema description, which is the main redundancy.

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?

Given eight parameters, a billing side effect and an output schema that already covers the return shape, the description closes the remaining gaps an agent needs: cost, caching, null conditions, spend-limit refusal and the user-approval step. Nothing required to invoke it safely is missing.

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

Parameters4/5

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

Schema coverage is 88%, so the baseline is 3, but the description adds cost semantics the schema cannot: clickstream doubling the price, country-dependent nulls for difficulty/intent, and the approved-max flow that explains why approvedMaxCostUsd exists. Minor gap: it never mentions sortBy or languageCode fallback behavior, leaving those entirely to the schema.

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 (returns metrics for a known keyword list) and enumerates the exact metrics returned (search volume, difficulty, intent, CPC, competition, monthly trends) plus the 700-keyword ceiling. It explicitly contrasts with 'research_keywords' for seed-based discovery, so an agent can distinguish it from siblings without opening a schema.

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

Usage Guidelines5/5

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

Gives a positive condition ('a known list you already have, no new ideas') and names the alternative with its selection condition ('for ideas from a seed keyword, use research_keywords'). It also states when metrics come back null (Google Ads-only countries) and the escalation path when a call exceeds the spend limit, including asking the user before setting approvedMaxCostUsd.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources