Skip to main content
Glama

XeoRank

by com.xeorank
OverviewDiscussionsAdmin

keyword_competitor_ranks

Read-onlyDestructive

Per-keyword competitive rank tracking: for the keywords a brand TRACKS, which domains rank and at what position — one request for the whole set. This is the tool to use for competitive analysis; discover_competitors answers the weaker question 'who co-ranks for what we ALREADY rank for', which is noise for a new site. Read avg_position, not keyword count: <=3 is entrenched and rarely worth attacking, 11-30 is where the fastest wins are (the bucket field says which). positions maps each keyword to that competitor's rank. Uses the brand's ranking location. Source is our index of Google, so it lags a live SERP.

Input Schema

NameRequiredDescriptionDefault
topNoWith by_keyword: domains per keyword (default 10, max 100)
limitNoCompetitors to return after filtering platforms (default 15, max 1000)
site_idYesBrand/site ID (from list_sites). Uses that brand's tracked keywords — add keywords first if it has none.
by_keywordNoAlso return by_keyword: each tracked keyword's best-ranked domains. Use it for 'who is #1 for X'; the competitor list is ordered by coverage and hides single-keyword leaders.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / by_keyword
      Added value: +{
+  "description": "Also return by_keyword: each tracked keyword's best-ranked domains. Use it for 'who is #1 for X'; the competitor list is ordered by coverage and hides single-keyword leaders.",
+  "type": "boolean"
+}
    • changedInput schema / properties / limit / description
      Previous value: -"Competitors to return after filtering platforms (default 15)"New value: +"Competitors to return after filtering platforms (default 15, max 1000)"
    • addedInput schema / properties / top
      Added value: +{
+  "description": "With by_keyword: domains per keyword (default 10, max 100)",
+  "type": "number"
+}
  2. First observed

TDQS

A4.3/5.0
Behavior4/5

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

Adds context beyond the annotations: it discloses the data source ('our index of Google, so it lags a live SERP') and that it uses the brand's ranking location, plus output-field interpretation for avg_position/bucket. The annotations are internally mixed (readOnlyHint=true alongside destructiveHint=true and idempotentHint=false) but the description does not contradict them; it simply doesn't address that tension.

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 alternative routing, then interpretation guidance and a data-source caveat — each sentence carries information. Slightly dense and mildly editorial ('which is noise for a new site'), but no filler.

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?

No output schema exists, so the description must carry return-value meaning; it explains positions, bucket, and avg_position interpretation. It covers freshness and location scoping. Remaining gap is that it doesn't describe pagination or the exact shape of the returned competitor list beyond ordering by coverage.

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 description coverage is 100%, so top/limit/site_id/by_keyword are already documented. The description's field guidance (positions, bucket, avg_position) describes output rather than inputs and adds no syntax or format detail for the parameters. 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: 'Per-keyword competitive rank tracking' for the keywords a brand tracks, returning which domains rank and at what position. It explicitly distinguishes itself from the sibling discover_competitors, so an agent can route without opening either 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?

Explicit when-to-use routing: 'This is the tool to use for competitive analysis' versus discover_competitors answering 'who co-ranks for what we ALREADY rank for.' It also gives interpretation guidance (read avg_position not keyword count; <=3 entrenched; 11-30 best wins, bucket field identifies which).

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

All XeoRank toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources