Skip to main content
Glama

add_rank_keywords

Start tracking keywords for a client, for one place and language. By default Google on desktop and mobile, top 100; Bing and the local lists ("More places", Google Maps) can be switched on with tracks. A keyword that is already tracked for the same place and language is left as it is; a keyword with a search operator (site:, inurl: …) is refused. Tracking runs weekly on the workspace's own DataForSEO account (or, on a Rank Tracker budget, on CrunchJunkie's account, charged to the budget), so every keyword and every engine adds to what is charged: the preview states the most it can cost per month. Get location from find_rank_location. Requires MCP write actions; without confirm:true it returns a preview.

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": {
      "clientId": "<clientId>",
      "keywords": "<keywords>",
      "location": "<location>",
      "languageCode": "<languageCode>"
    },
    "name": "add_rank_keywords"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagsNo
tracksNoDefault: Google desktop + Google mobile, top 100.
confirmNoSet true to apply. Omit for a preview. With confirm:true, also pass the preview's previewToken.
clientIdYesClient id (from list_clients).
keywordsYesThe keywords, one per entry. An entry may carry its own tags after " | ": "dentist auckland | Local, Core". They are added to the `tags` of the whole call.
locationYesWhere the search is made from.
targetUrlNoThe page the client WANTS to rank for these keywords. A page of the client's own site.
languageCodeYesSearch language, e.g. "en", "de".
previewTokenNoWith confirm:true: the previewToken from this tool's preview (valid 15 minutes, once, for exactly the previewed arguments).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • removedInput schema / additionalProperties
      Removed value: -false
    • removedInput schema / properties / location / additionalProperties
      Removed value: -false
    • addedInput schema / properties / location / properties / locationCode / maximum
      Added value: +9007199254740991
    • removedInput schema / properties / tracks / items / additionalProperties
      Removed value: -false
  2. Changed1 schema field changed
    • changedInput schema / properties / targetUrl / description
      Previous value: -"The page the client WANTS to rank for these keywords. Must be a page of the client's own site."New value: +"The page the client WANTS to rank for these keywords. A page of the client's own site."
  3. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations declare non-read-only, non-destructive, open-world, but the description adds far more: idempotent skip behavior, operator rejection, weekly cadence, billing on the workspace DataForSEO account or a Rank Tracker budget, per-keyword/per-engine cost accrual, and the preview-token safety gate. It stops short of saying what a successful confirmed call returns, but the mutation semantics are unusually well disclosed.

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 defaults, then refusal rules, then cost/confirmation. Nearly every sentence carries operational information, though the cost/billing sentence is dense and long enough to slow scanning. No filler or repetition of the tool name.

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 9-parameter nested-object mutation with no output schema, the definition covers defaults, prerequisites, cost, and the preview/confirm gate well. The one gap is what the preview payload and the confirmed response actually contain beyond the monthly cost figure.

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 already 89%, yet the description still adds meaning: it explains what `tracks` means when omitted, that `location` should come from find_rank_location, and how per-keyword tags are embedded in `keywords` entries via " | ". It does not explain `targetUrl` intent or the `surface` distinctions beyond what the schema already says, so it is additive but not exhaustive.

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?

Opens with a specific verb and resource — "Start tracking keywords for a client, for one place and language" — which is immediately distinguishable from the update_rank_keywords / remove_rank_keywords siblings. The scope (one place, one language) is stated up front.

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?

Explicitly states the defaults (Google desktop+mobile, top 100), how to opt into other engines and local lists via `tracks`, points to find_rank_location for the location, and gives when-not conditions: already-tracked keywords are skipped and operator keywords are refused. Also names the prerequisite (MCP write actions) and the preview-then-confirm workflow.

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