Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@seo-data-api-mcp-server show me my top 10 organic keywords"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Before you begin, please ensure you have the following software and accounts ready:
SE Ranking Account: You will need an active SE Ranking account to generate an API token. If you don’t have one, you can sign up here.
Docker: A platform for developing, shipping, and running applications in containers. If you don’t have it, you can download it from the official Docker website.
Docker Compose Plugin: The Docker Compose plugin is a Docker CLI plugin that provides a command-line interface (CLI) for Docker Compose. To build the Docker image, you need to have Docker Compose installed.
Git: A free and open-source distributed version control system. You can download it from the official Git website.
AI Assistant: You will need either the Claude Desktop App or the Gemini CLI installed and configured on your machine.
Follow these steps to install the SEO-MCP server on your local machine.
Open your terminal (or Command Prompt/PowerShell on Windows).
Clone the project repository from GitHub. This command downloads the necessary files to your machine.
git clone https://github.com/seranking/seo-data-api-mcp-server.gitNavigate into the new directory in your terminal:
cd seo-data-api-mcp-serverMake sure you're in the seo-data-api-mcp-server repository directory, and run:
docker compose build
# Check that the image is built and named `se-ranking/seo-data-api-mcp-server`:
docker image lsNote: don't worry about the warnings, this is normal when building the image:
WARN[0000] The "SERANKING_API_TOKEN" variable is not set. Defaulting to a blank string.To ensure you have the latest features and improvements, you should update the tool periodically.
Navigate to your seo-data-api-mcp-server directory in the terminal.
Pull the latest changes from the GitHub repository.
git pull origin mainRelated MCP server: SE Ranking SEO Data API MCP Server
Claude Desktop reads its configuration from claude_desktop_config.json.
Click on the Claude menu and select Settings....
In the Settings window, navigate to the Developer tab in the left sidebar.
Click the Edit Config button to open the configuration file. This action creates a new configuration file if one doesn’t exist or opens your existing configuration.
The file is located at:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %AppData%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Example of Claude Desktop configuration for MCP server
JSON Configuration Template:
{
"mcpServers": {
"seo-data-api-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"SERANKING_API_TOKEN",
"se-ranking/seo-data-api-mcp-server"
],
"env": {
"SERANKING_API_TOKEN": "<your-api-token-here>"
}
}
}
}You need to change the SERANKING_API_TOKEN, get yours from https://online.seranking.com/admin.api.dashboard.html
After saving claude_desktop_config.json, restart Claude Desktop. You should see the server under MCP Servers/Tools.
To verify the setup, ask Claude: Do you have access to MCP? It should respond by listing seo-data-api-mcp.
Your setup is complete! You can now run complex SEO queries using natural language.
Open the Gemini CLI settings file, which is typically located at: ~/.gemini/settings.json
Add the following JSON configuration, making sure to replace the SERANKING_API_TOKEN placeholder value.
{
"mcpServers": {
"seo-data-api-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"SERANKING_API_TOKEN",
"se-ranking/seo-data-api-mcp-server"
],
"env": {
"SERANKING_API_TOKEN": "<your-api-token-here>"
}
}
}
}"SERANKING_API_TOKEN": Use your personal API token, which you can generate from the SE Ranking API Dashboard.
Save the configuration file.
To verify the setup, launch the Gemini CLI by running gemini in your terminal. Once the interface is active, press Ctrl+T to view the available MCP servers. Ensure seo-data-api-mcp is listed.
Your setup is complete! You can now run complex SEO queries using natural language.
In order to run the local Node server, you need to have Node.js 20+ version installed on your machine.
Run the following commands in your terminal:
npm installTo build the project, use the following command:
npm run buildTo start the server use the command:
npm run start-httpThen your HTTP server should be running at: http://0.0.0.0:5000/mcp.
In case you'd like to modify the HOST and PORT, you can do so by creating a .env file in the root directory of the project with the settings you want to override, for example:
HOST=127.0.0.1
PORT=5555Additionally, when you're running the server in the external environments/tools like Replit and similar, you can set the SERANKING_API_TOKEN environment variable in the configuration panel, and the application will use it when you start the server.
Note: If you change the SERANKING_API_TOKEN value when the server is running, you need to restart the server.
With the configuration complete, you can now use natural language prompts to interact with your SE Ranking data. Here is an example prompt to identify low-hanging keyword opportunities for a domain.
Copy and paste the following into your configured AI assistant:
Use the seo-mcp to identify the Keywords my domain is overlooking and find low-hanging fruit opportunities.
1. Analyze my domain's keyword performance:
- Find keywords my domain has lost (not ranking) using the tool for domainKeywords with pos_change=lost.
- Find keywords where my domain's position has gone down using the tool for domainKeywords with pos_change=down.
2. Conduct a competitive analysis:
- Identify my top 2 competitors by finding all competitors with the tool for domainCompetitors and ordering them by common_keywords DESC.
- Find 30 keywords that these competitors are ranking for but my domain is not. Use the domainKeywordsComparison tool with diff=1, order_field=volume, and order_type=DESC.
3. Identify new keyword opportunities:
- For 10 of the competitor keywords found in the previous step, use the tools for relatedKeywords and similarKeywords to find the top 5 related and similar keywords for each, ordered by volume DESC.
4. Synthesize and Report:
- Create a final report of the findings. In the report, highlight potential low-hanging fruit from the new keyword opportunities by analyzing their CPC and keyword difficulty.
Domain to review: seranking.com
Market: usThis prompt instructs the model to perform a comprehensive competitive analysis by:
Finding Lost & Declining Keywords: It first identifies keywords for seranking.com that have either been lost from the rankings or have dropped in position.
Identifying Top Competitors: It finds all organic competitors and sorts them to identify the top two based on the number of shared keywords.
Uncovering Competitor-Ranked Keywords: It compares seranking.com against its top competitors to find 30 high-volume keywords that they rank for, but seranking.com does not.
Generating a Final Report: Finally, it synthesizes all of this information into a concise report, highlighting the most promising opportunities for growth.
To send the sample test request, which will verify if your server runs properly and has the correct setup, open another terminal window, and run the following command with your SE Ranking API token provided as an argument:
./test-http-server-curl-request.sh '<your-api-token-here>'For batch MCP Requests testing, you can use this script:
./test-batch-http-server-curl-request.sh '<your-api-token-here>'If you’re having trouble getting the MCP server to connect, here are a few steps to diagnose the issue.
Verifying if the Docker container is running when you run your AI Assistant (Claude or Gemini). If you start a chat with an AI, and your MCP Server is set up properly via JSON config, it should automatically start the Docker container.
To check if it’s running, open your terminal and run:
docker psIf it’s working correctly, you will see an output similar to this:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
de4e410ef0fd se-ranking/seo-data-api-mcp-server "docker-entrypoint.s…" 9 seconds ago Up 8 seconds musing_bhabhaThis confirms that your AI assistant has successfully started the container, and it’s listening for connections.
If docker ps shows no running containers related to the MCP server, it usually points to a configuration issue:
Incorrect/invalid JSON: Double-check the claude_desktop_config.json or settings.json for any syntax errors like missing commas or brackets. You can validate the JSON here: https://jsonlint.com/.
Incorrect image name: Double-check the claude_desktop_config.json or settings.json for the correct image name se-ranking/seo-data-api-mcp-server
If the docker image is running, but the MCP server is not visible in Claude Desktop, you can investigate the container by:
docker inspect <container-id>For the following example, the container ID is de4e410ef0fd:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
de4e410ef0fd se-ranking/seo-data-api-mcp-server "docker-entrypoint.s…" 9 seconds ago Up 8 seconds musing_bhabhaNote: you can shorten the container ID in case no other containers share that prefix, ex. docker inspect de4. When you're running multiple AI chats and/or tools connected to the MCP Servers, there can be multiple containers running, but all with the same IMAGE name.
This will show you the big JSON output, where particularly important is the "Config" section, ex.:
{
"Config": {
"Hostname": "0977c3dc06fb",
"Domainname": "",
"User": "",
"AttachStdin": true,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": true,
"StdinOnce": true,
"Env": [
"SERANKING_API_TOKEN=8abcdef-6fdd-a981-3ad5-123456",
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
"NODE_VERSION=20.19.5",
"YARN_VERSION=1.22.22",
"NODE_ENV=production"
]
}
}Which shows you if you have the correct environment variables set.
SE Ranking API documentation: https://seranking.com/api/integrations/mcp/.
In case you have any questions or need help, please contact us at api@seranking.com
Retrieve a high-level overview of a domain's performance in LLM: link presence, average position, AI traffic, and historical historical dynamics (trends over time).
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | The target to analyze for LLM performance. Can be a root domain, subdomain, or a specific URL. | |
| scope | No | Scope of analysis: base_domain (the root domain only), domain (the domain including all subdomains), or url (an exact URL). | domain |
| source | Yes | Alpha-2 country code for the regional prompt database (e.g., us for United States results). | |
| engine | Yes | The LLM to query (e.g., ai-overview, chatgpt, perplexity, gemini, ai-mode). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It implies a read operation ('retrieve') and mentions historical dynamics, hinting at aggregated time-series data. However, it does not explicitly state constraints like rate limits, authentication needs, or whether the data is cached or real-time.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with a front-loaded verb and list of metrics, very concise. Penalized slightly for a typo ('historical historical dynamics'), but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters and no output schema, the description covers the what (link presence, position, traffic, trends) but not the why/when relative to siblings. Lacks details on return format or pagination, leaving some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description adds context by naming the output fields but does not elaborate on parameter meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a high-level overview of a domain's LLM performance, listing specific metrics (link presence, average position, AI traffic, historical dynamics). It distinguishes from siblings like aiSearchPromptsByBrand by focusing on summary data, but does not explicitly differentiate from domainAioOverview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as domainAioOverview or aiSearchPromptsByTarget. The description only states what it retrieves, leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a paginated list of prompts where the specified brand is mentioned in LLM results. Maps to /v1/ai-search/prompts-by-brand.
| Name | Required | Description | Default |
|---|---|---|---|
| engine | Yes | LLM to query (e.g., 'ai-overview', 'chatgpt', 'perplexity', 'gemini', 'ai-mode'). | |
| brand | Yes | Brand name to search for in LLM snippets. | |
| source | Yes | Alpha-2 country code of the regional prompt database (e.g., 'us'). | |
| sort | No | The field to sort the results by. Options: volume, type, snippet_length. | volume |
| sort_order | No | Sort direction. Default: desc. | desc |
| limit | No | Max prompts per page (1–1000). Default: 100. | |
| offset | No | Starting index for pagination. Default: 0. | |
| filter[volume][from] | No | Specifies the minimum volume of searches to be included in the results. | |
| filter[volume][to] | No | Specifies the maximum volume of searches to be included in the results. | |
| filter[keyword_count][from] | No | Specifies the minimum number of words in prompts. | |
| filter[keyword_count][to] | No | Specifies the maximum number of words in prompts. | |
| filter[characters_count][from] | No | Specifies the minimum prompt length in characters. | |
| filter[characters_count][to] | No | Specifies the maximum prompt length in characters. | |
| filter[multi_keyword_included] | No | A URL-encoded JSON string specifying keywords that must be present in the prompt. For example: filter[multi_keyword_included]=[[{"type":"contains","value":"seo"},{"type":"contains","value":"tools"}],[{"type":"contains","value":"backlinks"}]] | |
| filter[multi_keyword_excluded] | No | A URL-encoded JSON string specifying keywords that must NOT be present in the prompt. For example: filter[multi_keyword_excluded]=[[{"type":"contains","value":"seo"},{"type":"contains","value":"tools"}],[{"type":"contains","value":"backlinks"}]] |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. The description only states the action and endpoint, omitting details about authorization, rate limits, error behavior, or what happens when the brand is not found. A simple fetch operation still warrants mentioning pagination nuances or data freshness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence efficiently conveys the core purpose and endpoint. No redundant information. Ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 15 parameters, no output schema, and no annotations, the description is insufficient. It does not explain the return format, pagination behavior beyond limit/offset, or how to interpret results. Users would need external documentation for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so each parameter is already well-documented. The description adds only the endpoint mapping and pagination context ('paginated list'), which is marginal. Given the baseline of 3 for high schema coverage, this score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch a paginated list of prompts'), the resource ('prompts where the specified brand is mentioned in LLM results'), and provides the endpoint. This effectively distinguishes it from siblings like 'aiSearchPromptsByTarget' or 'aiSearchOverview'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for brand-specific prompt searches but does not explicitly state when to use this tool versus alternatives (e.g., 'aiSearchPromptsByTarget') or provide context on prerequisites or complementary tools. No when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the list of prompts (queries) that refer to or mention a given target (domain/URL) in the AI Search context. Corresponds to SE Ranking’s “Get Prompts by Target” API section.
| Name | Required | Description | Default |
|---|---|---|---|
| engine | Yes | Type of LLM engine (e.g. 'chatgpt', 'perplexity', 'ai-mode', etc.). | |
| target | Yes | The target to retrieve prompts for (domain, host, or URL). | |
| source | Yes | Alpha-2 country code of the regional prompt database (e.g. 'US'). | |
| scope | No | Scope of analysis: base_domain (the root domain only), domain (the domain including all subdomains), or url (an exact URL). | base_domain |
| sort | No | The field to sort the results by. Options: volume, type, snippet_length. | volume |
| sort_order | No | Sort order ('asc' for ascending, 'desc' for descending). Default is 'desc'. | desc |
| limit | No | Maximum number of prompts to return. | |
| offset | No | Offset for pagination (starting index). | |
| filter[volume][from] | No | Specifies the minimum volume of searches to be included in the results. | |
| filter[volume][to] | No | Specifies the maximum volume of searches to be included in the results. | |
| filter[keyword_count][from] | No | Specifies the minimum number of words in prompts. | |
| filter[keyword_count][to] | No | Specifies the maximum number of words in prompts. | |
| filter[characters_count][from] | No | Specifies the minimum prompt length in characters. | |
| filter[characters_count][to] | No | Specifies the maximum prompt length in characters. | |
| filter[multi_keyword_included] | No | A URL-encoded JSON string specifying keywords that must be present in the prompt. For example: filter[multi_keyword_included]=[[{"type":"contains","value":"seo"},{"type":"contains","value":"tools"}],[{"type":"contains","value":"backlinks"}]] | |
| filter[multi_keyword_excluded] | No | A URL-encoded JSON string specifying keywords that must NOT be present in the prompt. For example: filter[multi_keyword_excluded]=[[{"type":"contains","value":"seo"},{"type":"contains","value":"tools"}],[{"type":"contains","value":"backlinks"}]] |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, rate limits, authentication requirements, or pagination behavior (though limit/offset parameters exist). The description is minimal and does not compensate for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. It front-loads the purpose and references the API section concisely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 16 parameters and no output schema, the description fails to mention return values, error handling, or output format. It is insufficient for a complex tool with rich filtering capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 16 parameters, so the description adds no additional meaning. Baseline score of 3 is appropriate as the schema already provides semantic clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a list of prompts that mention a given target (domain/URL). It uses specific verbs ('Fetch') and resource ('prompts that refer to or mention a given target'), and distinguishes from sibling tools like aiSearchOverview and aiSearchPromptsByBrand.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., aiSearchPromptsByBrand). Sibling tools are listed but no explicit when-to-use or when-not-to-use instructions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch backlinks pointing to a single target with sorting, limits, rank filters, URL/anchor filters, and nofollow filter (v1/backlinks/all)
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | Target to analyze: root domain, host (subdomain), or full URL. | |
| mode | No | Scope: 'domain' (incl. subdomains), 'host' (no subdomains), or 'url' (single URL). Default: host. | host |
| limit | No | Max results to return (1–10,000). Default: 100. | |
| per_domain | No | Number of backlinks per referring domain to return. If omitted, returns all backlinks (may exceed 100). | |
| output | No | Response format. Default: json. | json |
| order_by | No | Sort field: 'date_found' (most recent first), 'domain_inlink_rank', or 'inlink_rank'. | date_found |
| inlink_rank_from | No | Min InLink Rank filter (0–100). | |
| inlink_rank_to | No | Max InLink Rank filter (0–100). | |
| domain_inlink_rank_from | No | Min Domain InLink Rank filter (0–100). | |
| domain_inlink_rank_to | No | Max Domain InLink Rank filter (0–100). | |
| url_from_filter | No | Substring to filter 'url_from' by (ASCII, max 2063 chars). | |
| url_from_filter_mode | No | How to match 'url_from_filter'. Default: contains. | contains |
| url_to_filter | No | Substring to filter 'url_to' by (ASCII, max 2063 chars). | |
| url_to_filter_mode | No | How to match 'url_to_filter'. Default: contains. | contains |
| anchor_filter | No | Substring to filter 'anchor' by (ASCII, max 2063 chars). | |
| anchor_filter_mode | No | How to match 'anchor_filter'. Default: contains. | contains |
| nofollow_filter | No | Backlink type filter: 'nofollow_only' or 'dofollow_only'. If omitted, returns all. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only lists features that are already documented in the input schema (sorting, limits, filters). It does not disclose behavioral traits such as pagination behavior (despite limit and per_domain parameters), rate limits, data freshness, or whether the operation is read-only. The description adds no behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently lists the tool's capabilities. It is not verbose, but it could be improved by separating the purpose from the feature list (e.g., using a colon or bullet points). Still, it is concise and front-loaded with the main action ('Fetch backlinks').
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (17 parameters, no output schema), the description is insufficient. It does not explain the output structure, how results are ordered by default, or how to interpret the limit and per_domain interaction. The detailed parameter schema partially compensates, but the description lacks high-level context for an AI agent to understand the workflow (e.g., pagination, data scope).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, so the baseline is 3. The description redundantly lists parameter categories (e.g., 'rank filters', 'URL/anchor filters') that are already defined in the schema, without adding new semantic meaning. For example, 'nofollow_filter' is mentioned but the description does not explain the difference between 'nofollow_only' and 'dofollow_only' beyond what the enum provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch backlinks') and the resource ('a single target'), and lists all key filtering capabilities (sorting, limits, rank, URL/anchor, nofollow). It also includes the API endpoint (v1/backlinks/all), which helps distinguish it from sibling tools that focus on specific aspects (e.g., backlinksAnchors, backlinksAuthority).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention when to prefer backlinksAll over other backlinks-related siblings (e.g., backlinksAnchors, backlinksSummary) or any prerequisites. The phrase 'with sorting, limits, rank filters' implies feature richness but does not clarify use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch anchor texts of backlinks pointing to a single target with sorting and limit controls (v1/backlinks/anchors)
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | Target to analyze: root domain, host (subdomain), or full URL. | |
| mode | No | Scope: 'domain' (incl. subdomains), 'host' (no subdomains), or 'url' (single URL). Default: host. | host |
| order_by | No | Sort field (descending): 'backlinks' = total backlinks using the anchor; 'refdomains' = total referring domains using the anchor. | backlinks |
| limit | No | Maximum number of results to return (1–10,000). Default: 100. | |
| output | No | Response format. Default: json. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states 'Fetch', implying a read operation, but lacks details on rate limits, pagination behavior, authentication needs, or error handling. Schema covers parameters but description adds no behavioral context beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence front-loads the verb and resource, efficiently conveying core functionality. Slightly improved structure could separate purpose from controls, but overall concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no annotations. The description does not explain return format (though output parameter exists), pagination details, or typical use cases. For a data-fetching tool, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented. The description adds a summary mentioning 'sorting and limit controls', but this adds minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Fetch' and resource 'anchor texts of backlinks' with target scope 'single target'. It distinguishes from sibling tools like backlinksAll by specifying anchor texts specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. Implied usage is for fetching anchor text data, but no mention of alternatives or context for choosing this over other backlinks tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch authority metrics for a target (domain, host or URL) (v1/backlinks/authority)
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | Target to assess authority: root domain, host (subdomain), or full URL. | |
| output | No | Response format. Default: json. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose behavioral traits like rate limits, authentication needs, or what authority metrics entail. Fails to compensate for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence with no fluff. Could front-load more critical info but remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no annotations; description omits return value details, pagination, or usage constraints. Incomplete for a tool that provides authority metrics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage for both parameters. Description adds no additional meaning beyond 'Fetch authority metrics' and repeats target types already in schema. Baseline of 3 stands.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Fetch authority metrics for a target' with specific resource and target types (domain, host, URL). This verb+resource combination distinguishes it from siblings like backlinksAll or backlinksSummary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternative sibling tools (e.g., backlinksSummary, domainOverview). The description lacks any contextual cues for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch site pages that have backlinks, with sorting and limit controls (v1/backlinks/indexed-pages)
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | Target to analyze: root domain, host (subdomain), or full URL. | |
| mode | No | Scope: 'domain' (incl. subdomains), 'host' (no subdomains), or 'url' (single URL). Default: host. | host |
| order_by | No | Sort field (descending): 'backlinks' or 'refdomains'. Default: backlinks. | backlinks |
| limit | No | Maximum number of results to return (1–10,000). Default: 100. | |
| output | No | Response format. Default: json. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full burden. It only states it fetches pages, but does not disclose authentication needs, rate limits, whether the operation is read-only, or any other behavioral traits beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose. The endpoint in parentheses is slightly extraneous but does not harm conciseness. Every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters and no output schema, the description is incomplete. It does not describe the response format or what data is returned for each page (e.g., URL, backlink count). The schema covers parameter constraints but the description lacks return-value context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds little beyond what schema already provides, only mentioning sorting and limit controls generically. No additional meaning or context for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool fetches site pages that have backlinks, with sorting and limit controls. It distinguishes from sibling tools that focus on anchors, refdomains, or summary by explicitly targeting pages with backlinks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like backlinksAll or backlinksAnchors. The description does not mention when-not or provide context for choosing among the backlinks-focused siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch referring domains pointing to a single target with sorting and limit controls (v1/backlinks/refdomains)
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | Target to analyze: root domain, host (subdomain), or full URL. | |
| mode | No | Scope: 'domain' (incl. subdomains), 'host' (no subdomains), or 'url' (single URL). Default: host. | host |
| order_by | No | Sort field: 'date_found' (most recent first), 'domain_inlink_rank' (highest first), or 'inlink_rank' (homepage IR highest first). | date_found |
| limit | No | Max results to return (1–10,000). Default: 100. | |
| output | No | Response format. Default: json. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose behavioral traits like pagination (beyond the limit parameter), response structure, error handling, or rate limits. The description only mentions the endpoint version, which adds minimal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the core action and resource. It is efficient but could be slightly more informative without becoming verbose, making it appropriate for a 5-param tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, the description lacks details on return format, pagination behavior, and edge cases. The sibling tools list is extensive, but the description does not help an agent decide when to use this specific tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already explained. The description adds little beyond summarizing sorting and limit controls, so it meets the baseline but does not elevate understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch'), the resource ('referring domains'), and the context ('pointing to a single target'). It also mentions sorting and limit controls, which distinguishes it from sibling tools like backlinksAll or backlinksAnchors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as backlinksAll or backlinksAuthority. The description does not specify exclusions or conditions, leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch extended backlink statistics for one or multiple targets. Optionally builds an analysis prompt comparing your domain vs a competitor for a given keyword (v1/backlinks/summary)
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | Single target or an array of targets (root domain, host, or full URL). When omitted, it defaults to [domain, competitor] if both are provided. | |
| mode | No | Scope of analysis: 'domain' (*.example.com/* incl. subdomains), 'host' (www.example.com/* only), or 'url' (single URL). Default: host. | host |
| output | No | Response format. Default: json. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits like whether the tool is read-only, what 'extended' statistics entail, rate limits, or auth requirements. The term 'optionally builds an analysis prompt' is vague.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, but the mention of an optional analysis prompt introduces some ambiguity without adding structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and many sibling tools, the description lacks sufficient context about how the summary relates to other backlinks tools, what output to expect, and how to use the optional prompt feature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions, so baseline 3. The description adds only marginal meaning about an optional analysis prompt not reflected in the schema, but does not clarify parameter semantics further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches extended backlink statistics for one or multiple targets, and mentions an optional analysis prompt for competitor comparison, which distinguishes it from sibling tools focusing on specific backlink data like anchors or refdomains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description hints at a competitor comparison use case but provides no explicit when-to-use or when-not-to-use guidance, nor direct alternatives among the many backlink sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch domain ads by domain (v1/domain/ads)
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Alpha-2 country code of the regional keyword database. | |
| domain | Yes | The specific domain for which to retrieve its paid ad data. | |
| from | No | The starting year and month for the data retrieval period, formatted as “YYYY-MM” (e.g., “2017-01”). | |
| to | No | The ending year and month for the data retrieval period, formatted as “YYYY-MM”. | |
| page | No | For paginated results, specifies the page number of domains advertising on this keyword to retrieve. | |
| limit | No | The maximum number of domains (advertising on the keyword) to return per page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Only states what the tool does, but discloses no behavioral traits such as pagination behavior, rate limits, or data returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely short (one sentence) but under-specified; includes unnecessary API version info while omitting key context. Not efficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, no output schema, and no annotations, the description is incomplete; lacks explanation of pagination, return format, or how to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; description adds no additional meaning beyond schema descriptions, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states action ('Fetch') and resource ('domain ads'), but merely repeats the tool name and doesn't differentiate from sibling tools like 'domainAdsByKeyword'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., domainAdsByKeyword), no context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch domain ads by keyword (v1/domain/ads)
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Alpha-2 country code of the regional keyword database. | |
| keyword | Yes | The specific keyword for which to retrieve paid ad data. | |
| from | No | The starting year and month for the data retrieval period, formatted as “YYYY-MM” (e.g., “2017-01”). | |
| to | No | The ending year and month for the data retrieval period, formatted as “YYYY-MM”. | |
| page | No | For paginated results, specifies the page number of domains advertising on this keyword to retrieve. | |
| limit | No | The maximum number of domains (advertising on the keyword) to return per page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'fetch' implying a read operation but does not explicitly state idempotency, rate limits, or pagination behavior. The description lacks disclosure of what the tool returns or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence), which is concise but at the cost of providing necessary context. It is front-loaded but does not earn its place with substantive information beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and no annotations, the description is incomplete. It does not describe the return value, pagination details, or how the data is structured. The tool has 6 parameters with pagination, yet the description offers no guidance on usage patterns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, so the description does not need to add much. The description itself adds no parameter-specific meaning beyond the endpoint name, which is acceptable given schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Fetch domain ads by keyword' which specifies the verb and resource, but it does not distinguish this tool from the sibling tool 'domainAdsByDomain', which also fetches ads but by domain. The lack of differentiation reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like domainAdsByDomain or other keyword tools. There is no discussion of prerequisites, context, or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch AI Overviews brand names (v1/domain/aio/discover-brand)
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | The alpha-2 country code for the regional database. Example: us | |
| target | Yes | The domain, subdomain, or URL to analyze. Example: seranking.com | |
| scope | No | The scope of the analysis. Can be base_domain (domain and all subdomains), domain (specific host), or url (exact URL). | base_domain |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears the full burden of disclosing behavioral traits. It only hints at a read operation ('Fetch') but omits any details about side effects, permissions, rate limits, or return format. The description is insufficient for an agent to understand the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence), but it sacrifices utility for brevity. It could be considered efficient, but the lack of contextual information makes it less helpful. No structure or front-loading of key information is evident.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters, no output schema, no annotations), the description is incomplete. It fails to explain what the output contains, how results are structured, or any limitations. The tool's purpose is vaguely stated but not sufficiently elaborated for an agent to use it correctly without additional knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds no additional meaning beyond the schema; it does not clarify parameter usage or format beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch AI Overviews brand names' provides a clear verb and resource, but it essentially restates the tool name and title without differentiation from sibling tools like domainAioKeywordsByBrand or domainAioOverview. It lacks specificity about what constitutes a 'brand name' in this context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus its siblings. The description does not mention any prerequisites, context, or scenarios where this tool is appropriate or not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch AI Overviews domain keywords by brand (v1/domain/aio/keywords-by-brand)
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | The alpha-2 country code for the regional database. Example: us | |
| brand | Yes | The brand name to search for in AIO snippets. Example: SE Ranking. | |
| scope | No | The scope of the analysis. Can be base_domain (domain and all subdomains), domain (specific host), or url (exact URL). | base_domain |
| sort | No | The field to sort the results by. Available values: volume, type, snippet_length. | volume |
| sort_order | No | The order for sorting. Available values: asc, desc. | desc |
| offset | No | The starting position for paginated results. | |
| limit | No | The maximum number of keywords to return per page. | |
| filter[volume][from] | No | Specifies the minimum monthly search volume for keywords to be included. | |
| filter[volume][to] | No | Specifies the maximum monthly search volume for keywords to be included. | |
| filter[difficulty][from] | No | Specifies the minimum keyword difficulty score (typically 0-100) for keywords to be included. | |
| filter[difficulty][to] | No | Specifies the maximum keyword difficulty score for keywords to be included. | |
| filter[keyword_count][from] | No | Specifies the minimum number of words in a keyword phrase. | |
| filter[keyword_count][to] | No | Specifies the maximum number of words in a keyword phrase. | |
| filter[intents] | No | A comma-separated list of search intent codes to filter keywords. | |
| filter[competition][from] | No | Specifies the minimum competition score (typically 0-1 or 0-100, depending on the metric scale) for keywords. | |
| filter[competition][to] | No | Specifies the maximum competition score for keywords. | |
| filter[cpc][from] | No | Specifies the minimum Cost Per Click (CPC) value for keywords. | |
| filter[cpc][to] | No | Specifies the maximum Cost Per Click (CPC) value for keywords. | |
| filter[traffic][from] | No | Specifies the minimum estimated monthly traffic for keywords. | |
| filter[traffic][to] | No | Specifies the maximum estimated monthly traffic for keywords. | |
| filter[position][from] | No | Specifies the minimum ranking position for keywords. | |
| filter[position][to] | No | Specifies the maximum ranking position for keywords. | |
| filter[characters_count][from] | No | Specifies the minimum character length for keyword phrases. | |
| filter[characters_count][to] | No | Specifies the maximum character length for keyword phrases. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only provides the endpoint path, omitting any details about authentication, rate limits, data freshness, pagination limits, or what happens with missing brands. This is severely lacking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (one sentence) but under-specified. It provides no helpful structure or front-loaded key information. It sacrifices completeness for brevity, making it less useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 24 parameters, 2 required, and no output schema. The description is far too minimal to cover the complexity. It does not explain return structure, pagination, or how filters interact, leaving the agent with only the schema to infer behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents each parameter's meaning. The description adds no additional semantic value beyond the endpoint context. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch AI Overviews domain keywords by brand' clearly states the verb (fetch) and resource (AIO domain keywords by brand). It distinguishes from sibling tools like domainAioKeywordsByTarget, but does not explicitly mention how it differs, so it's not a full 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like domainAioKeywordsByTarget or domainAioOverview. The description fails to provide context for selection, leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch AI Overviews domain keywords by target (v1/domain/aio/keywords-by-target)
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | The alpha-2 country code for the regional database. Example: us | |
| target | Yes | The domain, subdomain, or URL to analyze. Example: seranking.com | |
| scope | No | The scope of the analysis. Can be base_domain (domain and all subdomains), domain (specific host), or url (exact URL). | base_domain |
| sort | No | The field to sort the results by. Available values: volume, type, snippet_length. | volume |
| sort_order | No | The order for sorting. Available values: asc, desc. | desc |
| offset | No | The starting position for paginated results. | |
| limit | No | The maximum number of keywords to return per page. | |
| filter[volume][from] | No | Specifies the minimum monthly search volume for keywords to be included. | |
| filter[volume][to] | No | Specifies the maximum monthly search volume for keywords to be included. | |
| filter[difficulty][from] | No | Specifies the minimum keyword difficulty score (typically 0-100) for keywords to be included. | |
| filter[difficulty][to] | No | Specifies the maximum keyword difficulty score for keywords to be included. | |
| filter[keyword_count][from] | No | Specifies the minimum number of words in a keyword phrase. | |
| filter[keyword_count][to] | No | Specifies the maximum number of words in a keyword phrase. | |
| filter[intents] | No | A comma-separated list of search intent codes to filter keywords. | |
| filter[competition][from] | No | Specifies the minimum competition score (typically 0-1 or 0-100, depending on the metric scale) for keywords. | |
| filter[competition][to] | No | Specifies the maximum competition score for keywords. | |
| filter[cpc][from] | No | Specifies the minimum Cost Per Click (CPC) value for keywords. | |
| filter[cpc][to] | No | Specifies the maximum Cost Per Click (CPC) value for keywords. | |
| filter[traffic][from] | No | Specifies the minimum estimated monthly traffic for keywords. | |
| filter[traffic][to] | No | Specifies the maximum estimated monthly traffic for keywords. | |
| filter[position][from] | No | Specifies the minimum ranking position for keywords. | |
| filter[position][to] | No | Specifies the maximum ranking position for keywords. | |
| filter[characters_count][from] | No | Specifies the minimum character length for keyword phrases. | |
| filter[characters_count][to] | No | Specifies the maximum character length for keyword phrases. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides no behavioral context beyond the bare endpoint. With no annotations and no mention of rate limits, pagination behavior (beyond offset/limit schema), or response characteristics, the agent is left uninformed about important runtime aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (a single sentence repeating the endpoint), but for a tool with 24 parameters, this is under-specification rather than conciseness. Important context is missing, making it inadequate for effective tool selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite rich parameter documentation in the schema, the description omits any explanation of the return data, pagination logic, or domain relationship. Without an output schema, the agent lacks essential completion information for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so parameters are already well-documented. The description adds no additional semantic value beyond the endpoint name, but given full schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches AI Overviews domain keywords by target, using a specific verb 'Fetch' and indicating the resource. However, it does not differentiate from sibling tools like domainAioKeywordsByBrand, as it only restates the endpoint path without additional context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., domainAioOverview or domainAioKeywordsByBrand). There is no mention of prerequisites, scenarios, or exclusions, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch AI Overviews domain metrics (v1/domain/aio/overview)
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | The alpha-2 country code for the regional database. Example: us | |
| target | Yes | The domain, subdomain, or URL to analyze. Example: seranking.com | |
| scope | No | The scope of the analysis. Can be base_domain (domain and all subdomains), domain (specific host), or url (exact URL). | base_domain |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only states 'Fetch' implying read-only, but doesn't disclose any behavioral traits like data freshness, pagination, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is extremely concise. However, it could include a bit more context without becoming verbose. Still, it is efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters, no output schema, and no annotations, the description is insufficient. It does not explain return values, limitations, or how the tool fits into the workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive parameter names and descriptions. The description adds no additional meaning beyond the schema, achieving the baseline for adequate parameter clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states action 'Fetch' and resource 'AI Overviews domain metrics', distinguishing it from siblings like aiSearchOverview or domainKeywords. However, it could be more specific about what metrics are returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings like domainAioDiscoverBrand or domainAioKeywordsByTarget. The description lacks context for when AI Overviews domain metrics are appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch domain competitors (v1/domain/competitors)
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Alpha-2 country code of the regional keyword database. | |
| domain | Yes | The primary domain for which to find competitors. | |
| type | No | Specifies whether to find competitors in organic search results or paid search (advertising). | organic |
| stats | No | A flag to control the level of detail in the response. If set to “1”, additional statistical parameters are returned for each competitor. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must convey behavioral traits. It only states 'Fetch', implying read-only, but does not disclose response size limits, authentication needs, or error handling. The API version is noted but adds little behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the tool's purpose. There is no wasted text, and it is front-loaded with the critical action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has four parameters and no output schema. The description does not explain what the response contains (e.g., list of competitor domains, metrics, pagination), leaving the agent to guess the output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no parameter information beyond what the schema provides. Baseline score of 3 is appropriate as the schema already documents all parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'domain competitors', distinguishing it from sibling tools like domainKeywords or domainOverview. However, it could be more specific about what constitutes a competitor (e.g., domains that rank for same keywords).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. With a large set of sibling tools, this lack of direction forces the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch domain keywords (v1/domain/keywords)
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Alpha-2 country code of the regional keyword database. | |
| domain | Yes | The domain name for which to retrieve keywords. | |
| type | No | Specifies whether to retrieve keywords for organic search traffic or paid search (advertising) traffic. | organic |
| order_field | No | The field by which the returned keyword list should be sorted. | traffic |
| order_type | No | The order of sorting. | desc |
| page | No | For paginated results, specifies the page number to retrieve. | |
| limit | No | The maximum number of keywords to return per page. | |
| cols | No | A comma-separated list of specific response parameter names to include in the output. If omitted, a default set of relevant columns is returned. | |
| pos_change | No | Filters keywords based on changes in their ranking positions compared to the previous period. | |
| filter[volume][from] | No | Specifies the minimum monthly search volume for keywords to be included. | |
| filter[volume][to] | No | Specifies the maximum monthly search volume for keywords to be included. | |
| filter[difficulty][from] | No | Specifies the minimum keyword difficulty score (typically 0-100) for keywords to be included. | |
| filter[difficulty][to] | No | Specifies the maximum keyword difficulty score for keywords to be included. | |
| filter[keyword_count][from] | No | Specifies the minimum number of words in a keyword phrase. | |
| filter[keyword_count][to] | No | Specifies the maximum number of words in a keyword phrase. | |
| filter[intents] | No | A comma-separated list of search intent codes to filter keywords. | |
| filter[competition][from] | No | Specifies the minimum competition score (typically 0-1 or 0-100, depending on the metric scale) for keywords. | |
| filter[competition][to] | No | Specifies the maximum competition score for keywords. | |
| filter[cpc][from] | No | Specifies the minimum Cost Per Click (CPC) value for keywords. | |
| filter[cpc][to] | No | Specifies the maximum Cost Per Click (CPC) value for keywords. | |
| filter[traffic][from] | No | Specifies the minimum estimated monthly traffic for keywords. | |
| filter[traffic][to] | No | Specifies the maximum estimated monthly traffic for keywords. | |
| filter[position][from] | No | Specifies the minimum ranking position for keywords. | |
| filter[position][to] | No | Specifies the maximum ranking position for keywords. | |
| filter[characters_count][from] | No | Specifies the minimum character length for keyword phrases. | |
| filter[characters_count][to] | No | Specifies the maximum character length for keyword phrases. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only gives the endpoint path, omitting details like read-only nature, required authentication, rate limits, or error scenarios. This is insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that essentially repeats the endpoint name. It is under-specified and fails to provide useful information efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 26 parameters, no output schema, and no annotations, the description is extremely incomplete. It lacks information on pagination, sorting, filtering semantics, return format, and behavior with invalid inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 26 parameters. The description adds no extra meaning beyond the schema, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'domain keywords', making the tool's core purpose unambiguous. However, it does not distinguish this tool from siblings like 'domainKeywordsComparison' or 'keywordsLongtail', missing a chance to differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. Among many sibling keyword tools, explicit when-to-use and when-not-to-use advice would significantly help an agent select correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyzes and compares the keyword rankings of two websites: domain and compare. It can find keywords they have in common or identify a 'keyword gap'—keywords for which the domain ranks, but the compare domain does not.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Alpha-2 country code of the regional keyword database. | |
| domain | Yes | The primary domain for the analysis. For a keyword gap analysis (`diff=1`), this will be the domain that has the keywords. | |
| compare | Yes | The secondary domain for comparison. For a keyword gap analysis (`diff=1`), this will be the domain that is missing the keywords. | |
| type | No | Specifies whether to compare keywords based on organic search traffic or paid search (advertising) traffic. | organic |
| page | No | For paginated results, specifies the page number of keywords to retrieve. | |
| limit | No | The maximum number of keywords to return per page. | |
| cols | No | A comma-separated list of specific response parameter names to include in the output. If omitted, a default set of relevant columns is returned for the comparison. | |
| diff | No | Controls the comparison mode. Use `0` to find keywords common to both domains. Use `1` for a keyword gap analysis to find keywords the `domain` ranks for, but the `compare` domain does not. | |
| order_field | No | Specifies the field by which to sort the results. | keyword |
| order_type | No | Specifies the sort order for the results. | asc |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states the tool is read-only (analyzes/comparses), but does not mention required permissions, rate limits, data freshness, or side effects. The description lacks depth for a complex tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, efficient and front-loaded. No redundant information. Every sentence serves a purpose: first states core function, second clarifies the two comparison modes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal for a tool with 10 parameters and no output schema. It covers the main idea but does not elaborate on pagination, sorting, or typical use cases. The schema fills some gaps, but the description could be richer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter. The description adds overarching context (e.g., explaining diff=0 vs 1, and which domain has keywords in gap mode). This adds moderate value beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares keyword rankings between two domains, with two modes (common keywords or gap). It uses specific verbs ('analyzes', 'compares', 'finds'). However, it does not explicitly differentiate from sibling tools like 'domainKeywordsReverseComparison', which likely does the opposite comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for comparing two domains, but provides no explicit guidance on when to use this tool versus alternatives (e.g., domainCompetitors, domainKeywords). No 'when not to use' or prerequisite conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare keywords across domains (v1/domain/keywords/comparison)
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Alpha-2 country code of the regional keyword database. | |
| domain | Yes | The primary domain for the comparison. | |
| compare | Yes | The competitor domain to compare against the primary domain. | |
| type | No | Specifies whether to compare keywords based on organic search traffic or paid search (advertising) traffic. | organic |
| page | No | For paginated results, specifies the page number of keywords to retrieve. | |
| limit | No | The maximum number of keywords to return per page. | |
| cols | No | A comma-separated list of specific response parameter names to include in the output. If omitted, a default set of relevant columns is returned for the comparison. | |
| order_field | No | Specifies the field by which to sort the results. | keyword |
| order_type | No | Specifies the sort order for the results. | asc |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavioral traits. It fails to mention any: no indication of side effects (likely read-only but unstated), no rate limits, no auth requirements. The bare description adds nothing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence but is under-specified, providing minimal value. It does not effectively front-load key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, no output schema, and no annotations, the description is far from complete. It lacks explanation of result format, pagination details, or how the comparison differs from similar tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description itself adds no extra meaning beyond what the input schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Compare keywords across domains' which indicates the core action and resource, but it lacks differentiation from the sibling tool 'domainKeywordsComparison'. The term 'Reverse' in the title is not explained.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus the similar sibling 'domainKeywordsComparison'. No context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch domain overview (v1/domain/overview)
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain for which to retrieve database data. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It fails to mention any traits such as read-only nature, rate limits, or potential side effects. The description is essentially a restatement of the endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but at the expense of informativeness. It repeats the endpoint path, which is not useful for understanding the tool's purpose. It could be restructured to add value without increasing length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is incomplete. It does not explain what the returned data represents, how to interpret it, or any limitations. For a simple one-parameter tool, it still leaves key questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'domain' described minimally. The tool description adds no extra meaning beyond the schema. Baseline score of 3 applies because the schema covers the parameter, but the description does not enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Fetch domain overview' which identifies the action and resource, but it is vague and does not distinguish from numerous sibling tools like domainOverviewDb or domainOverviewHistory. The lack of specificity about what the overview contains reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention context, prerequisites, or exclusions, leaving the agent to guess which domain overview tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch domain overview by database (v1/domain/overview/db)
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Alpha-2 country code of the regional keyword database. | |
| domain | Yes | The domain for which to retrieve the keyword statistics. | |
| with_subdomains | No | A flag to determine whether data for subdomains should be included in the analysis. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full weight. It only states 'Fetch' with no details on side effects, data freshness, rate limits, or response structure. It does not disclose if the operation is read-only or has any behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence) but at the cost of completeness. It fails to convey essential information, making it under-specified rather than efficiently precise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a complex domain (keyword statistics over regional databases), the description is insufficient. It does not explain what the response contains or how the three parameters interact. The agent would lack key information to validate results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear descriptions for each parameter (source as country code, domain as keyword statistics, with_subdomains flag). The tool description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch domain overview by database (v1/domain/overview/db)' is nearly a tautology of the tool name, providing no explanation of what 'overview' entails or how it differs from sibling tools like domainOverview, domainOverviewWorldwide, etc. The parameter description for 'domain' mentioning 'keyword statistics' introduces ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions. The agent is left to infer usage solely from the parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch domain historical overview (v1/domain/overview/history)
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Alpha-2 country code of the regional keyword database. | |
| domain | Yes | The domain name for which to retrieve historical performance data. | |
| type | No | Specifies whether to retrieve historical data for organic search traffic or paid search (advertising) traffic. | organic |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It only repeats the API endpoint and does not disclose what historical data is returned, time range, or any operational constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but includes redundant API endpoint. Could be more informative without adding length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without output schema or annotations, the description should explain return values and scope. It does not address what the historical overview contains, limiting completeness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no extra context beyond the schema, but the schema itself is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches domain historical overview, which is a specific verb+resource. The term 'history' helps distinguish from current overview tools like domainOverview, but no explicit differentiation is made, so it's not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. A long list of sibling tools exists, but the description provides no context for selection or exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch domain worldwide overview (v1/domain/overview/worldwide)
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain name for which to retrieve worldwide statistics. | |
| currency | No | An ISO 4217 currency code to be used for any monetary values (like traffic cost) returned in the response. | USD |
| fields | No | A comma-separated list specifying which data fields or categories to include in the response. This allows for tailoring the response to only the needed information. | price, traffic, keywords |
| show_zones_list | No | A boolean-like value (“1” for true, “0” for false) to determine if the response should include a detailed breakdown of statistics for each individual regional zone (country) in addition to the aggregated worldwide statistics. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavioral traits. It only states the action, omitting details about rate limits, data freshness, or side effects. The parameter descriptions in the schema do not compensate for the lack of behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at 10 words, but it may be too terse. It front-loads the action but lacks structure and often omits important context, making it merely adequate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters and no output schema, the description should provide more context about the response or typical usage. It only mentions the endpoint path, leaving the agent uncertain about the data structure and scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 4 parameters have full descriptions in the schema with default values. The tool description adds no extra semantic information, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'domain worldwide overview', distinguishing it from sibling overview tools by its geographic scope. However, it does not specify what data fields are included in the overview, relying on the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool over alternatives like domainOverview or domainOverviewDb. The description lacks any context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk retrieve metrics for a list of keywords (v1/keywords/export, POST form-data; source in query)
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Alpha-2 country code of the regional keyword database. | |
| keywords | Yes | For a single keyword, use one keywords[] parameter. Repeat the keywords[] to analyze multiple keywords. A maximum of 5,000 keywords can be submitted per call. | |
| sort | No | The field by which the returned list of keywords should be sorted. Common sortable fields include volume, cpc, difficulty, competition. | cpc |
| sort_order | No | The order of sorting for the sort field. | desc |
| cols | No | A comma-separated list of specific response parameter names to include in the output for each keyword. If omitted, all available data points are returned. | keyword, volume, cpc, competition, difficulty, history_trend |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions 'POST form-data; source in query' but lacks behavioral details like rate limits, data freshness, error handling, or response structure. The schema caps keywords at 5000, but description does not reinforce or explain this.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence) and front-loaded with the core action. However, it includes technical details (endpoint, method) that could be moved to the schema or noted separately. It is adequate but not structured for maximum clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters, no output schema, no annotations), the description is incomplete. It omits return value format, usage context among sibling tools, and any important behavioral notes. The schema provides param details, but the description adds little context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add extra meaning beyond schema; the parameters are already well-documented in the schema. The mention of 'source in query' is a minor technical detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Bulk retrieve metrics for a list of keywords', specifying the action (retrieve metrics) and scope (list of keywords). The endpoint and method are provided, distinguishing it from sibling tools that focus on specific keyword queries like questions or related.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives like keyword-specific tools. It does not mention when not to use it or provide any context for selection among similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch longtail (low search volume) keywords (v1/keywords/longtail)
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Alpha-2 country code of the regional keyword database. | |
| keyword | Yes | The seed keyword for which to find similar keywords. | |
| limit | No | Maximum number of keywords to return per page. | |
| offset | No | Starting offset for pagination. | |
| sort | No | The field by which the returned list of keywords should be sorted. | |
| sort_order | No | The order of sorting for the sort field. | |
| filter[volume][from] | No | Minimum monthly search volume. | |
| filter[volume][to] | No | Maximum monthly search volume. | |
| filter[difficulty][from] | No | Minimum keyword difficulty score (0-100). | |
| filter[difficulty][to] | No | Maximum keyword difficulty score (0-100). | |
| filter[cpc][from] | No | Minimum Cost Per Click. | |
| filter[cpc][to] | No | Maximum Cost Per Click. | |
| filter[competition][from] | No | Minimum competition score (0.0-1.0). | |
| filter[competition][to] | No | Maximum competition score (0.0-1.0). | |
| filter[keyword_count][from] | No | Minimum number of words in the keyword. | |
| filter[keyword_count][to] | No | Maximum number of words in the keyword. | |
| filter[characters_count][from] | No | Minimum character length of the keyword. | |
| filter[characters_count][to] | No | Maximum character length of the keyword. | |
| filter[serp_features] | No | Comma-separated list of SERP features to filter by. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only states 'Fetch longtail (low search volume) keywords' without disclosing behavioral traits such as pagination, rate limits, or what happens if no results are found. The endpoint is mentioned but adds minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very short (one sentence), achieving conciseness, but it lacks structure such as sections or bullet points. It could be more informative without being overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 19 parameters, no output schema, and no annotations, the description is too brief. It does not explain return values, pagination, or filter behavior, leaving the agent without sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 19 parameters have descriptions), so the description does not need to add much. The description itself adds no parameter-specific meaning; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it fetches longtail keywords with low search volume, and the name 'keywordsLongtail' aligns with sibling tools like 'keywordsRelated' and 'keywordsSimilar', providing some differentiation. However, it could more explicitly contrast with similar keyword tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., keywordsRelated or keywordsSimilar). The description does not mention prerequisites, when not to use it, or preferred use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch keyword questions (v1/keywords/questions)
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Alpha-2 country code of the regional keyword database. | |
| keyword | Yes | The seed keyword for which to find similar keywords. | |
| limit | No | Maximum number of keywords to return per page. | |
| offset | No | Starting offset for pagination. | |
| sort | No | The field by which the returned list of keywords should be sorted. | |
| sort_order | No | The order of sorting for the sort field. | desc |
| history_trend | No | Whether to include historical search volume trend data in the response. | |
| filter[volume][from] | No | Minimum monthly search volume. | |
| filter[volume][to] | No | Maximum monthly search volume. | |
| filter[difficulty][from] | No | Minimum keyword difficulty score (0-100). | |
| filter[difficulty][to] | No | Maximum keyword difficulty score (0-100). | |
| filter[cpc][from] | No | Minimum Cost Per Click. | |
| filter[cpc][to] | No | Maximum Cost Per Click. | |
| filter[competition][from] | No | Minimum competition score (0.0-1.0). | |
| filter[competition][to] | No | Maximum competition score (0.0-1.0). | |
| filter[keyword_count][from] | No | Minimum number of words in the keyword. | |
| filter[keyword_count][to] | No | Maximum number of words in the keyword. | |
| filter[characters_count][from] | No | Minimum character length of the keyword. | |
| filter[characters_count][to] | No | Maximum character length of the keyword. | |
| filter[serp_features] | No | Comma-separated list of SERP features to filter by. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only mentions the API endpoint and fails to state any behavioral traits like read-only nature, pagination behavior, response format, or side effects. This is a critical gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (one phrase) which is concise but lacks structure or complete sentences. It is not front-loaded with key information; it barely communicates purpose. A 3 is adequate but not well-crafted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 20 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain what the tool returns, how to interpret results, or any usage constraints. A 1 indicates significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters have descriptions in the schema. The tool description itself adds no additional meaning beyond the schema. Baseline 3 is appropriate as the description does not detract but adds no value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Fetch keyword questions' which is a specific verb and resource, but it lacks any explanation of what 'keyword questions' are, making it minimally clear. It does not distinguish from sibling tools like keywordsSimilar or keywordsLongtail. A score of 3 reflects adequate but not differentiating clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as when a user needs question-based keywords versus related keywords or long-tail keywords. There are no explicit usage contexts or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch related keywords (v1/keywords/related)
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Alpha-2 country code of the regional keyword database. | |
| keyword | Yes | The seed keyword for which to find similar keywords. | |
| limit | No | Maximum number of keywords to return per page. | |
| offset | No | Starting offset for pagination. | |
| sort | No | The field by which the returned list of keywords should be sorted. | |
| sort_order | No | The order of sorting for the sort field. | desc |
| history_trend | No | Whether to include historical search volume trend data in the response. | |
| filter[volume][from] | No | Minimum monthly search volume. | |
| filter[volume][to] | No | Maximum monthly search volume. | |
| filter[difficulty][from] | No | Minimum keyword difficulty score (0-100). | |
| filter[difficulty][to] | No | Maximum keyword difficulty score (0-100). | |
| filter[cpc][from] | No | Minimum Cost Per Click. | |
| filter[cpc][to] | No | Maximum Cost Per Click. | |
| filter[competition][from] | No | Minimum competition score (0.0-1.0). | |
| filter[competition][to] | No | Maximum competition score (0.0-1.0). | |
| filter[keyword_count][from] | No | Minimum number of words in the keyword. | |
| filter[keyword_count][to] | No | Maximum number of words in the keyword. | |
| filter[characters_count][from] | No | Minimum character length of the keyword. | |
| filter[characters_count][to] | No | Maximum character length of the keyword. | |
| filter[serp_features] | No | Comma-separated list of SERP features to filter by. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only mentions the API endpoint. It fails to disclose pagination, rate limits, data freshness, or what 'related' means behaviorally.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
While brief, the description is undersized for the complexity (20 params). It lacks front-loaded details and reads as a tautology of the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is completely inadequate for a tool with 20 parameters, no output schema, and no annotations. It does not explain return structure, pagination, or the meaning of 'related'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no parameter-level meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch related keywords' clearly states the action and resource. However, it does not differentiate from sibling tools like keywordsSimilar or keywordsLongtail, which may overlap in concept.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives. The description simply states what it does without context for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch similar keywords from SE Ranking Data API (v1/keywords/similar)
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Alpha-2 country code of the regional keyword database. | |
| keyword | Yes | The seed keyword for which to find similar keywords. | |
| limit | No | Maximum number of keywords to return per page. | |
| offset | No | Starting offset for pagination. | |
| sort | No | The field by which the returned list of keywords should be sorted. | |
| sort_order | No | The order of sorting for the sort field. | desc |
| history_trend | No | Whether to include historical search volume trend data in the response. | |
| filter[volume][from] | No | Minimum monthly search volume. | |
| filter[volume][to] | No | Maximum monthly search volume. | |
| filter[difficulty][from] | No | Minimum keyword difficulty score (0-100). | |
| filter[difficulty][to] | No | Maximum keyword difficulty score (0-100). | |
| filter[cpc][from] | No | Minimum Cost Per Click. | |
| filter[cpc][to] | No | Maximum Cost Per Click. | |
| filter[competition][from] | No | Minimum competition score (0.0-1.0). | |
| filter[competition][to] | No | Maximum competition score (0.0-1.0). | |
| filter[keyword_count][from] | No | Minimum number of words in the keyword. | |
| filter[keyword_count][to] | No | Maximum number of words in the keyword. | |
| filter[characters_count][from] | No | Minimum character length of the keyword. | |
| filter[characters_count][to] | No | Maximum character length of the keyword. | |
| filter[serp_features] | No | Comma-separated list of SERP features to filter by. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states the core action and endpoint. It does not disclose behavioral traits such as pagination behavior, rate limits, response structure, or any side effects. Since no annotations are provided, the description carries the full burden and fails to address these.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief (one sentence) and could be more informative without becoming verbose. It sacrifices valuable context for brevity, but it is not overly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 20 parameters and no output schema, the description is insufficiently complete. It should explain what 'similar' means, how pagination works, and what the response contains. The current description leaves significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 20 parameters, so the schema already explains each parameter. The tool description adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches similar keywords from a specific API endpoint. However, it does not differentiate 'similar' from sibling tools like 'keywordsRelated' or 'keywordsLongtail', which could cause confusion about when to use this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus its siblings. There is no mention of prerequisites, context, or exclusions, leaving the agent to infer when 'similar' is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0aiSearchOverviewaiSearchPromptsByBrandaiSearchPromptsByTargetbacklinksAllbacklinksAnchorsbacklinksAuthoritybacklinksIndexedPagesbacklinksRefdomainsbacklinksSummarydomainAdsByDomaindomainAdsByKeyworddomainAioDiscoverBranddomainAioKeywordsByBranddomainAioKeywordsByTargetdomainAioOverviewdomainCompetitorsdomainKeywordsdomainKeywordsComparisondomainKeywordsReverseComparisondomainOverviewdomainOverviewDbdomainOverviewHistorydomainOverviewWorldwidekeywordsExportkeywordsLongtailkeywordsQuestionskeywordsRelatedkeywordsSimilarTools are grouped by clear prefixes (aiSearch, backlinks, domain, keywords), making their purposes generally distinct. However, minor overlap exists within domain overview variants and keyword-related tools, and 'domainKeywordsComparison' vs 'domainKeywordsReverseComparison' may cause confusion.
The naming follows a consistent camelCase pattern with category prefixes. Most tools are well-structured, though a few, like 'domainKeywordsReverseComparison', break the typical verb-noun pattern slightly.
With 28 tools, the set is slightly larger than ideal but still well-scoped for a comprehensive SEO data API covering multiple subdomains. Each tool serves a specific function, and no tool appears redundant.
The toolset covers a wide range of SEO data retrieval tasks, including AI search, backlinks, domain analysis, and keywords. However, it lacks write operations (e.g., create, update) and some advanced backlink analysis tools, leaving minor gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Query your SEO data in plain language: rankings, audits, backlinks, competitors and AI visibility.
SE Ranking SEO: keywords, backlinks, domains, SERP, audits, rank tracking, AI Search visibility.
Real SEO data for AI assistants: page audits, Keyword Planner volumes, Search Console history.
SEO research, audits, backlinks, GSC, and content workflow tools for AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Teake1404/seo-data-api-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
