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
Behavior5/5

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

Adds substantial behavior beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false): duplicate keywords are silently skipped rather than erroring, operator keywords are rejected, tracking recurs weekly, and billing runs against the workspace's DataForSEO account with per-keyword/per-engine cost. It also discloses the confirm/preview gate and previewToken validity, which the annotations do not cover at all.

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?

A single dense paragraph with no filler; cost, default tracks and the preview gate are all front-loaded. It is slightly long and merges several distinct concerns (dedupe, operators, billing, confirm flow) into one block, which makes scanning harder than a short bulleted structure would.

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?

Covers the essentials for a 9-parameter nested mutation with no output schema: preview/confirm mechanics, cost ceiling from the preview response, default coverage, and rejection rules. It leaves the shape of a successful confirm response (e.g. which keywords were created vs skipped) unspecified, which is the main remaining gap.

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 89%, so the baseline is 3, and the description still adds meaning: the default value of `tracks`, the presence of the `confirm`/`previewToken` two-step flow, the cost multiplier per engine and depth, and the pointer to find_rank_location for location codes. It does not explain `targetUrl` or `tags` semantics, but those are already documented in 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 ("Start tracking keywords") plus the unit of scope (one client, one place, one language). The line "a keyword that is already tracked ... is left as it is" implicitly separates it from update_rank_keywords/remove_rank_keywords, so an agent can place it in the sibling set 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 Guidelines4/5

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

Gives clear operating context: default engines (Google desktop+mobile, top 100), how to widen via tracks, that duplicates are no-ops, that operator keywords are refused, and that find_rank_location supplies the location. It never names the alternative tool to use when a keyword already exists or must be changed, so the agent must infer update_rank_keywords from the no-op note.

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