Skip to main content
Glama

Visibility Genies

Find search competitors

find_serp_competitors

Compares the domains that compete in Google results for a set of keywords, in a country-level market (location and language codes). It is not radius based local SEO. Returns each domain's keyword count, average and median position, visibility and estimated traffic. Estimated price: ~$0.04 for 50 domains, billed by the domains returned; the same keywords, market and options asked again within 12 hours are 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>",
      "keywords": "<keywords>"
    },
    "name": "find_serp_competitors"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum domains to return. Defaults to 50.
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 visibility.
keywordsYesKeywords to compare. Competitors are the domains ranking for them.
projectIdYesRequired. The Visibility Genies project this call works in and is billed to. Call list_projects to find one.
resultTypesNoSERP result types to count. Defaults to organic and local_pack.
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.
excludeDomainsNoDomains to leave out of the answer, such as the user's own site. Subdomains of them are left out too.
includeSubdomainsNoCount a domain's subdomains as part of it.
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
competitorsYes
savedResultIdNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) by disclosing pricing (~$0.04 per 50 domains, billed on domains returned), the 12-hour free cache window, the workspace spend limit and hold behavior, and the exact refusal-then-approve flow with approvedMaxCostUsd. This is precisely the cost and side-effect context an agent needs before a billable open-world call.

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 the purpose and the negative scope, then the return values, then cost. The billing paragraph is long and slightly repetitive ('it holds at most its estimate plus a margin while it runs and is charged what it bought, never more'), but every clause carries actionable cost information.

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?

For a 12-parameter, billable, open-world tool with an output schema, the description covers scope, return fields, pricing, caching, spend limits, and the approval retry. Nothing an agent needs to call it safely and correctly 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 100%, so the baseline is 3; the description adds meaning by framing market as country-level location/language codes and by explaining the approvedMaxCostUsd approval loop that ties back to the spend-limit refusal. It does not add much for limit, offset, sortBy, or resultTypes beyond what the schema already documents.

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 ('compares the domains that compete in Google results for a set of keywords') plus the scope (country-level market via location and language codes) and explicitly rules out a nearby concept ('not radius based local SEO'). It also enumerates the returned metrics, so an agent knows exactly what it gets back without opening the output 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 conditions for use: country-level market comparison, and an explicit exclusion of radius-based local SEO, which routes the agent toward the local SERP siblings instead. It also documents the retry path after a spend-limit refusal. It stops short of naming a specific alternative for link-based or paid-advertiser competitor questions.

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