Mark

Suggest Competitors

suggest_competitors

Read-onlyIdempotent

The sites that rank for the most of the same Google keywords as one of your sites in one market: up to 20, most shared keywords first, each with shared keywords, estimated monthly traffic and whether you already track it. Leaves out your own sites, search engines, marketplaces, social, review and directory sites, and .gov/.edu sites. Returns the stored list when there is one; with refresh: true, or when nothing is stored, it fetches fresh data (1 domain) and replaces the stored list. Related: track_competitor, list_competitors.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "suggest_competitors"
  }
}

Input Schema

Name	Required	Description
`siteId`	No	Site id from list_sites. Defaults to the primary site.
`refresh`	No	Fetch fresh suggestions even when a list is stored.
`languageCode`	No	Language code. Defaults to the priority market.
`locationCode`	No	DataForSEO location. Defaults to the priority market.

Output Schema

Name	Required	Description	Default
`appUrl`	Yes
`fetched`	Yes
`suggestions`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 29, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Adds real context beyond the annotations: result cap of 20, ordering, returned fields, an explicit exclusion policy (own sites, search engines, marketplaces, social, review, directory, .gov/.edu), and caching behavior where refresh replaces the stored list. That last point is a mild tension with readOnlyHint=true since a stored list is overwritten, but it is disclosed rather than hidden and affects only cached suggestions, not user data.

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-loads what the tool returns and the ordering before the caveats, and every clause carries information. It is dense — the exclusion sentence is a long enumeration — but nothing is 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?

With an output schema present, return-value detail is not required, and the description covers ranking, limits, exclusions and caching. The remaining gap is cost/latency of a fresh fetch and the fact that it only queries one domain, which is touched on but not quantified.

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 parameter docs are already complete and the baseline is 3. The description clarifies the consequence of refresh (triggers a fresh 1-domain fetch and replaces the stored list), which slightly exceeds the schema's 'fetch fresh suggestions even when a list is stored', but it adds nothing about siteId, languageCode or locationCode defaults.

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+resource (suggest competitor sites) plus precise semantics: ranked by shared Google keywords in one market, up to 20, with the exclusion list spelled out. An agent can distinguish this from list_competitors (already-tracked) and track_competitor without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

The description explains the stored-vs-fresh mechanics but never states when an agent should call this versus list_competitors or track_competitor. 'Related: track_competitor, list_competitors' names siblings without giving a selection rule, so the workflow (suggest, then track) is only implied.

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

All Mark tools Inspect

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

Need Help?