Skip to main content
Glama

Visibility Genies

Get ranked keywords

get_ranked_keywords

Returns the keywords a domain or page ranks for in a country-level market: keyword, position, search volume, traffic, CPC, keyword difficulty and URL. By default it asks for Domain Overview's Top keywords page (the 100 keywords with the most traffic), so a page bought here opens free in the app and one bought in the app, or for a new rank tracker's suggestions, is answered here at no charge. Use get_domain_overview for a domain's totals. Estimated price: ~$0.05 for 100 rows, billed by the rows returned; asking again within 12 hours is answered from the saved copy at no charge. 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>",
      "target": "<target>"
    },
    "name": "get_ranked_keywords"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum rows to return (1-100). Defaults to 100; 50 or 100 at an offset that is a multiple of it reads and fills Domain Overview's Top keywords pages.
scopeNoWhich part of the site to research. One of: exact_url (a single page), subfolder (the path and everything under it), domain (the hostname without subdomains), subdomains (the hostname plus all of its subdomains). Defaults to subdomains for a bare domain and to subfolder when the input includes a path.
marketNoLegacy US selector. An explicit locationCode wins over it; leave both out to use the project's market.
offsetNoRows to skip for pagination.
sortByNoSort order for returned rows. Defaults to traffic_estimate, Domain Overview's default.
targetYesDomain without protocol or www (e.g. 'example.com'), or an absolute page URL.
maxRankNoOnly return keywords ranking at this position or better.
projectIdYesRequired. The Visibility Genies project this call works in and is billed to. Call list_projects to find one.
resultTypesNoSERP result types to include. Omit for the default, which Domain Overview uses too.
languageCodeNoLanguage for locationCode. Defaults to that location's primary language when locationCode overrides the project market.
locationCodeNoCountry-level location code. Defaults to the project's market; takes precedence over the legacy market object.
minSearchVolumeNoOnly return keywords with at least this monthly search volume.
excludeBrandTermsNoExclude keywords containing any of these brand terms, each without commas or plus signs, as Domain Overview's exclude filter reads them.
includeSubdomainsNoDeprecated: use scope ('subdomains' or 'domain') instead.
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.

Output Schema

NameRequiredDescriptionDefault
costNo
metaNo
scopeNo
targetNo
keywordsYes
totalCountYes
savedResultIdNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only supply safety flags (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the burden falls on the description, which it meets: estimated price, per-row billing, 12-hour cache reuse, the $2.00 workspace agent spend limit, the held-funds margin, and the refusal-then-approvedMaxCostUsd flow. This explains why a query tool is marked non-read-only and what a call actually costs.

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?

It is front-loaded with purpose and default behavior before pricing, and nearly every sentence carries operational information. The cost paragraph is dense and slightly repetitive (estimate, billing, cache, limit, margin, refusal, approval all in one block), which costs it the top score.

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?

For a 15-parameter tool with an output schema and thin annotations, the description covers cost, caching, defaults and the spend-approval escalation path well. It leaves projectId and the locationCode-vs-legacy-market precedence to the schema, which is acceptable given full coverage, but a pointer to list_projects for the billing project would have closed the loop.

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?

With 100% schema description coverage the baseline is 3, and the description earns an extra point by explaining the cross-parameter default: it returns Domain Overview's Top keywords page (100 keywords by traffic), which ties limit/offset/sortBy choices to the free-cache behavior. It doesn't add anything beyond the schema for the remaining filter parameters.

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?

It states a specific verb and resource ("Returns the keywords a domain or page ranks for in a country-level market") and enumerates the returned fields, so an agent knows exactly what it gets. It also names the sibling it isn't (get_domain_overview) and what that sibling covers instead.

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?

It gives explicit routing guidance: use this for keyword-level rows, use get_domain_overview for a domain's totals, and it notes that calls mirroring Domain Overview's Top keywords page or answered from the 12-hour cache come free. Both the when-to-use and the alternative are stated rather than inferred.

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