Skip to main content
Glama
dataforseo

DataForSEO MCP Server

Official
by dataforseo
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

DataForSEO MCP Server

⚠️ Deprecated: This version of the DataForSEO MCP server is deprecated and will no longer be maintained.

It covers versions up to V2.x, available on npm, Docker, or remotely at https://mcp.dataforseo.com/mcp, and has been moved out of the main project into a separate repository.

New, actively supported version: dataforseo/mcp-server-typescript.

Model Context Protocol (MCP) server implementation for DataForSEO, enabling AI assistants to interact with selected DataForSEO APIs and obtain SEO data through a standardized interface.

Features

  • AI_OPTIMIZATION API: provides data for keyword discovery, conversational optimization, and real-time LLM benchmarking;

  • SERP API: real-time Search Engine Results Page (SERP) data for Google, Bing, and Yahoo;

  • KEYWORDS_DATA API: keyword research and clickstream data, including search volume, cost-per-click, and other metrics;

  • ONPAGE API: allows crawling websites and webpages according to customizable parameters to obtain on-page SEO performance metrics;

  • DATAFORSEO LABS API: data on keywords, SERPs, and domains based on DataForSEO's in-house databases and proprietary algorithms;

  • BACKLINKS API: comprehensive backlink analysis including referring domains, anchor text distribution, and link quality metrics;

  • BUSINESS DATA API: publicly available data on any business entity;

  • DOMAIN ANALYTICS API: data on website traffic, technologies, and Whois details;

  • CONTENT ANALYSIS API: robust source of data for brand monitoring, sentiment analysis, and citation management;

  • MERCHANT API: provides essential data and metrics for comprehensive competitor analysis, price monitoring, and market research across Google Shopping, Amazon etc.

Related MCP server: DataForSEO MCP Server

Prerequisites

  • Node.js (v14 or higher)

  • DataForSEO API credentials (API login and password)

Installation

  1. Clone the repository:

git clone https://github.com/dataforseo/mcp-server-typescript
cd mcp-server-typescript

  1. Install dependencies:

npm install

  1. Set up environment variables:

# Required
export DATAFORSEO_USERNAME=your_username
export DATAFORSEO_PASSWORD=your_password

# Optional: specify which modules to enable (comma-separated)
# If not set, all modules will be enabled
export ENABLED_MODULES="SERP,KEYWORDS_DATA,ONPAGE,DATAFORSEO_LABS,BACKLINKS,BUSINESS_DATA,DOMAIN_ANALYTICS"

# Optional: specify which prompts in enabled modules are enable too (prompts names, comma-separated)
# If not set, all prompts from enabled modules will be enabled
export ENABLED_PROMPTS="top_3_google_result_domains,top_5_serp_paid_and_organic"

# Optional: enable full API responses
# If not set or set to false, the server will filter and transform API responses to a more concise format
# If set to true, the server will return the full, unmodified API responses
export DATAFORSEO_FULL_RESPONSE="false"

# Optional: enable simple filter schema
# If set to true, a simplified version of the filters schema will be used.
# This is required for ChatGPT APIs or other LLMs that cannot handle nested structures.
export DATAFORSEO_SIMPLE_FILTER="false"

Installation as an NPM Package

You can install the package globally:

npm install -g dataforseo-mcp-server@latest

Or run it directly without installation:

npx dataforseo-mcp-server@latest

Remember to set environment variables before running the command:

# Required environment variables
export DATAFORSEO_USERNAME=your_username
export DATAFORSEO_PASSWORD=your_password

# Run with npx
npx dataforseo-mcp-server@latest

Building and Running

Build the project:

npm run build

Run the server:

# Start local server (direct MCP communication)
npx dataforseo-mcp-server@latest

# Start HTTP server
npx dataforseo-mcp-server@latest http

HTTP Server Configuration

The server runs on port 3000 by default and supports both Basic Authentication and environment variable-based authentication.

To start the HTTP server, run:

npm run http

Authentication Methods

  1. Basic Authentication

    • Send requests with Basic Auth header:

    Authorization: Basic <base64-encoded-credentials>

    • Credentials format: username:password

  2. Environment Variables

    • If no Basic Auth is provided, the server will use credentials from environment variables:

    export DATAFORSEO_USERNAME=your_username
export DATAFORSEO_PASSWORD=your_password
# Optional
export DATAFORSEO_SIMPLE_FILTER="false"
export DATAFORSEO_FULL_RESPONSE="true"

Cloudflare Worker Deployment

The DataForSEO MCP Server can be deployed as a Cloudflare Worker for serverless, edge-distributed access to DataForSEO APIs.

Worker Features

  • Edge Distribution: Deploy globally across Cloudflare's edge network

  • Serverless: No server management required

  • Auto-scaling: Handles traffic spikes automatically

  • MCP Protocol Support: Compatible with both Streamable HTTP and SSE transports

  • Environment Variables: Secure credential management through Cloudflare dashboard

Quick Start

  1. Install Wrangler CLI:

    npm install -g wrangler

  2. Configure Worker:

    # Login to Cloudflare
wrangler login

# Set environment variables
wrangler secret put DATAFORSEO_USERNAME
wrangler secret put DATAFORSEO_PASSWORD

  3. Deploy Worker:

    # Build and deploy
npm run build
wrangler deploy --main build/index-worker.js

Configuration

The worker uses the same environment variables as the standard server:

  • DATAFORSEO_USERNAME: Your DataForSEO username

  • DATAFORSEO_PASSWORD: Your DataForSEO password

  • ENABLED_MODULES: Comma-separated list of modules to enable

  • ENABLED_PROMPTS: Comma-separated list of prompt names to enable

  • DATAFORSEO_FULL_RESPONSE: Set to "true" for full API responses

Worker Endpoints

Once deployed, your worker will be available at https://your-worker.your-subdomain.workers.dev/ with the following endpoints:

  • POST /mcp: Streamable HTTP transport (recommended)

  • GET /sse: SSE connection establishment (deprecated)

  • POST /messages: SSE message handling (deprecated)

  • GET /health: Health check endpoint

  • GET /: API documentation page

Advanced Configuration

Edit wrangler.jsonc to customize your deployment:

{
  "name": "dataforseo-mcp-worker",
  "main": "build/index-worker.js",
  "compatibility_date": "2025-07-10",
  "compatibility_flags": ["nodejs_compat"],
  "vars": {
    "ENABLED_MODULES": "SERP,KEYWORDS_DATA,ONPAGE,DATAFORSEO_LABS",
    "ENABLED_PROMPTS":"top_3_google_result_domains,top_5_serp_paid_and_organic"
  }
}

Usage with Claude

After deployment, configure Claude to use your worker:

{
  "name": "DataForSEO",
  "description": "Access DataForSEO APIs via Cloudflare Worker",
  "transport": {
    "type": "http",
    "baseUrl": "https://your-worker.your-subdomain.workers.dev/mcp"
  }
}

Available Modules

The following modules are available to be enabled/disabled:

  • AI_OPTIMIZATION: provides data for keyword discovery, conversational optimization, and real-time LLM benchmarking;

  • SERP: real-time SERP data for Google, Bing, and Yahoo;

  • KEYWORDS_DATA: keyword research and clickstream data;

  • ONPAGE: crawl websites and webpages to obtain on-page SEO performance metrics;

  • DATAFORSEO_LABS: data on keywords, SERPs, and domains based on DataForSEO's databases and algorithms;

  • BACKLINKS: data on inbound links, referring domains and referring pages for any domain, subdomain, or webpage;

  • BUSINESS_DATA: based on business reviews and business information publicly shared on the following platforms: Google, Trustpilot, Tripadvisor;

  • DOMAIN_ANALYTICS: helps identify all possible technologies used for building websites and offers Whois data;

  • CONTENT_ANALYSIS: help you discover citations of the target keyword or brand and analyze the sentiments around it;

  • MERCHANT: helps retrieve product data, prices, and seller information from Google Shopping and Amazon etc.;

Adding New Tools/Modules

Module Structure

Each module corresponds to a specific DataForSEO API:

Implementation Options

You can either:

  1. Add a new tool to an existing module

  2. Create a completely new module

Adding a New Tool

Here's how to add a new tool to any new or pre-existing module:

// src/code/modules/your-module/tools/your-tool.tool.ts
import { BaseTool } from '../../base.tool';
import { DataForSEOClient } from '../../../client/dataforseo.client';
import { z } from 'zod';

export class YourTool extends BaseTool {
  constructor(private client: DataForSEOClient) {
    super(client);
    // DataForSEO API returns extensive data with many fields, which can be overwhelming
    // for AI agents to process. We select only the most relevant fields to ensure
    // efficient and focused responses.
    this.fields = [
      'title',           // Example: Include the title field
      'description',     // Example: Include the description field
      'url',            // Example: Include the URL field
      // Add more fields as needed
    ];
  }

  getName() {
    return 'your-tool-name';
  }

  getDescription() {
    return 'Description of what your tool does';
  }

  getParams(): z.ZodRawShape {
    return {
      // Required parameters
      keyword: z.string().describe('The keyword to search for'),
      location: z.string().describe('Location in format "City,Region,Country" or just "Country"'),
      
      // Optional parameters
      fields: z.array(z.string()).optional().describe('Specific fields to return in the response. If not specified, all fields will be returned'),
      language: z.string().optional().describe('Language code (e.g., "en")'),
    };
  }

  async handle(params: any) {
    try {
      // Make the API call
      const response = await this.client.makeRequest({
        endpoint: '/v3/dataforseo_endpoint_path',
        method: 'POST',
        body: [{
          // Your request parameters
          keyword: params.keyword,
          location: params.location,
          language: params.language,
        }],
      });

      // Validate the response for errors
      this.validateResponse(response);

      //if the main data array is specified in tasks[0].result[:] field
      const result = this.handleDirectResult(response);
      //if main data array specified in tasks[0].result[0].items field
      const result = this.handleItemsResult(response);
      // Format and return the response
      return this.formatResponse(result);
    } catch (error) {
      // Handle and format any errors
      return this.formatErrorResponse(error);
    }
  }
}

Creating a New Module

  1. Create a new directory under src/core/modules/ for your module:

mkdir -p src/core/modules/your-module-name

  1. Create module files:

// src/core/modules/your-module-name/your-module-name.module.ts
import { BaseModule } from '../base.module';
import { DataForSEOClient } from '../../client/dataforseo.client';
import { YourTool } from './tools/your-tool.tool';

export class YourModuleNameModule extends BaseModule {
  constructor(private client: DataForSEOClient) {
    super();
  }

  getTools() {
    return {
      'your-tool-name': new YourTool(this.client),
    };
  }
}

  1. Register your module in src/core/config/modules.config.ts:

export const AVAILABLE_MODULES = [
  'SERP',
  'KEYWORDS_DATA',
  'ONPAGE',
  'DATAFORSEO_LABS',
  'BACKLINKS',
  'BUSINESS_DATA',
  'DOMAIN_ANALYTICS',
  'CONTENT_ANALYSIS',
  'YOUR_MODULE_NAME'  // Add your module name here
] as const;

  1. Initialize your module in src/main/index.ts:

if (isModuleEnabled('YOUR_MODULE_NAME', enabledModules)) {
  modules.push(new YourModuleNameModule(dataForSEOClient));
}

Field Configuration

The MCP server supports field filtering to customize which data fields are returned in API responses. This helps reduce response size and focus on the most relevant data for your use case.

Configuration File Format

Create a JSON configuration file with the following structure:

{
  "supported_fields": {
    "tool_name": ["field1", "field2", "field3"],
    "another_tool": ["field1", "field2"]
  }
}

Using Field Configuration

Pass the configuration file using the --configuration parameter:

# With npm
npm run cli -- http --configuration field-config.json

# With npx
npx dataforseo-mcp-server@latest http --configuration field-config.json

# Local mode
npx dataforseo-mcp-server@latest local --configuration field-config.json

Configuration Behavior

  • If a tool is configured: Only the specified fields will be returned in the response

  • If a tool is not configured: All available fields will be returned (default behavior)

  • If no configuration file is provided: All tools return all available fields

Example Configuration File

The repository includes an example configuration file field-config.example.json with optimized field selections for common tools:

{
  "supported_fields": {
    "backlinks_backlinks": [
      "id",
      "items.anchor",
      "items.backlink_spam_score",
      "items.dofollow",
      "items.domain_from",
      "items.domain_from_country",
      "items.domain_from_ip",
      "items.domain_from_platform_type",
      "items.domain_from_rank",
      "items.domain_to",
      "items.first_seen",
      "items.is_broken",
      "items.is_new",
      "items.item_type",
      "items.last_seen",
      "items.links_count",
      "items.original",
      "items.page_from_encoding",
      "items.page_from_external_links",
      "items.page_from_internal_links",
      "items.page_from_language",
      "items.page_from_rank",
      "items.page_from_size",
      "items.page_from_status_code",
      "items.page_from_title",
      "items.prev_seen",
      "items.rank",
      "items.ranked_keywords_info.page_from_keywords_count_top_10",
      "items.ranked_keywords_info.page_from_keywords_count_top_100",
      "items.ranked_keywords_info.page_from_keywords_count_top_3",
      "items.semantic_location",
      "items.text_post",
      "items.text_pre",
      "items.tld_from",
      "items.type",
      "items.url_from",
      "items.url_from_https",
      "items.url_to",
      "items.url_to_https",
      "items.url_to_spam_score",
      "items.url_to_status_code",
      "status_code",
      "status_message"
    ],
    ...
  }
}

Nested Field Support

The configuration supports nested field paths using dot notation:

  • "rating.value" - Access the value field within the rating object

  • "items.demography.age.keyword" - Access deeply nested fields

  • "meta.description" - Access nested object properties

Field Discovery

To discover available fields for any tool:

  1. Run the tool without field configuration to see the full response

  2. Identify the fields you need from the API response

  3. Add those field paths to your configuration file

Creating Your Own Configuration

  1. Copy the example file:

cp field-config.example.json my-config.json

  1. Modify the field selections based on your needs

  2. Use your custom configuration:

npx dataforseo-mcp-server@latest http --configuration my-config.json

What endpoints/APIs do you want us to support next?

We're always looking to expand the capabilities of this MCP server. If you have specific DataForSEO endpoints or APIs you'd like to see supported, please:

  1. Check the DataForSEO API Documentation to see what's available

  2. Open an issue in our GitHub repository with:

    • The API/endpoint you'd like to see supported;

    • A brief description of your use case;

    • Describe any specific features you'd like to see implemented.

Your feedback helps us prioritize which APIs to support next!

Resources

Available Tools

89 tools
ai_optimization_chat_gpt_scraperAI Optimization Chat GPT ScraperC
Read-onlyIdempotent

This endpoint provides results from ChatGPT searches

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordYeskeyword required field you can specify up to 2000 characters in the keyword field all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your keyword, please specify it as “%25”; if you need to use the “+” character for your keyword, please specify it as “%2B”
language_codeYesSearch engine language code (e.g., 'en')
location_nameNofull name of the location, example: 'United Kingdom', 'United States'United States
force_web_searchNoforce AI agent to use web search

TDQS

C2.7/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds no additional behavioral insights (e.g., rate limits, authentication, data freshness), nor does it contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence, which is concise but lacks substance. It front-loads the purpose but could be more informative without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should explain the nature of the results (e.g., JSON structure, fields). It does not. Additionally, the purpose of parameters like force_web_search and location_name is not addressed in the description, leaving gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers 100% of parameters with descriptions. The description does not add any extra meaning beyond the schema, but the schema itself is sufficient. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool provides results from ChatGPT searches, which gives a general idea. However, it is vague about what kind of results (e.g., search result snippets, full responses) and does not differentiate it from sibling tools like ai_optimization_llm_response that also involve LLM outputs.

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

Usage Guidelines2/5

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

There is no guidance on when to use this tool versus alternatives. No context about prerequisites, typical use cases, or scenarios where other tools would be preferred.

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

ai_optimization_chat_gpt_scraper_locationsAI Optimization Chat GPT Scraper LocationsA
Read-onlyIdempotent

Utility tool for ai_optimization_chat_gpt_scraper to get list of available locations

ParametersJSON Schema
NameRequiredDescriptionDefault
location_nameNoName of location or it`s part.
country_iso_codeNoISO 3166-1 alpha-2 country code, for example: US, GB, MT

TDQS

A3.8/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it's a 'utility tool' but does not disclose any additional behavioral traits beyond what annotations provide. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no redundancy, front-loaded with purpose. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low complexity, informative annotations, and complete parameter descriptions, the description is sufficient for agent understanding. However, lacking an output schema, a brief note on return format would improve completeness. Score reflects minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters have descriptions. The description does not add any additional meaning or context for using the parameters (e.g., how they filter or format results). Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool is for getting a list of available locations, specifically for the ai_optimization_chat_gpt_scraper. It distinguishes itself from sibling location tools by associating with a specific parent scraper.

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

Usage Guidelines3/5

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

Implies usage context (as a utility for the scraper) but provides no explicit guidance on when to use this vs. alternative location-oriented tools like serp_locations or kw_data_google_ads_locations. No when-not or exclusions are mentioned.

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

ai_optimization_keyword_data_search_volumeAI Optimization Keyword Data Search VolumeA
Read-onlyIdempotent

This endpoint provides search volume data for your target keywords, reflecting their estimated usage in AI LLMs

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordsYesKeywords. The maximum number of keywords you can specify: 1000
language_codeYesSearch engine language code (e.g., 'en')
location_nameNofull name of the location, example: 'United Kingdom', 'United States'United States

TDQS

A3.7/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds that data is 'estimated usage in AI LLMs', which is useful but not extensive. No additional behavioral traits are disclosed beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that conveys the core functionality without fluff. It is front-loaded and every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description does not explain the return format, pagination, or provide examples. Annotations are rich, but the description alone leaves gaps in understanding the full context of usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all parameters are already documented. The description does not add significant extra meaning beyond the schema. The mention of 'target keywords' is generic.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The tool name, title, and description clearly state its function: providing search volume data for keywords in AI LLMs. The description specifies the resource (search volume data) and context (AI LLMs), distinguishing it from sibling tools like kw_data_google_ads_search_volume.

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

Usage Guidelines3/5

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

The description gives a clear purpose but no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, limitations, or use cases where other tools might be more appropriate.

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

ai_optimization_llm_mentions_filtersAI Optimization LLM Mentions FiltersA
Read-onlyIdempotent

This endpoint provides all the necessary information about filters that can be used with AI Optimization LLM Mentions API endpoints

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's claim of providing 'all the necessary information about filters' adds useful context without contradiction. The tool is safe and informational.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that effectively communicates the tool's purpose with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the description states it provides 'all necessary information about filters,' it lacks specifics about the format or structure of that information. Given there is no output schema, more detail would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, and schema coverage is 100%, so the baseline score is 4. The description does not need to add parameter information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that this endpoint provides information about filters for AI Optimization LLM Mentions API endpoints, distinguishing it from sibling tools like backlinks_available_filters and other AI optimization endpoints.

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

Usage Guidelines3/5

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

The description implies that this tool should be used to discover available filters for the AI Optimization LLM Mentions endpoints, but it does not explicitly state when to use it versus alternatives or provide any when-not-to-use guidance.

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

ai_optimization_llm_modelsAI Optimization LLM ModelsB
Read-onlyIdempotent

Utility tool for ai_optimization_llm_response to get list of availible locations and languages

ParametersJSON Schema
NameRequiredDescriptionDefault
llm_typeYestype of llm. Must be one of: 'claude', 'gemini', 'chat_gpt', 'perplexity'

TDQS

B3.2/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds that the tool returns a list, but does not disclose additional behavioral traits such as rate limits, authentication needs, or whether the list is exhaustive. With annotations covering safety, the description adds limited new value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 10 words, very concise. It front-loads the utility purpose. However, there is a minor typo ('availible' instead of 'available'), and the structure could be slightly clearer.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple one-parameter tool and existing annotations, the description provides acceptable context for basic usage. However, it does not describe the output format, whether the list is exhaustive or paginated, or any edge cases. For a listing tool, slightly more detail would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage for the single parameter 'llm_type' is 100% because its description includes the allowed values. The tool description adds no extra meaning beyond the schema, so baseline score is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves a list of available locations and languages for the ai_optimization_llm_response tool. The verb 'get list' and the resource 'availible locations and languages' are specific, though the title is vague. It distinguishes from sibling location tools by explicitly linking to the LLM response context.

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

Usage Guidelines2/5

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

The description indirectly suggests it is a utility for ai_optimization_llm_response, but does not explicitly state when to use this tool versus alternatives like ai_opt_kw_data_loc_and_lang or serp_locations. No exclusions or conditions are provided.

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

ai_optimization_llm_responseAI Optimization LLM ResponseC
Read-onlyIdempotent

This endpoint allows you to retrieve structured responses from a specific AI model, based on the input parameters

ParametersJSON Schema
NameRequiredDescriptionDefault
top_pNodiversity of the AI response, optional field, controls diversity of the response by limiting token selection;
llm_typeYestype of llm. Must be one of: 'claude', 'gemini', 'chat_gpt', 'perplexity'
model_nameYesname of the AI model. consists of the actual model name and version name. if not sure which model to use, first call the ai_optimization_llm_models tool to get list of available models for the specified llm_type
web_searchNoenable web search for current information. When enabled, the AI model can access and cite current web information;
temperatureNorandomness of the AI response optional field higher values make output more diverse; lower values make output more focused;
user_promptYesPrompt for the AI model. The question or task you want to send to the AI model. You can specify up to 500 characters in the user_prompt field

TDQS

C2.9/5.0
Behavior2/5

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no additional behavioral context beyond 'retrieve', so value added is minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no redundancy. Efficiently conveys the core purpose without wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description does not specify the structure or content of the returned response. For a tool with 6 parameters, more context on return format is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters with descriptions. The overall description does not enhance parameter meaning beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves structured responses from a specific AI model based on input parameters. While not explicitly distinguishing from siblings, the purpose is specific and actionable.

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

Usage Guidelines2/5

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. The only hint is in the parameter 'model_name' description referencing a sibling tool, but the main description lacks usage context.

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

ai_opt_kw_data_loc_and_langAI Optimization Keywords Data Locations and LanguagesB
Read-onlyIdempotent

Utility tool for 'AI Optimization Keyword Data Locations and Languages' (ai_opt_kw_data_loc_and_lang) to get list of availible locations and languages

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior3/5

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which inform safety and idempotency. The description adds 'utility tool' and 'get list', which aligns with these hints but does not provide additional behavioral detail (e.g., response format, rate limits, or side effects). With annotations present, the description fulfills a minimal role but could add value by noting that the list is static or cacheable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence but contains redundancy: it repeats the full tool name and title verbatim. It could be condensed to 'Retrieves a list of available locations and languages for AI Optimization Keyword Data.' The typo 'availible' also detracts from quality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (no parameters, no output schema), so the description is largely adequate. However, it does not explain how the returned list is structured or which tools it is meant to support (e.g., ai_optimization_keyword_data_search_volume). Adding a note about use with other AI Optimization tools would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema documentation coverage is 100% (since there are no properties to document). The description does not need to elaborate on parameters, and it correctly implies no input is required. For a no-parameter tool, this is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a list of available locations and languages for AI Optimization Keyword Data. It specifies the verb 'get' and the resource 'list of available locations and languages', making the purpose unambiguous. However, it does not explicitly distinguish itself from sibling location tools like ai_opt_llm_ment_loc_and_lang or serp_locations, though the 'AI Optimization Keywords' context provides implicit differentiation.

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

Usage Guidelines2/5

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. It does not mention prerequisites, typical use cases, or when it should not be used. Given the number of sibling tools with overlapping functionality (e.g., ai_opt_llm_ment_loc_and_lang, serp_locations), explicit usage context is needed.

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

ai_opt_llm_ment_agg_metricsAI Optimization LLM Mentions Aggregated MetricsB
Read-onlyIdempotent

This endpoint provides aggregated metrics for mentions of the keywords or domains specified in the target array of the request.

ParametersJSON Schema
NameRequiredDescriptionDefault
targetYesArray of target objects to search for LLM mentions. Each object must contain either 'domain' or 'keyword'. Maximum number of targets: 1000
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like Use % with like/not_like/ilike/not_ilike as a wildcard. Example: Single: ["ai_search_volume", ">", "1000"] The full list of possible filters is available in 'ai_optimization_llm_mentions_filters' tool
platformNoPlatform to search for LLM mentions
language_codeNoSearch engine language code (e.g., 'en')
location_nameNofull name of the location, example: 'United Kingdom', 'United States'
internal_list_limitNoInternal parameter to limit the number of items processed. Not exposed to end-users.

TDQS

B3.1/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds minimal transparency beyond 'aggregated metrics', e.g., no mention of rate limits, pagination, or handling of large target arrays (max 1000 in schema). Adequate given annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single efficient sentence that conveys the core function. No fluff, but could be slightly more structured (e.g., breaking out key details). Still above average.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Lacks critical context about the output format or content of aggregated metrics (e.g., counts, trends). No output schema and no explanation, leaving the agent uncertain about what to expect. Incomplete for a tool with six parameters and no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all parameters. The description restates that the target array contains keywords/domains but adds no new semantic meaning beyond what's in the schema. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides aggregated metrics for mentions of specified keywords or domains. This is specific and distinct from raw mention retrieval or cross-aggregation, but does not explicitly differentiate from sibling tools like ai_opt_llm_ment_search or ai_opt_llm_ment_cross_agg_metrics.

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

Usage Guidelines2/5

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. The description only explains what it does, not when it should be preferred (e.g., for summary statistics vs. raw data) or when not to use it.

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

ai_opt_llm_ment_cross_agg_metricsAI Optimization LLM Mentions Cross Aggregated MetricsB
Read-onlyIdempotent

This endpoint provides aggregated metrics grouped by custom keys for mentions of the keywords or domains specified in the target array of the request

ParametersJSON Schema
NameRequiredDescriptionDefault
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like Use % with like/not_like/ilike/not_ilike as a wildcard. Example: Single: ["ai_search_volume", ">", "1000"] The full list of possible filters is available in 'ai_optimization_llm_mentions_filters' tool
targetsYesarray of objects containing target entities with aggregation keys. you can specify up to 10, but not less than 2
platformNoPlatform to search for LLM mentions
language_codeNoSearch engine language code (e.g., 'en')
location_nameNofull name of the location, example: 'United Kingdom', 'United States'
internal_list_limitNoInternal parameter to limit the number of items processed. Not exposed to end-users.

TDQS

B3.1/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior. The description adds that it aggregates metrics and groups by keys, which is consistent but does not disclose additional behavioral traits like limits on number of targets (though schema shows max 10) or rate limits. It provides moderate transparency, aligning with annotations without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that efficiently conveys the core functionality. It avoids redundancy and is appropriately front-loaded. However, it could be slightly more informative without adding much length, so it earns a 4 rather than a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (nested parameters, multiple siblings, no output schema), the description is too minimal. It does not clarify what 'aggregated metrics' includes (e.g., counts, volumes), how grouping works, or that at least 2 targets are required (though schema says 'not less than 2'). The agent lacks sufficient context to confidently invoke the tool without additional exploration.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description does not add meaningful semantics beyond what the schema already provides for parameters like 'targets', 'aggregation_key', or 'filters'. It mentions 'keywords or domains' which corresponds to the target parameter, but no extra detail. Thus, no significant added value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool provides aggregated metrics grouped by custom keys for LLM mentions. The verb 'provides' is somewhat generic, but it specifies the resource (aggregated metrics) and scope (based on targets). The name and description distinguish it from siblings like 'ai_opt_llm_ment_agg_metrics' by emphasizing 'cross' and 'custom keys' grouping.

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

Usage Guidelines2/5

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

The description does not provide any guidance on when to use this tool versus alternatives. It lacks explicit when-not scenarios or references to sibling tools. Users must infer from the name and schema, but no rationale is given for selecting this over similar tools like 'ai_opt_llm_ment_agg_metrics' or 'ai_opt_llm_ment_search'.

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

ai_opt_llm_ment_loc_and_langAI Optimization LLM Mentions Locations and LanguagesB
Read-onlyIdempotent

Utility tool for 'AI Optimization LLM Mentions Locations and Languages' (ai_opt_llm_ment_loc_and_lang) to get list of available locations and languages

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.3/5.0
Behavior3/5

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds basic purpose but no additional behavioral details (e.g., output format, pagination, or error states). It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that front-loads 'Utility tool' and states the action. Slightly verbose due to repeating the title and ID, but overall efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and no output schema, the description adequately states what the tool returns. However, it could be more complete by hinting at the output format (e.g., 'list of location codes and language codes') to help the agent understand how to use the results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameters, so schema coverage is 100%. The description adds no parameter info, but baseline for zero-parameter tools is 4. No further meaning needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a list of available locations and languages, with a verb+resource structure. However, it does not differentiate from the similar sibling 'ai_opt_kw_data_loc_and_lang', which likely serves a parallel purpose for keyword data.

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

Usage Guidelines2/5

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

The description labels it as a 'utility tool' but provides no explicit guidance on when to use it versus alternatives like 'ai_opt_kw_data_loc_and_lang'. No contextual cues for selection are given.

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

ai_opt_llm_ment_top_domainsAI Optimization LLM Mentions Top DomainsB
Read-onlyIdempotent

This endpoint provides aggregated LLM mentions metrics grouped by the most frequently mentioned domains for the specified target

ParametersJSON Schema
NameRequiredDescriptionDefault
targetYesArray of target objects to search for LLM mentions. Each object must contain either 'domain' or 'keyword'. Maximum number of targets: 1000
platformNoPlatform to search for LLM mentions
links_scopeNospecifies which links will be used to extract domains and aggregation
language_codeNoSearch engine language code (e.g., 'en')
location_nameNofull name of the location, example: 'United Kingdom', 'United States'
items_list_limitNomaximum number of results in the items array, min value is 1, max value is 10
internal_list_limitNomaximum number of elements within internal arrays, min value is 1, max value is 10
initial_dataset_filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like Use % with like/not_like/ilike/not_ilike as a wildcard. Example: Single: ["ai_search_volume", ">", "1000"] The full list of possible filters is available in 'ai_optimization_llm_mentions_filters' tool

TDQS

B3.3/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that it provides aggregated metrics grouped by domains, which gives context about the output shape but no further behavioral traits (e.g., rate limits, authorization needs). No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 17 words, concise and front-loaded with the main purpose. However, it repeats 'LLM mentions' twice, which could be slightly tighter. Still, it earns its place with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 8 parameters, no output schema, and a nested input structure. The description only explains the grouping logic but does not describe the output format, what the metrics are, or how domains are ranked. Given the complexity, this is insufficient for an agent to fully understand the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 8 parameters are documented in the schema. The description does not add any additional meaning about parameters beyond what is already in the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'provides', resource 'aggregated LLM mentions metrics grouped by most frequently mentioned domains', and specifies it's for 'the specified target'. It distinguishes this tool from siblings like 'ai_opt_llm_ment_search' or 'ai_opt_llm_ment_top_pages' by focusing on domain grouping.

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

Usage Guidelines2/5

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

The description does not provide any guidance on when to use this tool versus alternatives (e.g., 'ai_opt_llm_ment_agg_metrics' or 'ai_opt_llm_ment_top_pages'). No prerequisites, when-not, or exclusion criteria are mentioned, leaving the agent to infer context.

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

ai_opt_llm_ment_top_pagesAI Optimization LLM Mentions Top PagesA
Read-onlyIdempotent

This endpoint provides aggregated LLM mentions metrics grouped by the most frequently mentioned pages for the specified target

ParametersJSON Schema
NameRequiredDescriptionDefault
targetYesArray of target objects to search for LLM mentions. Each object must contain either 'domain' or 'keyword'. Maximum number of targets: 1000
platformNoPlatform to search for LLM mentions
links_scopeNospecifies which links will be used to extract domains and aggregation
language_codeNoSearch engine language code (e.g., 'en')
location_nameNofull name of the location, example: 'United Kingdom', 'United States'
items_list_limitNomaximum number of results in the items array, min value is 1, max value is 10
internal_list_limitNomaximum number of elements within internal arrays, min value is 1, max value is 10
initial_dataset_filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like Use % with like/not_like/ilike/not_ilike as a wildcard. Example: Single: ["ai_search_volume", ">", "1000"] The full list of possible filters is available in 'ai_optimization_llm_mentions_filters' tool

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, so the safety profile is clear. The description adds that the output is aggregated metrics grouped by pages, which is useful but does not disclose other behavioral traits like sorting, pagination, or default limits. It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the core functionality. There is no redundancy or filler, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 8 parameters and nested objects in 'target', and no output schema, the description should provide more detail about the returned metrics. The phrase 'aggregated LLM mentions metrics' is vague; the agent does not know what specific metrics (e.g., count, frequency) are included. This leaves a gap for an effective decision.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so each parameter is already well-described in the input schema. The tool description adds no additional meaning beyond summarizing the tool's purpose. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides aggregated LLM mentions metrics grouped by pages, which is distinct from sibling tools like 'ai_opt_llm_ment_top_domains' that focus on domains. The verb 'provides' and resource 'pages' are specific and unambiguous.

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

Usage Guidelines2/5

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. It does not specify when to choose this over 'ai_opt_llm_ment_top_domains' or other LLM mention tools, leaving the agent without decision-making context.

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

backlinks_page_intersectionBacklinks Page IntersectionA
Read-onlyIdempotent

This endpoint will provide you with the list of domains pointing to the specified websites. This endpoint is especially useful for creating a Link Gap feature that shows what domains link to your competitors but do not link out to your website

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNothe maximum number of returned results
offsetNooffset in the array of returned results optional field default value: 0 if you specify the 10 value, the first ten backlinks in the results array will be omitted and the data will be provided for the successive backlinks
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, =, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_match Use % with like/not_like to match any string of zero or more characters. Examples: Single: ["1.rank",">","80"] Combined: [["2.page_from_rank",">","55"],"and",["1.original","=","true"]]
targetsYesdomains, subdomains or webpages to get links for required field you can set up to 20 domains, subdomains or webpages a domain or a subdomain should be specified without https:// and www. a page should be specified with absolute URL (including http:// or https://)
order_byNoresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["rank,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["domain_from_rank,desc","page_from_rank,asc"]

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds no additional behavioral context beyond the use case, such as rate limits, data freshness, or response structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two concise, front-loaded sentences with no wasted words. It efficiently conveys the core functionality and a key use case.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the detailed schema, annotations, and the simplicity of the tool (listing domains), the description is largely complete. However, it could be slightly improved by clarifying that it performs an intersection of backlinks across multiple targets.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are fully documented. The description does not add any extra meaning beyond what the schema provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns 'the list of domains pointing to the specified websites', indicating the verb and resource. The use case (Link Gap feature) provides context, but it does not explicitly differentiate from the sibling tool 'backlinks_domain_intersection', which likely has a similar purpose.

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

Usage Guidelines3/5

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

The description hints at usage for a Link Gap feature but provides no guidance on when not to use this tool or alternatives. No explicit exclusions or comparisons to similar tools are given.

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

content_analysis_phrase_trendsContent Analysis Phrase TrendsB
Read-onlyIdempotent

This endpoint will provide you with data on all citations of the target keyword for the indicated date range

ParametersJSON Schema
NameRequiredDescriptionDefault
date_toNoending date of the time range date format: "yyyy-mm-dd"
keywordYestarget keyword Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
date_fromYesstarting date of the time range date format: "yyyy-mm-dd"
page_typeNotarget page types
date_groupNodate grouping typemonth
keyword_fieldsNotarget keyword fields and target keywords use this parameter to filter the dataset by keywords that certain fields should contain; you can indicate several fields; Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes; example: { "snippet": "\"logitech mouse\"", "main_title": "sale" }
internal_list_limitNomaximum number of elements within internal arrays you can use this field to limit the number of elements within the following arrays
initial_dataset_filtersNoArray-based initial dataset filter expression applied to Search endpoint fields. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like, has, has_not, match, not_match Use % with like/not_like as a wildcard. Examples: Single: ["domain", "<>", "logitech.com"] Combined: [["domain", "<>", "logitech.com"], "and", ["content_info.connotation_types.negative", ">", 1000]] Nested: [["domain", "<>", "logitech.com"], "and", [["content_info.connotation_types.negative", ">", 1000], "or", ["content_info.text_category", "has", 10994]]]

TDQS

B3.1/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds that it returns 'all citations,' implying a complete dataset without filtering, but does not disclose pagination, rate limits, or output structure. Given strong annotations, the description provides modest additional context but still leaves gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, front-loading the core purpose. It avoids redundancy but could be more streamlined (e.g., remove 'This endpoint will provide you with' – 'Returns citation data...' is tighter). No filler, but not maximally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having 8 parameters (including nested objects) and no output schema, the description does not explain the return format, time-series structure, limits, or typical use cases. For a tool producing trend data, critical information about the response (e.g., array of objects with date and count) is missing, leaving the agent underinformed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The description does not repeat any parameter details or add new semantic meaning. It stays neutral, relying on the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool provides data on citations of a target keyword for a given date range. It uses specific verbs ('provide you with data') and identifies the resource ('citations of the target keyword'). However, it does not explicitly mention 'trends' or time-series output, nor does it distinguish itself from sibling tools like content_analysis_search or content_analysis_summary, though the date range implies temporal aggregation.

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

Usage Guidelines2/5

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. It does not mention prerequisites, limitations, or situations where other tools (e.g., content_analysis_search for raw citations, dataforseo_labs_google_keyword_suggestions for suggestions) might be more appropriate. The agent receives no context for selection.

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

content_analysis_searchContent Analysis SearchC
Read-onlyIdempotent

This endpoint will provide you with detailed citation data available for the target keyword

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNomaximum number of results to return
offsetNooffset in the results array of returned keywords
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like, match, not_match Use % with like/not_like as a wildcard. Examples: Single: ["country", "=", "US"] Combined: [["domain_rank", ">", 800], "and", ["content_info.connotation_types.negative", ">", 0.9]] Nested: [["domain_rank", ">", 800], "and", [["page_types", "has", "ecommerce"], "or", ["content_info.text_category", "has", 10994]]]
keywordYestarget keyword Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
order_byNoresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["content_info.sentiment_connotations.anger,desc"] default rule: ["content_info.sentiment_connotations.anger,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["content_info.sentiment_connotations.anger,desc","keyword_data.keyword_info.cpc,desc"]
page_typeNotarget page types
search_modeNoresults grouping type
keyword_fieldsNotarget keyword fields and target keywords use this parameter to filter the dataset by keywords that certain fields should contain; you can indicate several fields; Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes; example: { "snippet": "\"logitech mouse\"", "main_title": "sale" }

TDQS

C2.5/5.0
Behavior2/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which the description does not reinforce or contradict. The description adds only the phrase 'citation data', which is too vague to provide meaningful behavioral insight beyond what annotations and schema cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, but it is too vague to be efficient. It lacks essential detail, making it less helpful despite being short.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 8 parameters, required keyword, no output schema, and complex nested filters, the description fails to explain what the tool returns or how the output relates to the input. The phrase 'citation data' is insufficient for an agent to understand the tool's behavior or result format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The description adds no extra parameter context, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description says 'detailed citation data available for the target keyword', but 'citation data' is vague and doesn't clearly distinguish the tool from siblings like serp_organic_live_advanced or dataforseo_labs_google_keyword_suggestions. A more specific verb and resource would improve clarity.

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

Usage Guidelines2/5

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. Among many sibling tools for keyword and content analysis, the description offers no context for selection, 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.

content_analysis_summaryContent Analysis SummaryC
Read-onlyIdempotent

This endpoint will provide you with an overview of citation data available for the target keyword

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordYestarget keyword Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes;
page_typeNotarget page types
keyword_fieldsNotarget keyword fields and target keywords use this parameter to filter the dataset by keywords that certain fields should contain; you can indicate several fields; Note: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes; example: { "snippet": "\"logitech mouse\"", "main_title": "sale" }
internal_list_limitNomaximum number of elements within internal arrays you can use this field to limit the number of elements within the following arrays
initial_dataset_filtersNoArray-based initial dataset filter expression applied to Search endpoint fields. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like, has, has_not, match, not_match Use % with like/not_like as a wildcard. Examples: Single: ["domain", "<>", "logitech.com"] Combined: [["domain", "<>", "logitech.com"], "and", ["content_info.connotation_types.negative", ">", 1000]] Nested: [["domain", "<>", "logitech.com"], "and", [["content_info.connotation_types.negative", ">", 1000], "or", ["content_info.text_category", "has", 10994]]]
positive_connotation_thresholdNopositive connotation threshold specified as the probability index threshold for positive sentiment related to the citation content if you specify this field, connotation_types object in the response will only contain data on citations with positive sentiment probability more than or equal to the specified value
sentiments_connotation_thresholdNosentiment connotation threshold specified as the probability index threshold for sentiment connotations related to the citation content if you specify this field, sentiment_connotations object in the response will only contain data on citations where the probability per each sentiment is more than or equal to the specified value

TDQS

C2.9/5.0
Behavior2/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds only that it provides an 'overview', which is vague and does not disclose any behavioral traits beyond annotations (e.g., limits on data scope, aggregation behavior, or response structure). Given the annotations are present, the description should add context like 'returns aggregated counts' or 'limits per keyword' but does not.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the purpose. It is concise without extraneous information. However, it could benefit from a brief note on output or usage without becoming lengthy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 7 parameters including nested objects, no output schema, and is part of a complex domain (content analysis). The description is too brief to cover what the overview entails (e.g., what metrics, how citations are counted, pagination). An agent needs more context to understand the output or constraints, especially given the lack of output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the input schema already documents all 7 parameters with descriptions. The tool description itself does not elaborate on parameter semantics beyond the schema. According to the rubric, baseline is 3 when schema coverage is high. No additional value added by the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides an 'overview of citation data' for a target keyword, specifying the verb (provide overview) and resource (citation data). It distinguishes it from sibling tools like content_analysis_search (which likely returns raw data) and content_analysis_phrase_trends (which tracks trends). However, it could be more specific about the nature of the overview.

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

Usage Guidelines2/5

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 over siblings such as content_analysis_search or other keyword-related tools. There is no mention of prerequisites, limitations, or alternatives, leaving the agent without context to make an informed choice.

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

dataforseo_labs_amazon_bulk_search_volumeDataForSEO Labs Amazon Bulk Search VolumeA
Read-onlyIdempotent

This endpoint will provide you with search volume values for a maximum of 1,000 keywords in one API request. Search volume represents the approximate number of monthly searches for a keyword on Amazon.

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordsYestarget keywords required field UTF-8 encoding maximum number of keywords you can specify in this array: 1000 the keywords will be converted to lowercase format
language_codeNolanguage code required field if language_name is not specified example: enen
location_nameNofull name of the location required field if location_code is not specified example: 'United States'United States

TDQS

A3.7/5.0
Behavior3/5

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

Description aligns with annotations (readOnlyHint=true, idempotentHint=true). Does not go beyond annotations to disclose additional behavioral traits such as response format, rate limits, or authentication needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no unnecessary words, front-loaded with purpose and constraints. Highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Lacks description of return values/response format, which would be helpful for an agent interpreting results. No pagination or error handling details. Adequate given tool simplicity, but could be more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents parameters well. The description adds minimal value by stating the max keywords and Amazon context, but does not enhance understanding of parameter usage beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly specifies the action (provide search volume values), resource (keywords on Amazon), and constraints (max 1000 keywords). Distinguishes from sibling tools like Google-related volume tools due to 'Amazon' specificity.

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

Usage Guidelines3/5

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

Implied usage from context (Amazon keyword volume), but no explicit guidance on when to use vs alternatives or when not to use it. Does not mention sibling tools that might be used for similar purposes.

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

dataforseo_labs_amazon_product_competitorsDataForSEO Labs Amazon Product CompetitorsA
Read-onlyIdempotent

This endpoint will provide you with a list of products that intersect with a target asin in Amazon SERPs. The data can help you identify product competitors for any listing published on Amazon.

ParametersJSON Schema
NameRequiredDescriptionDefault
asinYesproduct ID required field unique product identifier (ASIN) on Amazon
limitNoMaximum number of product competitors to return
offsetNooffset in the results array of returned product competitors optional field default value: 0 if you specify the 10 value, the first ten product competitors in the results array will be omitted and the data will be provided for the successive product competitors
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like Use % with like/not_like/ilike/not_ilike as a wildcard. Example: ["full_metrics.amazon_serp.pos_1", ">", 20]
order_byNoresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting parameter example: ["full_metrics.amazon_serp.pos_1,desc"] default rule: ["ranked_serp_element.serp_item.rank_group,asc"] note that you can set no more than three sorting rules in a single request example: ["full_metrics.amazon_serp.pos_1,desc","avg_position,desc"]
language_codeNolanguage code required field if language_name is not specified example: enen
location_nameNofull name of the location required field if location_code is not specified Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only example: 'United States'United States

TDQS

A3.6/5.0
Behavior2/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the tool is known to be safe and idempotent. The description adds no additional behavioral context such as authentication needs, rate limits, or side effects, thus providing minimal added value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences, no fluff, and front-loads the primary purpose. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 7 parameters and no output schema, the description lacks completeness. It does not explain pagination (limit, offset), filtering, ordering, location specifics, or return structure, leaving significant gaps 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.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all parameters thoroughly. The description does not add meaning beyond the schema about parameters, 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.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides a list of products that intersect with a target ASIN in Amazon SERPs, using specific verbs and resource identification. It distinguishes itself from sibling tools like dataforseo_labs_amazon_product_kw_intersections by focusing on product competitors rather than keyword intersections.

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

Usage Guidelines4/5

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

The description identifies the tool's use case for identifying product competitors, providing clear context. However, it does not explicitly state when not to use it or name alternative tools, though the sibling list implies differentiation.

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

dataforseo_labs_amazon_product_kw_intersectionsDataForSEO Labs Amazon Product Keyword IntersectionsB
Read-onlyIdempotent

This endpoint will provide you with a list of keywords for which the target products intersect in Amazon SERP. The returned results are specific to the asins specified in a POST request.

ParametersJSON Schema
NameRequiredDescriptionDefault
asinsYestarget product ASINs required field product IDs of the products for which you need to find keyword intersections the maximum number of ASINs you can specify is 20 example: ["B09172433Z", "B07GBZ4Q68"]
limitNoMaximum number of keywords to return
offsetNooffset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like Use % with like/not_like/ilike/not_ilike as a wildcard. Example: ["avg_position", "<", 10]
order_byNoresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting parameter example: ["sum_position,desc"] default rule: ["intersections,desc"] note that you can set no more than three sorting rules in a single request example: ["intersections,desc","avg_position,asc"]
language_codeNolanguage code required field if language_name is not specified example: enen
location_nameNofull name of the location required field if location_code is not specified Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only example: 'United States'United States
intersection_modeNomode for finding asin intersections optional field possible values: union, intersect default value: intersectintersect

TDQS

B3.3/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's addition of 'POST request' and 'results specific to ASINs' provides minor extra context. There is no contradiction, but no further behavioral traits (e.g., rate limits, pagination) are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences, front-loaded with the main action in the first sentence. It avoids fluff, though could be slightly sharper (e.g., 'lists keywords...' instead of 'will provide you with a list...').

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (8 parameters, no output schema), the two-sentence description is insufficient. It does not explain the concept of 'intersections' (e.g., union vs intersect mode), the return format, or how to interpret results, leaving significant gaps for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each parameter is already documented in the schema. The tool description adds no additional meaning beyond what the schema provides, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides a list of keywords where target products intersect in Amazon SERP, using a specific verb ('provide') and resource ('keywords'). It distinguishes from sibling Amazon tools like dataforseo_labs_amazon_ranked_keywords or dataforseo_labs_amazon_product_competitors by focusing on keyword intersections.

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

Usage Guidelines2/5

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

The description does not offer any guidance on when to use this tool versus alternatives like other Amazon keyword or intersection tools. It lacks explicit 'when to use' or 'when not to use' instructions, which is needed given the variety of sibling tools.

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

dataforseo_labs_amazon_product_rank_overviewDataForSEO Labs Amazon Product Rank OverviewB
Read-onlyIdempotent

This endpoint will provide you with ranking data from organic and paid Amazon SERPs for the target products. The returned results are specific to the asins specified in a POST request.

ParametersJSON Schema
NameRequiredDescriptionDefault
asinsYesproduct IDs to compare required field product IDs to receive ranking data for the maximum number of ASINs you can specify in this array is 1000 Note: all letters in ASIN code must be specified in uppercase format example: ["B001TJ3HUG", "B01LW2SL7R"]
language_codeNolanguage code required field if language_name is not specified example: enen
location_nameNofull name of the location required field if location_code is not specified Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only example: 'United States'United States

TDQS

B3.3/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that it returns ranking data from organic and paid SERPs via a POST request, which aligns with annotations. There is no contradiction, but little extra behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the core purpose. Every sentence adds value without redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given high schema coverage, clear annotations, and no output schema, the description explains the input (ASINs) and general output (ranking data) but lacks details on the structure of returned data (e.g., fields like position, URL, etc.). The openWorldHint mitigates this slightly, but more completeness would help agent expectations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with detailed descriptions for asins (max 1000, uppercase required, example), language_code (default en), and location_name (supported locations listed). The tool description adds no further parameter-specific meaning, so it meets the baseline but does not provide additional clarification.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it provides ranking data from organic and paid Amazon SERPs for target ASINs. It distinguishes from siblings like 'dataforseo_labs_amazon_ranked_keywords' (keyword focus) and 'dataforseo_labs_amazon_product_competitors' (competitor focus). However, it could be more specific about what exactly 'rank overview' entails (e.g., position, URL, etc.).

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

Usage Guidelines2/5

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

The description only explains what the tool does, with no guidance on when to use it versus alternatives (e.g., when to use this vs. dataforseo_labs_amazon_ranked_keywords for keyword-level data). No exclusion criteria or prerequisites are mentioned.

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

dataforseo_labs_amazon_ranked_keywordsDataForSEO Labs Amazon Ranked KeywordsA
Read-onlyIdempotent

This endpoint will provide you with a list of keywords the target product ranks for on Amazon. The returned results are specific to the asin specified in a POST request.

ParametersJSON Schema
NameRequiredDescriptionDefault
asinYesproduct ID required field unique product identifier (ASIN) on Amazon
limitNoMaximum number of keywords to return
offsetNooffset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like, match, not_match Use % with like/not_like as a wildcard. Example: ["keyword_data.keyword_info.search_volume", "in", [100, 1000]]
order_byNoresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting parameter example: ["keyword_data.keyword_info.competition,desc"] default rule: ["ranked_serp_element.serp_item.rank_group,asc"] note that you can set no more than three sorting rules in a single request example: ["keyword_data.keyword_info.search_volume,desc","keyword_data.keyword_info.cpc,desc"]
language_codeNolanguage code required field if language_name is not specified example: enen
location_nameNofull name of the location required field if location_code is not specified Note: this endpoint currently supports the US, Egypt, Saudi Arabia, and the United Arab Emirates locations only example: 'United States'United States

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds minimal behavioral context beyond confirming it's a read operation. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise at two sentences. Front-loaded with the core purpose. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should explain return format or structure. It only mentions 'list of keywords', lacking detail on fields, pagination, or typical response. For a 7-parameter tool, more context is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline 3 is appropriate. The description does not add any additional meaning beyond what the schema provides for parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides a list of keywords a product ranks for on Amazon, specific to the ASIN. This distinguishes it from sibling tools like keyword intersections or rank overview.

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

Usage Guidelines3/5

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

The description implies usage (for Amazon ASIN keywords) but does not explicitly state when to use this tool versus alternatives like Amazon product keyword intersections or competitors. No exclusions or alternative mentions.

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

dataforseo_labs_available_filtersDataForSEO Labs Available FiltersB
Read-onlyIdempotent

Here you will find all the necessary information about filters that can be used with DataForSEO Labs API endpoints.

Please, keep in mind that filters are associated with a certain object in the result array, and should be specified accordingly.

ParametersJSON Schema
NameRequiredDescriptionDefault
toolNoThe name of the tool to get filters for

TDQS

B3.2/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds that filters are associated with a certain object in the result array, which is modest extra context. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, no redundant information. It efficiently conveys the purpose and a key detail about filters. Could be more structured but is concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (1 parameter, no output schema, clear annotations), the description is mostly adequate. However, it does not describe the output format or what 'all necessary information' entails, leaving some ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter 'tool', with a clear description. The tool description does not add further 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.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool provides information about filters for DataForSEO Labs API endpoints. It distinguishes itself from sibling 'available_filters' tools by the 'dataforseo_labs' prefix.

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

Usage Guidelines2/5

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

The description does not provide any guidance on when to use this tool versus alternatives, nor does it mention when not to use it. There is no comparison to similar filter tools like backlinks_available_filters.

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

dataforseo_labs_bulk_keyword_difficultyDataForSEO Labs Bulk Keyword DifficultyA
Read-onlyIdempotent

This endpoint will provide you with the Keyword Difficulty metric for a maximum of 1,000 keywords in one API request. Keyword Difficulty stands for the relative difficulty of ranking in the first top-10 organic results for the related keyword. Keyword Difficulty in DataForSEO API responses indicates the chance of getting in top-10 organic results for a keyword on a logarithmic scale from 0 to 100.

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordsYestarget keywords required field UTF-8 encoding maximum number of keywords you can specify in this array: 1000
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining the metric's logarithmic 0-100 scale and the 1,000 keyword limit, but does not detail response structure 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: two sentences that front-load the main purpose, with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description adequately explains the metric's meaning but could be improved by mentioning what the response contains (e.g., difficulty per keyword). It is sufficient for an agent to understand the return value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all parameters. The description adds no additional explanation for the parameters beyond what is in 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.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides the Keyword Difficulty metric for up to 1,000 keywords in one request, distinguishing it from sibling tools like keyword suggestions or search volume by explicitly mentioning the bulk aspect and the specific metric.

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

Usage Guidelines3/5

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

The description implies usage when needing difficulty for many keywords, but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention situations where it should not be used.

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

dataforseo_labs_bulk_traffic_estimationDataForSEO Labs Bulk Traffic EstimationA
Read-onlyIdempotent

This endpoint will provide you with estimated monthly traffic volumes for up to 1,000 domains, subdomains, or webpages. Along with organic search traffic estimations, you will also get separate values for paid search, featured snippet, and local pack results.

ParametersJSON Schema
NameRequiredDescriptionDefault
targetsYestarget domains, subdomains, and webpages. you can specify domains, subdomains, and webpages in this field; domains and subdomains should be specified without https:// and www.; pages should be specified with absolute URL, including https:// and www.; you can set up to 1000 domains, subdomains or webpages
item_typesNodisplay results by item type indicates the type of search results included in the response
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States
ignore_synonymsNoignore highly similar keywords, if set to true, results will be more accurate

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by specifying the output includes separate traffic values for paid, featured snippet, and local pack. This goes beyond annotations but does not cover potential rate limits or data recency, though the up-to-1000 limit is implied. The description complements annotations well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loading the core function (estimated monthly traffic volumes) and then listing the output types. Every word earns its place, with no unnecessary detail. It is highly efficient for an AI agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 5 parameters (all described in schema), no output schema, and simple estimation task, the description covers the key result (traffic volumes by type). It lacks mention of response format or location/language impact, but the schema provides that info. It is sufficiently complete for an agent to understand what the tool produces, though a mention of the 'item_types' parameter control would be slightly better.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains all 5 parameters. The description does not add new parameter-level meaning; it only summarizes the overall purpose. Baseline 3 is appropriate as the description offers no extra semantic value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides estimated monthly traffic volumes for up to 1,000 domains/subdomains/webpages, with breakdowns for organic, paid, featured snippet, and local pack. The verb 'provide' and resource 'domains/subdomains/webpages' make the purpose specific, and the title 'Bulk Traffic Estimation' reinforces this, distinguishing it from sibling tools like keyword suggestion or backlinks.

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

Usage Guidelines2/5

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

The description does not provide any explicit guidance on when to use this tool versus alternatives (e.g., bulk keyword difficulty). It simply states what it does, leaving the agent to infer usage context without explicit 'when to use' or 'when not to use' instructions.

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

dataforseo_labs_google_competitors_domainDataForSEO Labs Google Competitors DomainA
Read-onlyIdempotent

This endpoint will provide you with a full overview of ranking and traffic data of the competitor domains from organic and paid search. In addition to that, you will get the metrics specific to the keywords both competitor domains and your domain rank for within the same SERP.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of keywords to return
offsetNooffset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
targetYestarget domain
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like Use % with like/not_like/ilike/not_ilike as a wildcard. Examples: Single: ["metrics.organic.count", ">", 50] Combined: [["metrics.organic.pos_1", "<>", 0], "and", ["metrics.organic.impressions_etv", ">=", "10"]] Nested: [[["metrics.organic.count", ">=", 50], "and", ["metrics.organic.pos_1", "in", [1, 5]]], "or", ["metrics.organic.etv", ">=", "100"]]
order_byNoresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting parameter default rule: ["relevance,desc"] example: ["relevance,desc","keyword_info.search_volume,desc"]
item_typesNodisplay results by item type indicates the type of search results included in the response
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States
ignore_synonymsNoignore highly similar keywords, if set to true, results will be more accurate
exclude_top_domainsNoindicates whether to exclude world's largest websites optional field default value: false set to true if you want to get highly-relevant competitors excluding the top websites
include_clickstream_dataNoInclude or exclude data from clickstream-based metrics in the result

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side effects. The description adds that the tool returns 'ranking and traffic data' and 'metrics specific to keywords', which is useful behavioral context. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, clear and front-loaded with the core purpose. No unnecessary words. Efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 11 parameters and no output schema, the description is brief. It explains the overall data returned but omits details like pagination behavior or example usage. Combined with 100% schema coverage and annotations, it is adequate but lacks completeness for a full understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage; every parameter (target, limit, offset, filters, etc.) is documented. The tool description adds general context about what data is returned but does not provide additional meaning beyond schema descriptions. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides 'a full overview of ranking and traffic data of the competitor domains from organic and paid search' and mentions 'metrics specific to the keywords both competitor domains and your domain rank for within the same SERP'. This is a specific verb-resource pair (provides overview of competitor domains) that differentiates it from related tools like dataforseo_labs_google_serp_competitors.

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

Usage Guidelines3/5

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

The description implies usage for analyzing competitor domains in organic and paid search but does not explicitly state when to use this tool over alternatives (e.g., SERP-level competitor tools). No guidance on when not to use or prerequisites.

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

dataforseo_labs_google_domain_intersectionDataForSEO Labs Google Domain IntersectionA
Read-onlyIdempotent

This endpoint will provide you with the keywords for which both specified domains rank within the same SERP. You will get search volume, competition, cost-per-click and impressions data on each intersecting keyword. Along with that, you will get data on the first and second domain's SERP element discovered for this keyword, as well as the estimated traffic volume and cost of ad traffic.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of keywords to return
offsetNooffset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like Use % with like/not_like/ilike/not_ilike as a wildcard. Examples: Single: ["keyword_data.keyword_info.search_volume", "in", [100, 1000]] Combined: [["first_domain_serp_element.etv", ">", 0], "and", ["first_domain_serp_element.description", "like", "%goat%"]] Nested: [["keyword_data.keyword_info.search_volume", ">", 100], "and", [["first_domain_serp_element.description", "like", "%goat%"], "or", ["second_domain_serp_element.type", "=", "organic"]]]
target1Yestarget domain 1
target2Yestarget domain 2
order_byNoresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting parameter example: ["keyword_data.keyword_info.competition,desc"] default rule: ["keyword_data.keyword_info.search_volume,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["keyword_data.keyword_info.search_volume,desc","keyword_data.keyword_info.cpc,desc"]
item_typesNodisplay results by item type indicates the type of search results included in the response
intersectionsNodomain intersections in SERP optional field if you set intersections to true, you will get the keywords for which both target domains specified as target1 and target2 have results within the same SERP; the corresponding SERP elements for both domains will be provided in the results array Note: this endpoint will not provide results if the number of intersecting keywords exceeds 10 million if you specify intersections: false, you will get the keywords for which the domain specified as target1 has results in SERP, and the domain specified as target2 doesn’t; thus, the corresponding SERP elements and other data will be provided for the domain specified as target1only default value: true
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States
ignore_synonymsNoignore highly similar keywords, if set to true, results will be more accurate
include_clickstream_dataNoInclude or exclude data from clickstream-based metrics in the result

TDQS

A4/5.0
Behavior4/5

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context about the output data (search volume, CPC, SERP elements, traffic estimates) and clarifies the intersection logic. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is only four sentences, each conveying essential information without fluff. The main purpose is front-loaded, and the structure is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 12 parameters with full schema coverage and no output schema, the description explains the key output fields well. It omits details about filtering and sorting, but the schema covers those. The description is complete enough for most use cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the description does not need to detail parameters. However, it adds no extra meaning beyond the schema; it focuses on output rather than input semantics. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool finds keywords where both specified domains rank in the same SERP, providing specific data fields. This distinguishes it from siblings like page_intersection or single-domain tools.

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

Usage Guidelines3/5

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

The description implies usage for finding intersecting keywords but does not explicitly state when to use this tool vs alternatives like dataforseo_labs_google_page_intersection or backlinks_domain_intersection. No exclusions or alternative pointers are given.

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

dataforseo_labs_google_domain_rank_overviewDataForSEO Labs Google Domain Rank OverviewA
Read-onlyIdempotent

This endpoint will provide you with ranking and traffic data from organic and paid search for the specified domain. You will be able to review the domain ranking distribution in SERPs as well as estimated monthly traffic volume for both organic and paid results.

ParametersJSON Schema
NameRequiredDescriptionDefault
targetYestarget domain
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States
ignore_synonymsNoignore highly similar keywords, if set to true, results will be more accurate

TDQS

A4/5.0
Behavior4/5

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) are present and cover safety. Description adds value by specifying it returns ranking distribution and traffic volume, but doesn't contradict annotations. With annotations already providing core behavioral traits, the description offers good additional context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with key action ('will provide you with ranking and traffic data') and efficient. No fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (4 parameters, no output schema), the description adequately covers what the tool does and what data it returns. It mentions organic/paid search, ranking distribution, and traffic volume. Slight gap in not describing the output structure, but overall complete for the tool's purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (all 4 parameters described in schema). Description doesn't add new meaning beyond the schema; it summarizes the tool's output but does not elaborate on parameter usage or constraints. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it provides ranking and traffic data for organic and paid search for a domain. It specifies the resource (domain ranking overview) and what data is included (ranking distribution, estimated monthly traffic). This distinguishes it from sibling tools like keyword suggestions or backlinks tools.

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

Usage Guidelines3/5

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

No explicit guidance on when to use this tool versus alternatives. The description implies it is for reviewing a domain's ranking overview, but doesn't mention when not to use it or provide comparisons to similar tools like dataforseo_labs_google_ranked_keywords or dataforseo_labs_google_competitors_domain.

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

dataforseo_labs_google_historical_keyword_dataDataForSEO Labs Google Historical Keyword DataA
Read-onlyIdempotent

This endpoint provides Google historical keyword data for specified keywords, including search volume, cost-per-click, competition values for paid search, monthly searches, and search volume trends. You can get historical keyword data since August, 2021, depending on keywords along with location and language combination

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordsYeskeywords required field The maximum number of keywords you can specify: 700 The maximum number of characters for each keyword: 80 The maximum number of words for each keyword phrase: 10 the specified keywords will be converted to lowercase format, data will be provided in a separate array note that if some of the keywords specified in this array are omitted in the results you receive, then our database doesn't contain such keywords and cannot return data on them you will not be charged for the keywords omitted in the results
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint true, idempotentHint true, and destructiveHint false. The description adds context about data availability since August 2021 and dependency on location/language, going beyond annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise comprising only two sentences. It is front-loaded with the purpose and lists key outputs, then adds contextual detail about the date range and dependencies. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with simple parameters and no output schema, the description adequately explains the returned metrics and constraints (date range, location/language). It could mention pagination or formatting, but overall it is sufficient for agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed parameter descriptions. The description does not add additional meaning about parameters beyond what the schema already provides, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it provides historical keyword data including specific metrics like search volume, CPC, competition, monthly searches, and trends. The term 'historical' and the mention of data since August 2021 differentiate it from sibling tools like keyword overview or suggestions.

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

Usage Guidelines2/5

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 vs. alternatives like keyword overview or keyword suggestions. It does not mention when not to use it, leaving the agent to infer from the description alone.

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

dataforseo_labs_google_historical_rank_overviewDataForSEO Labs Google Historical Rank OverviewB
Read-onlyIdempotent

This endpoint will provide you with historical data on rankings and traffic of the specified domain, such as domain ranking distribution in SERPs and estimated monthly traffic volume for both organic and paid results

ParametersJSON Schema
NameRequiredDescriptionDefault
targetYestarget domain
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States
ignore_synonymsNoignore highly similar keywords, if set to true, results will be more accurate
include_clickstream_dataNoInclude or exclude data from clickstream-based metrics in the result

TDQS

B3.3/5.0
Behavior2/5

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds minimal behavioral context (e.g., returns historical data) beyond what annotations provide. No mention of rate limits, pagination, 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence that directly states the purpose and examples. Efficient and front-loaded, though could be slightly more compact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and a tool with multiple output facets, the description lacks details on date range scope (no date parameter), result structure, and pagination. It only provides high-level examples, leaving agents without sufficient context for expected output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all parameters have descriptions. The tool description does not add 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.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it provides historical ranking and traffic data for a specified domain, listing specific metrics like domain ranking distribution and estimated monthly traffic. This distinguishes it from sibling tools like 'dataforseo_labs_google_domain_rank_overview' (current) and 'dataforseo_labs_google_historical_keyword_data' (per keyword).

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

Usage Guidelines3/5

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

The description implies use for historical domain analysis but lacks explicit guidance on when to use this tool versus alternatives like 'dataforseo_labs_google_domain_rank_overview'. No when-not-to-use or alternatives mentioned.

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

dataforseo_labs_google_historical_serpsDataForSEO Labs Google Historical SERPsB
Read-onlyIdempotent

This endpoint will provide you with Google SERPs collected within the specified time frame. You will also receive a complete overview of featured snippets and other extra elements that were present within the specified dates. The data will allow you to analyze the dynamics of keyword rankings over time for the specified keyword and location.

ParametersJSON Schema
NameRequiredDescriptionDefault
date_toNoending date of the time range, date format: YYYY-MM-DD
keywordYestarget keyword
date_fromNostarting date of the time range, date format: YYYY-MM-DD
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds that the tool returns SERPs with extra elements like featured snippets, but does not disclose potential rate limits, data freshness, or pagination behavior. It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no fluff. Could be slightly more streamlined, but it effectively communicates the core functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description partially covers output (SERPs, featured snippets) but lacks details on data structure, pagination, or limitations. Parameters are well-documented. Sufficient for basic understanding but not thoroughly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% coverage with descriptions for all 5 parameters. The description adds no further meaning beyond saying 'specified time frame' and 'keyword and location', which is already in schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it provides historical Google SERPs for a keyword and location over a time range, including featured snippets. However, it does not distinguish itself from sibling tools like `dataforseo_labs_google_historical_rank_overview` or `dataforseo_labs_google_historical_keyword_data`, which also deal with historical data.

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

Usage Guidelines3/5

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

The description implies usage for analyzing ranking dynamics over time via historical SERPs, but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternative tools for similar purposes.

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

dataforseo_labs_google_keyword_ideasDataForSEO Labs Google Keyword IdeasB
Read-onlyIdempotent

The Keyword Ideas provides search terms that are relevant to the product or service categories of the specified keywords. The algorithm selects the keywords which fall into the same categories as the seed keywords specified in a POST array. As a result, you will get a list of relevant keyword ideas for up to 200 seed keywords. Along with each keyword idea, you will get its search volume rate for the last month, search volume trend for the previous 12 months, as well as current cost-per-click and competition values. Moreover, this endpoint supplies minimum, maximum and average values of daily impressions, clicks and CPC for each result.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of keywords to return
offsetNooffset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like Use % with like/not_like/ilike/not_ilike as a wildcard. Examples: Single: ["keyword_info.search_volume", ">", 0] Combined: [["keyword_info.search_volume", "in", [0, 1000]], "and", ["keyword_info.competition_level", "=", "LOW"]] Nested: [["keyword_info.search_volume", ">", 100], "and", [["keyword_info.cpc", "<", 0.5], "or", ["keyword_info.high_top_of_page_bid", "<=", 0.5]]]
keywordsYestarget keywords
order_byNoresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting parameter default rule: ["relevance,desc"] relevance is used as the default sorting rule to provide you with the closest keyword ideas. We recommend using this sorting rule to get highly-relevant search terms. Note that relevance is only our internal system identifier, so it can not be used as a filter, and you will not find this field in the result array. The relevance score is based on a similar principle as used in the Keywords For Keywords endpoint. note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["relevance,desc","keyword_info.search_volume,desc"]
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States
include_clickstream_dataNoInclude or exclude data from clickstream-based metrics in the result

TDQS

B3.4/5.0
Behavior4/5

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by detailing the algorithm (category-based selection) and outputs (search volume, trend, CPC, etc.). No contradictions, but could mention rate limits 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.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph that conveys necessary information but lacks structural elements like bullets or clear separation of concerns. It is somewhat dense but not excessively long.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 8 parameters with full schema coverage and no output schema, the description adequately explains the output and algorithm. It mentions seed keyword limit (200) and POST method, which adds context. Still, pagination and filter usage are not elaborated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline 3. Description does not add extra meaning to parameters beyond what the schema provides; it focuses on overall behavior rather than parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it provides relevant keyword ideas based on category-matching algorithm and lists specific metrics returned. However, it lacks explicit differentiation from sibling tools like related keywords or suggestions, slightly reducing clarity.

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

Usage Guidelines2/5

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

No usage guidance is provided—no mention of when to use this tool over alternatives or prerequisites. The description only states what it does, not appropriate contexts.

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

dataforseo_labs_google_keyword_overviewDataForSEO Labs Google Keyword OverviewB
Read-onlyIdempotent

This endpoint provides Google keyword data for specified keywords. For each keyword, you will receive current cost-per-click, competition values for paid search, search volume, search intent, monthly searches

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordsYeskeywords required field The maximum number of keywords you can specify: 700 The maximum number of characters for each keyword: 80 The maximum number of words for each keyword phrase: 10 the specified keywords will be converted to lowercase format, data will be provided in a separate array note that if some of the keywords specified in this array are omitted in the results you receive, then our database doesn't contain such keywords and cannot return data on them you will not be charged for the keywords omitted in the results
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States
include_clickstream_dataNoInclude or exclude data from clickstream-based metrics in the result

TDQS

B3.2/5.0
Behavior3/5

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, non-destructive. The description adds minor behavioral context (keyword lowercase conversion, no charge for omitted keywords) but does not go beyond what annotations imply for safety.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first states the purpose, second details output fields. Efficient and front-loaded, but could be slightly more structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 4 parameters and no output schema, the description adequately summarizes the returned fields. It covers the key outputs without being overly verbose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description does not add parameter-specific details. Baseline 3 applies because the schema already documents all parameters well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it provides keyword data and lists specific metrics (cost-per-click, competition, search volume, etc.). It distinguishes the tool's output from siblings like keyword_suggestions or related_keywords, but naming a sibling would have strengthened it.

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

Usage Guidelines2/5

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 dataforseo_labs_google_keyword_suggestions or dataforseo_labs_google_related_keywords. The description only explains what it does, not when it's appropriate.

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

dataforseo_labs_google_keywords_for_siteDataForSEO Labs Google Keywords For SiteB
Read-onlyIdempotent

The Keywords For Site endpoint will provide you with a list of keywords relevant to the target domain. Each keyword is supplied with relevant, search volume data for the last month, cost-per-click, competition

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of keywords to return
offsetNooffset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
targetYestarget domain
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like Use % with like/not_like/ilike/not_ilike as a wildcard. Examples: Single: ["keyword_info.search_volume", ">", 0] Combined: [["keyword_info.search_volume", "in", [0, 1000]], "and", ["keyword_info.competition_level", "=", "LOW"]] Nested: [["keyword_info.search_volume", ">", 100], "and", [["keyword_info.cpc", "<", 0.5], "or", ["keyword_info.high_top_of_page_bid", "<=", 0.5]]]
order_byNoresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting parameter default rule: ["relevance,desc"] example: ["relevance,desc","keyword_info.search_volume,desc"]
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States
include_subdomainsNoInclude keywords from subdomains
include_clickstream_dataNoInclude or exclude data from clickstream-based metrics in the result

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds minimal behavioral context beyond stating the output includes specific metrics. It does not disclose pagination behavior, rate limits, or data freshness, but the annotations sufficiently cover the safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, directly stating the tool's purpose and output characteristics. No unnecessary words or repetition. Well-structured and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite good schema coverage and annotations, the description omits important context for a tool with 9 parameters including complex filters and ordering. It does not mention pagination, filter capabilities, or default behavior. The lack of output schema also means the agent must infer return structure. While the core purpose is clear, the description falls short for a comprehensive understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents all parameters thoroughly. The description does not repeat or enrich parameter details, offering no additional meaning beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('provide'), the resource ('a list of keywords relevant to the target domain'), and the data included ('search volume data for the last month, cost-per-click, competition'). It distinguishes from sibling tools like 'dataforseo_labs_google_related_keywords' which provides related keywords for a given keyword, making the purpose unambiguous.

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

Usage Guidelines2/5

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

The description does not provide any guidance on when to use this tool versus alternatives, nor does it mention prerequisites, context, or limitations. No explicit 'when-to-use' or 'when-not-to-use' advice is given, 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.

dataforseo_labs_google_keyword_suggestionsDataForSEO Labs Google Keyword SuggestionsA
Read-onlyIdempotent

The Keyword Suggestions provides search queries that include the specified seed keyword.

The algorithm is based on the full-text search for the specified keyword and therefore returns only those search terms that contain the keyword you set in the POST array with additional words before, after, or within the specified key phrase. Returned keyword suggestions can contain the words from the specified key phrase in a sequence different from the one you specify.

As a result, you will get a list of long-tail keywords with each keyword in the list matching the specified search term.

Along with each suggested keyword, you will get its search volume rate for the last month, search volume trend for the previous 12 months, as well as current cost-per-click and competition values. Moreover, this endpoint supplies minimum, maximum and average values of daily impressions, clicks and CPC for each result.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of keywords to return
offsetNooffset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like Use % with like/not_like/ilike/not_ilike as a wildcard. Examples: Single: ["keyword_info.search_volume", ">", 0] Combined: [["keyword_info.search_volume", "in", [0, 1000]], "and", ["keyword_info.competition_level", "=", "LOW"]] Nested: [["keyword_info.search_volume", ">", 100], "and", [["keyword_info.cpc", "<", 0.5], "or", ["keyword_info.high_top_of_page_bid", "<=", 0.5]]]
keywordYestarget keyword
order_byNoresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order a comma is used as a separator example: ["keyword_info.competition,desc"] default rule: ["keyword_info.search_volume,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["keyword_info.search_volume,desc","keyword_info.cpc,desc"]
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States
include_clickstream_dataNoInclude or exclude data from clickstream-based metrics in the result

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value beyond these by detailing the algorithm (full-text search, variable sequence) and the output metrics (search volume, trend, CPC, competition, daily impressions/clicks/CPC stats). No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a few well-structured paragraphs that front-load the core purpose and then provide algorithmic and output details. It is efficient without unnecessary words, though a more structured format (e.g., bullet points for metrics) could improve readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the algorithm, the output metrics, and the nature of suggestions (long-tail keywords containing the seed). Given no output schema, it adequately covers return values. It lacks error conditions, rate limits, or authorization details, but these are somewhat expected for a read-only tool with comprehensive annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The tool description does not add new parameter semantics; it focuses on output and algorithm. The schema's own parameter descriptions are sufficient, so the description provides minimal added value for parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool returns search queries containing the specified seed keyword, explaining the full-text search algorithm and what kind of suggestions are returned. It implicitly distinguishes from related keyword tools by emphasizing containment, but does not explicitly name siblings.

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

Usage Guidelines3/5

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

The description explains the algorithmic behavior and the type of results (long-tail keywords containing the seed), providing clear context for when to use it. However, it does not explicitly state when not to use it or mention alternative tools like dataforseo_labs_google_related_keywords for related keywords not containing the seed.

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

dataforseo_labs_google_page_intersectionDataForSEO Labs Google Page IntersectionA
Read-onlyIdempotent

This endpoint will provide you with the keywords for which specified pages rank within the same SERP. You will get search volume, competition, cost-per-click and impressions data on each intersecting keyword. Along with that, you will get data on SERP elements that specified pages rank for in search results, as well as the estimated traffic volume and cost of ad traffic. Page Intersection endpoint supports organic, paid, local pack and featured snippet results.

Find keywords several webpages rank for: If you would like to get the keywords several pages rank for, you need to specify webpages only in the pages object. This way, you will receive intersected ranked keywords for the specified URLs.

Find keywords your competitors rank for but you do not: If you would like to receive all keywords several pages rank for, but particular pages do not, you need to use the exclude_pages array as well. This way you will receive the keywords for which the URLs from the pages object rank for, but the URLs from the exclude_pages array do not

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of keywords to return
pagesYespages array required field you can set up to 20 pages in this object the pages should be specified with absolute URLs (including http:// or https://) if you specify a single page here, we will return results only for this page; you can also use a wildcard ('*') character to specify the search pattern example: "example.com" search for the exact URL "example.com/eng/*" search for the example.com page and all its related URLs which start with '/eng/', such as "example.com/eng/index.html" and "example.com/eng/help/", etc. note: a wilcard should be placed after the slash ('/') character in the end of the URL, it is not possible to place it after the domain in the following way: https://dataforseo.com* use https://dataforseo.com/* instead
offsetNooffset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like Use % with like/not_like/ilike/not_ilike as a wildcard. Examples: Single: ["keyword_data.keyword_info.search_volume", "in", [100, 1000]] Combined: [["intersection_result.1.etv", ">", 0], "and", ["intersection_result.2.description", "like", "%goat%"]] Nested: [["keyword_data.keyword_info.search_volume", ">", 100], "and", [["intersection_result.1.description", "like", "%goat%"], "or", ["intersection_result.2.type", "=", "organic"]]]
order_byNoresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting parameter example: ["keyword_data.keyword_info.competition,desc"] default rule: ["keyword_data.keyword_info.search_volume,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["intersection_result.1.rank_group,asc","intersection_result.2.rank_absolute,asc"]
item_typesNodisplay results by item type indicates the type of search results included in the response
exclude_pagesNoURLs of pages you want to exclude optional field you can set up to 10 pages in this array if you use this array, results will contain the keywords for which URLs from the pages object rank, but URLs from exclude_pages array do not; note that if you specify this field, the results will be based on the keywords any URL from pages ranks for regardless of intersections between them. However, you can set intersection_mode to intersect and results will contain the keywords all URLs from pages rank for in the same SERP and URLs from exclude_pages do not. use a wildcard (‘*’) character to specify the search pattern example: "exclude_pages": [ "https://www.apple.com/iphone/*", "https://dataforseo.com/apis/*", "https://www.microsoft.com/en-us/industry/services/" ]
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States
ignore_synonymsNoignore highly similar keywords, if set to true, results will be more accurate
intersection_modeNoindicates whether to intersect keywords optional field use this field to intersect or merge results for the specified URLs possible values: union, intersect union – results are based on all keywords any URL from pages rank for; intersect – results are based on the keywords all URLs from pages rank for in the same SERP: by default, results are based on the intersect mode if you specify only pages array. If you specify exclude_pages as well, results are based on the union mode
include_clickstream_dataNoInclude or exclude data from clickstream-based metrics in the result

TDQS

A3.8/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context about the data returned (search volume, competition, etc.) and mentions supported SERP elements. It does not contradict annotations. However, it does not disclose potential rate limits, authentication requirements, or any side effects beyond what annotations cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is moderately sized and well-structured, with clear sections for the two use cases. It front-loads the main purpose. Some repetition exists (e.g., mentions data types twice), but overall it is efficient and easy to read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 12 parameters, no output schema, and complex functionality, the description covers the main output (keywords with metrics, SERP elements) and two key use cases. It provides enough context for an AI agent to understand what the tool does and how to use it, though some advanced features (like filters) are left to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, baseline is 3. The description adds value by explaining the two main use cases, which guide parameter usage (e.g., specifying pages vs. using exclude_pages). It also clarifies the effect of exclude_pages and intersection_mode beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool finds keywords for which specified pages rank within the same SERP, and provides additional metrics. It includes two specific use cases. However, it does not directly differentiate the tool from sibling tools like dataforseo_labs_google_domain_intersection or backlinks_domain_intersection, though the 'page intersection' focus is evident.

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

Usage Guidelines4/5

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

The description explicitly provides two usage scenarios: finding keywords several pages rank for, and finding keywords competitors rank for but the user does not. It explains how to use exclude_pages for the latter. However, it does not mention when to use alternative tools 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.

dataforseo_labs_google_ranked_keywordsDataForSEO Labs Google Ranked KeywordsA
Read-onlyIdempotent

This endpoint will provide you with the list of keywords that any domain or webpage is ranking for. You will also get SERP elements related to the keyword position, as well as impressions, monthly searches and other data relevant to the returned keywords.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of keywords to return
offsetNooffset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
targetYesdomain name or page url required field the domain name of the target website or URL of the target webpage; the domain name must be specified without https:// or www.; the webpage URL must be specified with https:// or www. Note: if you specify the webpage URL without https:// or www., the result will be returned for the entire domain rather than the specific page
filtersNoArray of filter conditions and logical operators. Each filter condition is an array of [field, operator, value]. Maximum 8 filters allowed. Available operators: =, <>, <, <=, >, >=, in, not_in, like, not_like, ilike, not_ilike, regex, not_regex, match, not_match Logical operators: "and", "or" Examples: Simple filter: [["ranked_serp_element.serp_item.rank_group","<=",10]] With logical operator: [["ranked_serp_element.serp_item.rank_group","<=",10],"or",["ranked_serp_element.serp_item.type","<>","paid"]] Complex filter: [["keyword_data.keyword_info.search_volume","<>",0],"and",[["ranked_serp_element.serp_item.type","<>","paid"],"or",["ranked_serp_element.serp_item.is_malicious","=",false]]]
order_byNoresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["keyword_data.keyword_info.competition,desc"] default rule: ["ranked_serp_element.serp_item.rank_group,asc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["keyword_data.keyword_info.search_volume,desc","keyword_data.keyword_info.cpc,desc"]
item_typesNodisplay results by item type indicates the type of search results included in the response
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States
include_subdomainsNoInclude keywords from subdomains
include_clickstream_dataNoInclude or exclude data from clickstream-based metrics in the result

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already indicate readOnlyHint=true, idempotentHint=true. The description adds value by specifying the returned data types (SERP elements, impressions, monthly searches), which provides behavioral context beyond annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the main purpose, and contains no unnecessary words or repetition. It efficiently communicates the key functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 10 parameters but no output schema, the description provides a reasonable overview of what is returned. It does not cover all details like filtering or sorting, but the schema descriptions cover those. The description is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description does not add new parameter information beyond what is in the schema. It gives an overview of returned data but not parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides a list of keywords a domain or webpage is ranking for, including SERP elements, impressions, and monthly searches. The verb 'provide you with the list' and specific resource 'keywords that any domain or webpage is ranking for' make the purpose very clear.

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

Usage Guidelines2/5

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

The description does not provide any guidance on when to use this tool versus alternatives, such as when to use 'dataforseo_labs_google_keywords_for_site' or 'serp_organic_live_advanced'. There are no explicit conditions or exclusions mentioned.

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

dataforseo_labs_google_relevant_pagesDataForSEO Labs Google Relevant PagesA
Read-onlyIdempotent

This endpoint will provide you with rankings and traffic data for the web pages of the specified domain. You will be able to review each page’s ranking distribution and estimated monthly traffic volume from both organic and paid searches.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of keywords to return
offsetNooffset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
targetYestarget domain
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like Use % with like/not_like/ilike/not_ilike as a wildcard. Examples: Single: ["metrics.organic.count", ">", 50] Combined: [["metrics.organic.pos_1", "<>", 0], "and", ["metrics.organic.impressions_etv", ">=", "10"]] Nested: [[["metrics.organic.count", ">=", 50], "and", ["metrics.organic.pos_1", "in", [1, 5]]], "or", ["metrics.organic.etv", ">=", "100"]]
order_byNoresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to specify a sorting type example: ["metrics.paid.etv,asc"] Note: you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["metrics.organic.etv,desc","metrics.paid.count,asc"] default rule: ["metrics.organic.count,desc"]
item_typesNodisplay results by item type indicates the type of search results included in the response
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States
ignore_synonymsNoignore highly similar keywords, if set to true, results will be more accurate
exclude_top_domainsNoindicates whether to exclude world’s largest websites optional field default value: false set to true if you want to get highly-relevant competitors excluding the top websites
include_clickstream_dataNoInclude or exclude data from clickstream-based metrics in the result

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description adds minimal behavioral context. It mentions 'organic and paid searches' but not specifics like 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, 26 words, direct and front-loaded. No redundant phrases; every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description provides a high-level overview of return data (rankings, traffic). It omits details on pagination and filtering but covers the essential purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the description does not need to elaborate on parameters. It mentions 'specified domain' (target) but adds no extra meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'provide' and specifies the resource: 'web pages of the specified domain'. It distinguishes from similar tools by focusing on page-level rankings and traffic data for a single domain, contrasting with keyword-focused siblings.

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

Usage Guidelines2/5

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. The description does not mention prerequisites, exclusions, or comparisons to other DataForSEO Labs endpoints.

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

dataforseo_labs_google_serp_competitorsDataForSEO Labs Google SERP CompetitorsA
Read-onlyIdempotent

This endpoint will provide you with a list of domains ranking for the keywords you specify. You will also get SERP rankings, rating, estimated traffic volume, and visibility values the provided domains gain from the specified keywords.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of keywords to return
offsetNooffset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like Use % with like/not_like/ilike/not_ilike as a wildcard. Examples: Single: ["median_position", "in", [1, 10]] Combined: [["median_position", "in", [1, 10]], "and", ["domain", "not_like", "%wikipedia.org%"]] Nested: [["domain", "not_like", "%wikipedia.org%"], "and", [["relevant_serp_items", ">", 0], "or", ["median_position", "in", [1, 10]]]]
keywordsYeskeywords array required field the results will be based on the keywords you specify in this array UTF-8 encoding; the keywords will be converted to lowercase format; you can specify the maximum of 200 keywords
order_byNoresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order the comma is used as a separator example: ["avg_position,asc"] default rule: ["rating,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["avg_position,asc","etv,desc"]
item_typesNodisplay results by item type indicates the type of search results included in the response
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States
include_subdomainsNoInclude keywords from subdomains

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, etc., so safety is clear. The description adds context about the output (ratings, traffic, visibility) but does not disclose additional behavioral traits like rate limits, authentication needs, or handling of large keyword arrays (max 200 stated in schema but not highlighted).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that conveys the core functionality and output. It is front-loaded and contains no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of detailed schema and annotations, the description covers the primary output adequately. However, it omits mention of pagination (offset/limit) and result filtering by item types, which are important for usage. Still, most necessary context is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are well-documented. The description does not add extra semantic meaning beyond what the schema already provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it provides 'a list of domains ranking for the keywords you specify' along with specific metrics (SERP rankings, rating, traffic, visibility). It distinguishes from sibling tools like dataforseo_labs_google_related_keywords or dataforseo_labs_google_competitors_domain by focusing on keyword-based competitor analysis.

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

Usage Guidelines2/5

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

The description lacks guidance on when to use this tool versus other similar tools. It does not mention scenarios, prerequisites, or alternatives. For example, when to use this over dataforseo_labs_google_competitors_domain (which analyzes by domain) is not addressed.

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

dataforseo_labs_google_subdomainsDataForSEO Labs Google SubdomainsA
Read-onlyIdempotent

This endpoint will provide you with a list of subdomains of the specified domain, along with the ranking distribution across organic and paid search. In addition to that, you will also get the estimated traffic volume of subdomains based on search volume.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of keywords to return
offsetNooffset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
targetYestarget domain
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like Use % with like/not_like/ilike/not_ilike as a wildcard. Examples: Single: ["metrics.organic.count", ">", 50] Combined: [["metrics.organic.pos_1", "<>", 0], "and", ["metrics.organic.impressions_etv", ">=", "10"]] Nested: [[["metrics.organic.count", ">=", 50], "and", ["metrics.organic.pos_1", "in", [1, 5]]], "or", ["metrics.organic.etv", ">=", "100"]]
order_byNoresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to specify a sorting type example: ["metrics.paid.etv,asc"] Note: you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["metrics.organic.etv,desc","metrics.paid.count,asc"] default rule: ["metrics.organic.count,desc"]
item_typesNodisplay results by item type indicates the type of search results included in the response
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States
ignore_synonymsNoignore highly similar keywords, if set to true, results will be more accurate
include_clickstream_dataNoInclude or exclude data from clickstream-based metrics in the result

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already indicate read-only, open-world, idempotent behavior. The description adds context about the data returned (ranking distribution, traffic volume) but does not disclose additional behavioral traits beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with clear, front-loaded content. Every sentence adds value with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 10 parameters and no output schema, the description provides a good overview but could be more complete by mentioning the purpose of each parameter or the structure of the response. However, it is sufficient for a basic understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds no new parameter semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides a list of subdomains with ranking distribution across organic and paid search, and estimated traffic volume. It uses specific verbs and resources, and distinct from sibling tools like keyword suggestions or competitive analysis.

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

Usage Guidelines2/5

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

The description lacks explicit guidance on when to use this tool vs alternatives. No prerequisites, exclusions, or comparisons to sibling tools are mentioned.

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

dataforseo_labs_google_top_searchesDataForSEO Labs Google Top SearchesB
Read-onlyIdempotent

The Top Searches endpoint of DataForSEO Labs API can provide you with over 7 billion keywords from the DataForSEO Keyword Database. Each keyword in the API response is provided with a set of relevant keyword data with Google Ads metrics

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of keywords to return
offsetNooffset in the results array of returned keywords optional field default value: 0 if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like Use % with like/not_like/ilike/not_ilike as a wildcard. Examples: Single: ["keyword_info.search_volume", ">", 0] Combined: [["keyword_info.search_volume", "in", [0, 1000]], "and", ["keyword_info.competition_level", "=", "LOW"]] Nested: [["keyword_info.search_volume", ">", 100], "and", [["keyword_info.cpc", "<", 0.5], "or", ["keyword_info.high_top_of_page_bid", "<=", 0.5]]]
order_byNoresuresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting type example: ["keyword_info.competition,desc"] default rule: ["keyword_info.search_volume,desc"] note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["keyword_info.search_volume,desc","keyword_info.cpc,desc"]
language_codeNolanguage code required field example: enen
location_nameNofull name of the location required field only in format "Country" (not "City" or "Region") example: 'United Kingdom', 'United States', 'Canada'United States
include_clickstream_dataNoInclude or exclude data from clickstream-based metrics in the result

TDQS

B3.3/5.0
Behavior4/5

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context about the massive keyword count (7 billion) and the inclusion of Google Ads metrics, which are not in annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys the tool's core purpose and output. It is front-loaded and not verbose, but could benefit from slight restructuring to separate key points.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite 7 parameters and no output schema, the description omits details about pagination, filtering, ordering, and the exact metrics returned. The agent would need to infer these from the input schema, which is insufficient for complete understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All 7 parameters have descriptions in the schema (100% coverage), so the baseline is 3. The description does not add any parameter-specific details beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides 'over 7 billion keywords' from the DataForSEO Keyword Database with 'Google Ads metrics', specifying the resource and output. It lacks explicit differentiation from sibling keyword tools like 'related_keywords' or 'keyword_suggestions', but the term 'top searches' implies a broad list.

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

Usage Guidelines2/5

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

No guidance on when to use this tool over alternatives. No mention of prerequisites, exclusions, or appropriate contexts. The description is purely declarative.

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

dataforseo_labs_search_intentDataForSEO Labs Search IntentA
Read-onlyIdempotent

This endpoint will provide you with search intent data for up to 1,000 keywords. For each keyword that you specify when setting a task, the API will return the keyword's search intent and intent probability. Besides the highest probable search intent, the results will also provide you with other likely search intent(s) and their probability. Based on keyword data and search results data, our system has been trained to detect four types of search intent: informational, navigational, commercial, transactional.

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordsYestarget keywords required field UTF-8 encoding maximum number of keywords you can specify in this array: 1000
language_codeNolanguage code required field Note: this endpoint currently supports the following languages only: ar, zh-TW, cs, da, nl, en, fi, fr, de, he, hi, it, ja, ko, ms, nb, pl, pt, ro, ru, es, sv, th, uk, vi, bg, hr, sr, sl, bsen

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context about the output (intent types, probability) and the training basis, going beyond the annotations to explain behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and single-paragraph, with no wasted words. It could be slightly more structured but is efficient and front-loads the purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with 2 parameters and no output schema, the description adequately explains the output and functionality. Annotations provide safety context. It is complete for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the description adds little beyond what the schema already provides. It mentions the maximum number of keywords and language support, but these are also in the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it provides search intent data for up to 1000 keywords, returning intent and probability. It distinguishes from sibling tools by focusing specifically on search intent, which is unique among the listed siblings.

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

Usage Guidelines3/5

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

The description explains what the tool does but does not provide explicit guidance on when to use it versus alternatives like keyword suggestions or search volume tools. Usage is implied but no exclusions or comparisons are given.

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

domain_analytics_technologies_available_filtersDomain Analytics Technologies Available FiltersB
Read-onlyIdempotent

Here you will find all the necessary information about filters that can be used with DataForSEO Technologies API endpoints.

Please, keep in mind that filters are associated with a certain object in the result array, and should be specified accordingly.

ParametersJSON Schema
NameRequiredDescriptionDefault
toolNoThe name of the tool to get filters for

TDQS

B3.1/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, ensuring the agent knows it's safe. The description adds that filters are associated with a specific object in the result array, which provides behavioral context beyond the annotations. However, it does not cover other traits like response structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded, comprising two sentences. While the first sentence could be more concise (e.g., 'Returns available filters for DataForSEO Technologies API endpoints'), it is not overly verbose and lacks irrelevant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has one parameter, no output schema, and simple annotations. The description does not specify what the response format looks like or how the filters are structured, leaving the agent without crucial context. Given the available richness of annotations, the description should at least hint at the output structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single 'tool' parameter, which is described as 'The name of the tool to get filters for'. The tool description does not add further meaning to this parameter, 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.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states that the tool provides information about filters for DataForSEO Technologies API endpoints, and the title specifies 'Available Filters'. This clearly indicates the purpose and distinguishes it from sibling filter tools for other APIs. However, it could be more action-oriented (e.g., 'Returns available filters').

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

Usage Guidelines2/5

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 vs alternatives like dataforseo_labs_available_filters or backlinks_available_filters. It does not mention that this tool is specifically for the Technologies API or exclude other use cases.

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

domain_analytics_technologies_domain_technologiesDomain Analytics Technologies Domain TechnologiesB
Read-onlyIdempotent

Using this endpoint you will get a list of technologies used in a particular domain

ParametersJSON Schema
NameRequiredDescriptionDefault
targetYestarget domain required field domain name of the website to analyze Note: results will be returned for the specified domain only

TDQS

B3.3/5.0
Behavior2/5

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, covering safety and idempotency. The description adds no behavioral details beyond what is in the schema (e.g., 'results returned for specified domain only' is already in the parameter description). It lacks disclosure of potential behaviors 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that communicates the core purpose without unnecessary words or structure. It is front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description provides the essential purpose. However, it lacks details about the output format (e.g., structure of the technology list, whether it includes versions or categories) and does not mention potential limitations, making it only minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter 'target', which includes its own description. The tool description essentially restates the same concept ('list of technologies used in a particular domain') without adding new semantic meaning, meeting the baseline for high coverage but not exceeding it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a list of technologies used for a specific domain, using a precise verb+resource structure. It distinguishes itself from sibling tools like domain_analytics_whois_overview (whois) and domain_analytics_technologies_available_filters (filters).

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

Usage Guidelines2/5

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. It does not specify conditions, prerequisites, or mention when not to use it, leaving the agent without decision context despite many sibling tools in the domain analytics category.

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

domain_analytics_whois_available_filtersDomain Analytics WHOIS Available FiltersC
Read-onlyIdempotent

Here you will find all the necessary information about filters that can be used with DataForSEO WHOIS API endpoints.

Please, keep in mind that filters are associated with a certain object in the result array, and should be specified accordingly.

ParametersJSON Schema
NameRequiredDescriptionDefault
toolNoThe name of the tool to get filters for

TDQS

C2.6/5.0
Behavior2/5

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

The description adds no behavioral information such as the return format, error handling, or rate limits. Annotations (readOnlyHint=true, idempotentHint=true) already convey safety, but the description does not elaborate on what the tool does when a valid or invalid tool name is provided. No additional value beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short (two sentences) and to the point. However, it lacks a front-loaded, clear action statement. The first sentence is passive ('Here you will find...') rather than active. It is concise but could be more direct and structured. Still, it avoids unnecessary verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (one optional parameter, no output schema), the description should at least indicate the expected output structure (e.g., 'returns an array of filter definitions'). The current description only hints at the content orientation, leaving an agent uncertain about what exactly is returned. This is a notable gap for a tool that is mean to provide 'information about filters'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides a clear description for the single parameter 'tool' ('The name of the tool to get filters for'), achieving 100% schema coverage. The description adds no further semantics about the parameter, such as accepted values or examples. Baseline score of 3 is appropriate as the schema already covers the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states that the tool provides 'information about filters' for WHOIS API endpoints, but it does not explicitly state the action (e.g., 'get available filters') or specify the input parameter's role. The verb 'find' is ambiguous, and the purpose is inferable but not clearly articulated. It adequately distinguishes from siblings via the name, but the description alone is vague.

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

Usage Guidelines2/5

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 'backlinks_available_filters' or 'domain_analytics_technologies_available_filters'. The description lacks any mention of context, prerequisites, or when not to use the tool. An AI agent would have no basis to choose this tool over similar ones.

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

domain_analytics_whois_overviewDomain Analytics WHOIS OverviewB
Read-onlyIdempotent

This endpoint will provide you with Whois data enriched with backlink stats, and ranking and traffic info from organic and paid search results. Using this endpoint you will be able to get all these data for the domains matching the parameters you specify in the request

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNothe maximum number of returned domains
offsetNooffset in the results array of returned businesses optional field default value: 0 if you specify the 10 value, the first ten entities in the results array will be omitted and the data will be provided for the successive entities
filtersNoArray-based filter expression. A single condition is a 3-element array: [field, operator, value]. Combine conditions with ["and"|"or"] between them: [condition, "and", condition]. Max 8 filters. Operators: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like, match, not_match Use % with like/not_like as a wildcard. Example: Single: ["rating.value", ">", 3]
order_byNoresults sorting rules optional field you can use the same values as in the filters array to sort the results possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order you should use a comma to set up a sorting parameter example: ["rating.value,desc"]note that you can set no more than three sorting rules in a single request you should use a comma to separate several sorting rules example: ["rating.value,desc","rating.votes_count,desc"]
is_claimedNoindicates whether the business is verified by its owner on Google Maps

TDQS

B3.2/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false. The description adds value by listing the enriched data types (backlink stats, ranking, traffic info), but doesn't disclose additional behavioral traits beyond what annotations cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core functionality. Efficient and to the point, though could be slightly more structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately explains what data is returned (Whois, backlink stats, ranking, traffic). It covers the main outputs, though lacks detail on output structure or filtering behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters are well-documented. The description adds no parameter-specific meaning beyond 'matching the parameters you specify'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it provides Whois data enriched with backlink stats, ranking, and traffic info. It distinguishes from siblings by focusing on WHOIS enrichment, though it could be more explicit about what makes it unique among domain analytics tools.

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

Usage Guidelines2/5

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. It only says 'for domains matching parameters', but doesn't mention when not to use it or suggest other tools for different use cases.

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

kw_data_google_ads_locationsKeywords Data Google Ads LocationsB
Read-onlyIdempotent

Utility tool for kw_data_google_ads_search_volume to get list of availible locations.

ParametersJSON Schema
NameRequiredDescriptionDefault
location_nameNoName of location or it`s part.
location_typeNoType of location. Possible variants: 'TV Region','Postal Code','Neighborhood','Governorate','National Park','Quarter','Canton','Airport','Okrug','Prefecture','City','Country','Province','Barrio','Sub-District','Congressional District','Municipality District','district','DMA Region','Union Territory','Territory','Colloquial Area','Autonomous Community','Borough','County','State','District','City Region','Commune','Region','Department','Division','Sub-Ward','Municipality','University'
country_iso_codeYesISO 3166-1 alpha-2 country code, for example: US, GB, MT

TDQS

B3.4/5.0
Behavior2/5

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe, read-only operation. The description adds no additional behavioral context beyond stating it retrieves a list. There is no mention of pagination, rate limits, or other traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that effectively communicates the tool's role. However, it contains a typo ('availible' instead of 'available'), which slightly detracts from clarity. Overall, it is appropriately sized and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple nature of the tool (no output schema, three well-described parameters), the description provides the essential context of being a utility for another tool. It is adequate but could be more complete by mentioning the return format or the scope of location listing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the input schema already describes all three parameters clearly, including examples for country_iso_code and enumerated values for location_type. The description does not add any extra meaning or context for the parameters, so it meets the baseline but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: it is a utility for 'kw_data_google_ads_search_volume' to retrieve a list of available locations. The verb ('get list') and resource ('locations') are specific, and it distinguishes itself by being a supporting tool for a sibling.

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

Usage Guidelines3/5

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

The description implies usage when location data is needed for 'kw_data_google_ads_search_volume', but it does not provide explicit guidance on when to use this tool versus other location-related siblings like 'serp_locations' or 'ai_opt_kw_data_loc_and_lang'. Usage context is implied but not clearly differentiated.

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

kw_data_google_ads_search_volumeKeywords Data Google Ads Search VolumeB
Read-onlyIdempotent

Get search volume data for keywords from Google Ads

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordsYesArray of keywords to get search volume for
language_codeNoLanguage two-letter ISO code (e.g., 'en'). optional field
location_nameNofull name of the location required field Location format - hierarchical, comma-separated (from most specific to least) Can be one of: 1. Country only: "United States" 2. Region,Country: "California,United States" 3. City,Region,Country: "San Francisco,California,United States"United States

TDQS

B3.1/5.0
Behavior2/5

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds no additional behavioral context, such as data freshness, result format, or any side effects. Since annotations are rich, the description could have added value but did not.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 8 words, highly efficient and front-loaded. Every word is necessary, and there is no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple lookup tool, the description is minimally adequate with good parameter documentation in the schema. However, there is no mention of return values or data details, which would improve completeness. No output schema exists, so the description could compensate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all three parameters are documented. The description does not repeat parameter details, which is acceptable; however, it adds no extra meaning beyond the schema, such as constraints or examples. Baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action and resource: 'Get search volume data for keywords from Google Ads'. It is specific and matches the tool name, but does not explicitly differentiate from sibling tools like 'kw_data_google_trends_categories' or 'dataforseo_labs_google_keyword_suggestions'.

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

Usage Guidelines2/5

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. It lacks any context for selection, such as mentioning when search volume is needed compared to related keywords or trend data.

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

merchant_amazon_asin_live_advancedMerchant Amazon ASIN Live AdvancedA
Read-onlyIdempotent

Get detailed product information from Amazon by ASIN (Amazon Standard Identification Number). Returns product title, price, description, images, reviews summary, seller info, shipping options, and other product attributes for the specified ASIN.

ParametersJSON Schema
NameRequiredDescriptionDefault
asinYesproduct ID required field unique product identifier (ASIN) in Amazon you can receive the asin parameter by making a separate request to the merchant_amazon_products_live_advanced
language_codeNolanguage code required field example: "en_US" supported languages: ar_SA, ar_AE, zh_CN, zh_TW, cs_CZ, nl_NL, en_AU, en_CA, en_IN, en_AE, en_GB, en_US, fr_CA, fr_FR, de_DE, he_IL, hi_IN, it_IT, ja_JP, ko_KR, pl_PL, pt_BR, es_MX, es_ES, es_US, sv_SE, tr_TRen_US
location_nameNofull name of the location required field Location format - hierarchical, comma-separated (from most specific to least) Can be one of: 1. Country only: "United States" 2. Postal Code,Region,Country: "90210,California,United States"United States

TDQS

A3.8/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds limited behavioral insight beyond listing returned data. No mention of side effects, rate limits, or authorization beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with front-loaded main purpose followed by a clear list of returned data categories. No redundancy or wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description adequately lists the expected return fields. Parameters are fully documented in schema. Lacks only explicit mention of error cases or pagination, but sufficient for common use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed parameter descriptions (e.g., supported languages, location format). The description does not add further parameter meaning beyond the schema, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves detailed product information from Amazon by ASIN, listing specific data categories (title, price, etc.). This distinguishes it from sibling tools like merchant_amazon_products_live_advanced, which likely returns product search results.

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

Usage Guidelines3/5

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

The description implies usage through the asin parameter description mentioning it can be obtained from merchant_amazon_products_live_advanced, but lacks explicit when-to-use or when-not-to-use guidance compared to alternatives. No exclusions or 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.

merchant_amazon_locationsMerchant Amazon LocationsA
Read-onlyIdempotent

Utility tool for Amazon merchant tools (merchant_amazon_asin_live_advanced, merchant_amazon_sellers_live_advanced, merchant_amazon_products_live_advanced) to get the list of available locations with their location_code and location_name values. You can optionally filter the list by country ISO code.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNomaximum number of locations to return
offsetNooffset in the results array of returned locations
countryNoISO 3166-1 alpha-2 country code to filter locations by optional field example: "US", "GB", "DE" if omitted, the full list of available Amazon locations is returned
location_name_containsNofilter locations by a substring match on location_name optional field example: "New York", "London" if omitted, no name filtering is applied

TDQS

A3.7/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds that it returns location_code and location_name, but does not disclose pagination behavior, default limits, or other operational details. With strong annotation coverage, this is acceptable but not exceptional.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences efficiently communicate purpose and optional filtering. The list of sibling tools in parentheses adds context without being overly verbose. Could be slightly more structured (e.g., separating utility statement from filtering options), but overall very concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple lookup tool with fully described parameters and robust annotations, the description covers the essential purpose and optional filtering. No output schema exists, but the return type (list of locations with code and name) is implied. Complete enough for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions for all four parameters (limit, offset, country, location_name_contains). The description mentions optional country filtering but does not add new semantic meaning beyond what the schema already provides. Baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it's a utility to get available locations for Amazon merchant tools, specifying it returns location_code and location_name. It distinguishes from sibling tools by explicitly listing the associated Amazon merchant tools (merchant_amazon_asin_live_advanced, etc.), making its scope unambiguous.

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

Usage Guidelines3/5

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

Describes when to use (when needing location codes for Amazon merchant tools) and optional country filtering, but does not explicitly state when not to use or provide comparisons to other location tools like serp_locations or kw_data_google_ads_locations. Guidance is adequate but lacks exclusions.

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

merchant_amazon_products_live_advancedMerchant Amazon Products Live AdvancedA
Read-onlyIdempotent

Search Amazon products by keyword and get the list of matching items. Returns product titles, ASINs, prices, ratings, images, sponsored placements, and other SERP-like results for the specified keyword on Amazon.

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordYeskeyword required field the keyword that will be searched for on Amazon; example: "shoes"
sort_byNoresults sorting rules optional field supported values: relevance, price_low_to_high, price_high_to_low, featured, avg_customer_review, newest_arrival example: "relevance"
price_maxNomaximum product price optional field maximum price of the returned products listed on Amazon for the specified query example: 100 Note: if you specify price_max, the search_param parameter will be ignored
price_minNominimum product price optional field minimum price of the returned products listed on Amazon for the specified query example: 5 Note: if you specify price_min, the search_param parameter will be ignored
departmentNoamazon product department optional field specify one of the supported amazon departments for extracting product listings
language_codeNolanguage code required field example: "en_US" supported languages: ar_SA, ar_AE, zh_CN, zh_TW, cs_CZ, nl_NL, en_AU, en_CA, en_IN, en_AE, en_GB, en_US, fr_CA, fr_FR, de_DE, he_IL, hi_IN, it_IT, ja_JP, ko_KR, pl_PL, pt_BR, es_MX, es_ES, es_US, sv_SE, tr_TRen_US
location_nameNofull name of the location required field Location format - hierarchical, comma-separated (from most specific to least) Can be one of: 1. Country only: "United States" 2. Postal Code,Region,Country: "90210,California,United States"United States

TDQS

A3.8/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description's contribution to behavioral transparency is limited. It adds value by listing returned fields (titles, ASINs, prices, etc.), but does not disclose potential behaviors like pagination, rate limits, or error handling. The description does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two concise sentences that front-load the main purpose and immediately list return values. There is no extraneous information; every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lists key return fields (titles, ASINs, prices, ratings, images, sponsored placements) partially compensating for the lack of an output schema. However, it omits details like pagination, result limits, or error conditions. For a search tool with comprehensive parameter schemas, this is fairly complete but not fully thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter is well-described in the schema (e.g., keyword: 'the keyword that will be searched for on Amazon'). The description adds no additional parameter semantics beyond what the schema provides, resulting in a baseline score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly identifies the action ('Search Amazon products by keyword') and the resource ('Amazon products'). The name 'merchant_amazon_products_live_advanced' and sibling context (e.g., merchant_amazon_asin_live_advanced) further distinguish it as a keyword-based product search, distinguishing it from ASIN-specific or seller-specific tools.

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

Usage Guidelines3/5

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

The description implies usage when one wants to search Amazon products by keyword, but it does not provide explicit when-to-use/when-not-to-use guidance or mention alternative sibling tools (e.g., merchant_amazon_asin_live_advanced). The context is clear but lacks exclusions or comparative guidance.

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

merchant_amazon_sellers_live_advancedMerchant Amazon Sellers Live AdvancedA
Read-onlyIdempotent

Get the list of sellers offering a specific Amazon product (by ASIN). Returns seller names, ratings, prices, shipping conditions, and product offers available from each merchant for the requested ASIN.

ParametersJSON Schema
NameRequiredDescriptionDefault
asinYesproduct identifier (ASIN) on Amazon required field the unique identifier of the product on Amazon; example: "B07D528W98"
language_codeNolanguage code required field example: "en_US" supported languages: ar_SA, ar_AE, zh_CN, zh_TW, cs_CZ, nl_NL, en_AU, en_CA, en_IN, en_AE, en_GB, en_US, fr_CA, fr_FR, de_DE, he_IL, hi_IN, it_IT, ja_JP, ko_KR, pl_PL, pt_BR, es_MX, es_ES, es_US, sv_SE, tr_TRen_US
location_nameNofull name of the location required field Location format - hierarchical, comma-separated (from most specific to least) Can be one of: 1. Country only: "United States" 2. Postal Code,Region,Country: "90210,California,United States"United States

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already provide strong behavioral hints: readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description only reiterates that it returns data, adding no new traits like rate limits or pagination. It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences long, front-loaded with the main purpose, and contains no redundant information. It is efficient but could be slightly more structured (e.g., bullet items for returned fields).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers what the tool returns (seller names, ratings, etc.) and implies a single ASIN lookup. However, it does not mention output format, pagination, or any limits. For a parameter-rich tool with no output schema, it is adequate but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter already having a clear description in the input schema. The tool description adds no extra meaning or context for the parameters beyond what is already present.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get'), identifies the resource ('list of sellers offering a specific Amazon product'), and specifies the key parameter (ASIN). It also lists the returned fields, clearly distinguishing this tool from sibling tools like merchant_amazon_asin_live_advanced which likely returns product details.

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

Usage Guidelines3/5

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

The description implies usage when one needs seller info for a given ASIN, but it does not explicitly state when to use this tool over alternatives (e.g., merchant_amazon_products_live_advanced). No exclusions or context about required permissions are provided.

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

on_page_content_parsingOn Page Content ParsingA
Read-onlyIdempotent

This endpoint allows parsing the content on any page you specify and will return the structured content of the target page, including link URLs, anchors, headings, and textual content.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesURL of the page to parse
accept_languageNoAccept-Language header value
custom_user_agentNoCustom User-Agent header
enable_javascriptNoEnable JavaScript rendering

TDQS

A3.8/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it parses content and returns structured data, which is consistent but does not disclose additional behavioral traits such as network requests, potential latency, or handling of JavaScript rendering beyond what parameters suggest.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the core action and result. Every word serves a purpose, with no redundancy or filler. It is optimally concise for an agent to quickly grasp the tool's function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters (1 required) and no output schema, the description provides useful context by listing the types of structured content returned (links, anchors, headings, text). This helps agents anticipate data shape. However, it omits details on error handling, rate limits, or interaction with website consent/robots.txt.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with clear descriptions for all four parameters. The description adds no extra meaning beyond summarizing the output; it does not clarify parameter syntax, defaults, or constraints. Baseline 3 is appropriate as schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'parsing', the resource 'content on any page', and the output 'structured content including link URLs, anchors, headings, and textual content'. It distinguishes from sibling tools like 'on_page_instant_pages' or 'serp_organic_live_advanced' by focusing on page content parsing rather than SERP or analysis.

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

Usage Guidelines3/5

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

The description implies usage for extracting structured content from any web page but provides no explicit guidance on when to use this tool versus siblings like dataforseo_labs tools or serp tools. No exclusions or alternative recommendations are given, leaving the agent to infer context.

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

on_page_instant_pagesOn Page Instant PagesB
Read-onlyIdempotent

Using this function you will get page-specific data with detailed information on how well a particular page is optimized for organic search

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesURL to analyze
custom_jsNoCustom JavaScript code to execute
accept_languageNolanguage header for accessing the website all locale formats are supported (xx, xx-XX, xxx-XX, etc.) Note: if you do not specify this parameter, some websites may deny access; in this case, pages will be returned with the "type":"broken in the response array
custom_user_agentNoCustom User-Agent header
enable_javascriptNoEnable JavaScript rendering

TDQS

B3.1/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds 'get page-specific data' which aligns but does not add new behavioral context beyond what annotations provide. Hence, a 3 is fair.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the purpose. It is concise with no wasted words, but the phrasing 'Using this function you will get' is slightly verbose. Still effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 5 parameters and no output schema, the description should provide more context about the returned data, expected URL format, or constraints. It only vaguely mentions 'detailed information' without specifics, leaving the agent underinformed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with all 5 parameters documented. The tool description adds no additional parameter information beyond the schema. Baseline is 3, and no extra value is provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'get' and the resource 'page-specific data on how well a page is optimized for organic search', which is specific and distinct from siblings like on_page_content_parsing or on_page_lighthouse. However, it does not explicitly differentiate from all siblings, so a 4 is appropriate.

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

Usage Guidelines2/5

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. No explicit context about prerequisites, exclusions, or preferred use cases is given, making it minimal.

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

on_page_lighthouseOn Page LighthouseC
Read-onlyIdempotent

The OnPage Lighthouse API is based on Google’s open-source Lighthouse project for measuring the quality of web pages and web apps.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesURL of the page to parse
full_dataNoReturn the complete API response instead of a reduced version
accept_languageNoAccept-Language header value
custom_user_agentNoCustom User-Agent header
enable_javascriptNoEnable JavaScript rendering

TDQS

C2.7/5.0
Behavior2/5

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

Annotations already declare the tool as read-only, non-destructive, and idempotent. The description does not add any behavioral context beyond stating its Lighthouse foundation. No mention of rate limits, required permissions, or response characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise but overly brief for a tool with 5 parameters and no output schema. It sacrifices informativeness for brevity, leaving the agent with minimal actionable guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 parameters, no output schema) and many sibling tools, the description is incomplete. It does not describe return values, interpretation of results, or how to use parameters effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All 5 parameters have descriptions in the schema, achieving 100% coverage. The description does not elaborate on any parameter, but with full schema coverage, a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool measures web page quality using Google's Lighthouse, which distinguishes it from sibling tools like 'on_page_content_parsing'. However, it lacks specificity about which quality metrics (performance, accessibility, etc.) are included.

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

Usage Guidelines2/5

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. Sibling tools like 'on_page_content_parsing' or various SERP tools are not mentioned, leaving the agent to infer usage context.

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

serp_locationsSERP LocationsC
Read-onlyIdempotent

Utility tool for serp_organic_live_advanced to get list of availible locations.

ParametersJSON Schema
NameRequiredDescriptionDefault
location_nameNoName of location or it`s part.
location_typeNoType of location. Possible variants: 'TV Region','Postal Code','Neighborhood','Governorate','National Park','Quarter','Canton','Airport','Okrug','Prefecture','City','Country','Province','Barrio','Sub-District','Congressional District','Municipality District','district','DMA Region','Union Territory','Territory','Colloquial Area','Autonomous Community','Borough','County','State','District','City Region','Commune','Region','Department','Division','Sub-Ward','Municipality','University'
search_engineNosearch engine name, one of: google, yahoo, bing.google
country_iso_codeYesISO 3166-1 alpha-2 country code, for example: US, GB, MT

TDQS

C2.9/5.0
Behavior2/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, indicating a safe, non-destructive read operation. The description adds minimal context beyond calling it a 'utility tool' and 'get list', which does not significantly enhance the behavioral understanding provided by the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence, efficient and front-loaded. However, it contains a typo ('availible') and could be slightly expanded for clarity without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

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, the description partially addresses the output by mentioning 'get list of available locations', but does not specify the structure or fields of the returned data. For a utility tool with 4 parameters, this is adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already fully documents all four parameters. The description does not add extra meaning or context for the parameters beyond what the schema provides. Baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it is a utility tool for serp_organic_live_advanced to get a list of available locations. It has a specific verb+resource combination. However, it could be more specific about the type of locations (e.g., SERP locations for Google search).

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

Usage Guidelines2/5

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

The description implies usage as a utility for serp_organic_live_advanced, but it does not provide explicit guidance on when to use this tool vs. alternative location tools like serp_youtube_locations or kw_data_google_ads_locations. No exclusions or when-not advice is given.

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

serp_organic_live_advancedSERP Organic Live AdvancedB
Read-onlyIdempotent

Get organic search results for a keyword in specified search engine

ParametersJSON Schema
NameRequiredDescriptionDefault
depthNoparsing depth optional field number of results in SERP
deviceNodevice type optional field can take the values:desktop, mobile default value: desktopdesktop
keywordYesSearch keyword
language_codeYessearch engine language code (e.g., 'en')
location_nameNofull name of the location required field Location format - hierarchical, comma-separated (from most specific to least) Can be one of: 1. Country only: "United States" 2. Region,Country: "California,United States" 3. City,Region,Country: "San Francisco,California,United States"United States
search_engineNosearch engine name, one of: google, yahoo, bing.google
max_crawl_pagesNopage crawl limit optional field number of search results pages to crawl max value: 100 Note: the max_crawl_pages and depth parameters complement each other
people_also_ask_click_depthNoclicks on the corresponding element specify the click depth on the people_also_ask element to get additional people_also_ask_element items;

TDQS

B3.3/5.0
Behavior3/5

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the agent knows it's a safe, idempotent, read-only operation. The description adds no extra behavioral context beyond stating the basic function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no redundant information. Every word is necessary and contributes to understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 8 parameters with full schema coverage and annotations, the description is minimally adequate. However, it could mention that results are paginated (via max_crawl_pages) or that it returns structured SERP data, but the schema covers this.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description does not add any meaning beyond what the schema already provides. For instance, 'depth' is described in the schema, and the description does not elaborate further.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns organic search results for a keyword in a specified search engine. It is concise and distinguishes the tool from sibling tools that deal with other data (e.g., backlinks, YouTube, keyword suggestions). However, it does not elaborate on 'advanced' features.

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

Usage Guidelines2/5

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 dataforseo_labs or AI tools. The description does not mention any use cases, prerequisites, or conditions.

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

serp_youtube_locationsSERP YouTube LocationsA
Read-onlyIdempotent

Utility tool to get list of available locations for: serp_youtube_organic_live_advanced, serp_youtube_video_info_live_advanced, serp_youtube_video_comments_live_advanced, serp_youtube_video_subtitles_live_advanced.

ParametersJSON Schema
NameRequiredDescriptionDefault
location_nameNoName of location or it`s part.
location_typeNoType of location. Possible variants: 'TV Region','Postal Code','Neighborhood','Governorate','National Park','Quarter','Canton','Airport','Okrug','Prefecture','City','Country','Province','Barrio','Sub-District','Congressional District','Municipality District','district','DMA Region','Union Territory','Territory','Colloquial Area','Autonomous Community','Borough','County','State','District','City Region','Commune','Region','Department','Division','Sub-Ward','Municipality','University'
country_iso_codeYesISO 3166-1 alpha-2 country code, for example: US, GB, MT

TDQS

A4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false, so the agent knows it's a safe, idempotent read. The description adds no further behavioral context (e.g., return format, pagination, or limits), but the annotations are sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence of 20 words, front-loaded with the core purpose. No wasted words. Efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a utility tool returning location lists, the description plus schema and annotations cover the essential aspects. The lack of output schema or return format detail is a minor gap, but typical for such tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter having a clear description. The description does not add any parameter-level guidance beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states it returns a list of available locations for four specific YouTube SERP tools. The verb 'get' and resource 'list of available locations' are clear. It effectively distinguishes itself as a utility tool for those sibling tools.

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

Usage Guidelines4/5

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

The description identifies exactly which tools require this location data, guiding the agent to use this tool before those. While it does not specify when not to use it or contrast with 'serp_locations', the context of being a prerequisite utility is clear.

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

serp_youtube_organic_live_advancedSERP YouTube Organic Live AdvancedB
Read-onlyIdempotent

provides top 20 blocks of youtube search engine results for a keyword

ParametersJSON Schema
NameRequiredDescriptionDefault
osNodevice operating system optional field if you specify desktop in the device field, choose from the following values: windows, macos default value: windows if you specify mobile in the device field, choose from the following values: android, ios default value: androidwindows
deviceNodevice type optional field can take the values:desktop, mobile default value: desktopdesktop
keywordYesSearch keyword
block_depthNoparsing depth optional field number of blocks of results in SERP max value: 700
language_codeYessearch engine language code (e.g., 'en')
location_nameYesfull name of the location required field Location format - hierarchical, comma-separated (from most specific to least) Can be one of: 1. Country only: "United States" 2. Region,Country: "California,United States" 3. City,Region,Country: "San Francisco,California,United States"

TDQS

B3.1/5.0
Behavior2/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool's safety profile is clear. However, the description adds no extra behavioral context beyond what is implicit. It fails to mention that block_depth can be customized up to 700, which is a key behavioral trait. No mention of rate limits, authentication, or pagination.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no extraneous words. It is front-loaded and efficient. Every part contributes to stating the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 6 parameters (3 required) and full schema coverage, the description is adequate but lacks completeness in explaining the output. There is no output schema, and the description does not hint at what is returned (e.g., video titles, URLs). The default block_depth of 20 is stated, but the max of 700 is omitted. For a search results tool, more context on response structure would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, meaning each parameter already has a description in the schema. The tool description adds no additional semantic value beyond the schema. According to the calibration, baseline is 3 when schema coverage is high, and the description does not enhance understanding of parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides YouTube search engine results for a keyword. The verb 'provides' and resource are explicit. However, it says 'top 20 blocks' which may conflict with the configurable block_depth parameter (default 20, max 700), slightly reducing clarity. It does not differentiate from sibling tools like serp_youtube_video_info_live_advanced, but the tool name itself contains 'youtube_organic' which helps.

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

Usage Guidelines2/5

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

No usage guidelines are provided. There is no indication of when to use this tool vs alternatives such as serp_organic_live_advanced (for web) or serp_youtube_video_info_live_advanced (for specific video info). The description lacks any guidance on context or exclusions.

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

serp_youtube_video_comments_live_advancedSERP YouTube Video Comments Live AdvancedC
Read-onlyIdempotent

provides data on the video comments you specify

ParametersJSON Schema
NameRequiredDescriptionDefault
osNodevice operating system optional field if you specify desktop in the device field, choose from the following values: windows, macos default value: windows if you specify mobile in the device field, choose from the following values: android, ios default value: androidwindows
depthNoparsing depth, number of results in SERP, max value: 700
deviceNodevice type optional field can take the values:desktop, mobile default value: desktopdesktop
video_idYesID of the video
language_codeYessearch engine language code (e.g., 'en')
location_nameYesfull name of the location required field Location format - hierarchical, comma-separated (from most specific to least) Can be one of: 1. Country only: "United States" 2. Region,Country: "California,United States" 3. City,Region,Country: "San Francisco,California,United States"

TDQS

C2.3/5.0
Behavior2/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds minimal value, not explaining pagination (depth parameter), rate limits, or behavior when video has no comments.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence is concise but lacks structure and does not front-load key details. The sentence is functional but could be improved.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 6 parameters (3 required), no output schema, and depth up to 700, the description is far too minimal. It does not explain return format, usage context, or limitations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all parameters. The description does not add additional 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.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description is vague: 'provides data on the video comments you specify' does not specify what kind of data or source. It fails to distinguish from siblings like 'serp_youtube_video_info_live_advanced'.

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

Usage Guidelines2/5

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. Sibling tools include other YouTube comment/subtitle/info tools, but no comparison is provided.

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

serp_youtube_video_info_live_advancedSERP YouTube Video Info Live AdvancedC
Read-onlyIdempotent

provides data on the video you specify

ParametersJSON Schema
NameRequiredDescriptionDefault
osNodevice operating system optional field if you specify desktop in the device field, choose from the following values: windows, macos default value: windows if you specify mobile in the device field, choose from the following values: android, ios default value: androidwindows
deviceNodevice type optional field can take the values:desktop, mobile default value: desktopdesktop
video_idYesID of the video
language_codeYessearch engine language code (e.g., 'en')
location_nameYesfull name of the location required field Location format - hierarchical, comma-separated (from most specific to least) Can be one of: 1. Country only: "United States" 2. Region,Country: "California,United States" 3. City,Region,Country: "San Francisco,California,United States"

TDQS

C2.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral traits, but does not contradict annotations either.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single vague sentence. While concise, it is under-specified and fails to convey sufficient information. It lacks structure and front-loading of key details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 5 parameters (3 required) and no output schema, the description is too minimal. It does not explain what 'data' includes, why location and language are required, or hint at the return format, leaving the agent with insufficient context to use the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with each parameter having descriptions. The tool description does not add extra meaning or clarification beyond the schema, so it meets the baseline but does not enhance understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'provides data on the video you specify' which indicates it returns information about a specific video, but it lacks specificity on what kind of data (e.g., metadata, statistics) and does not differentiate from sibling YouTube tools like serp_youtube_video_comments_live_advanced.

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

Usage Guidelines2/5

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

There is no guidance on when to use this tool versus alternatives, no mention of prerequisites, limitations, or best practices. The sole sentence does not provide usage context.

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

serp_youtube_video_subtitles_live_advancedSERP YouTube Video Subtitles Live AdvancedC
Read-onlyIdempotent

provides data on the video subtitles you specify

ParametersJSON Schema
NameRequiredDescriptionDefault
osNodevice operating system optional field if you specify desktop in the device field, choose from the following values: windows, macos default value: windows if you specify mobile in the device field, choose from the following values: android, ios default value: androidwindows
deviceNodevice type optional field can take the values:desktop, mobile default value: desktopdesktop
video_idYesID of the video
language_codeYessearch engine language code (e.g., 'en')
location_nameYesfull name of the location required field Location format - hierarchical, comma-separated (from most specific to least) Can be one of: 1. Country only: "United States" 2. Region,Country: "California,United States" 3. City,Region,Country: "San Francisco,California,United States"
subtitles_languageNolanguage code of original text (e.g., 'en')
subtitles_translate_languageNolanguage code of translated text (e.g., 'en')

TDQS

C2.5/5.0
Behavior2/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. However, the description adds nothing beyond 'provides data', omitting details like pagination, error handling (e.g., missing subtitles), or rate limits. With annotations carrying the burden, a score of 2 is appropriate as the description fails to add value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short (one sentence) which is concise, but it lacks structure and substance. It could be expanded slightly to include purpose and usage without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters, no output schema, and sibling tools providing similar functions, the description is incomplete. It does not explain the return format, whether subtitles are returned as text or metadata, or how to interpret results. The schema covers inputs but the description fails to provide sufficient operational context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and parameter descriptions in the input schema are detailed (e.g., location format, OS options). The description does not add any additional meaning beyond the schema, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it provides data on video subtitles, which is specific enough to identify the resource, but it lacks a strong verb like 'retrieve' or 'get'. It is not a tautology, but the purpose is vague and does not differentiate well from sibling tools like video info or comments tools.

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

Usage Guidelines2/5

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 alternatives such as serp_youtube_video_info_live_advanced or serp_youtube_video_comments_live_advanced. There is no mention of prerequisites, typical use cases, or when not to use it.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 89 tool updatesv2.9.11
    • First observedai_opt_kw_data_loc_and_lang
    • First observedai_opt_llm_ment_agg_metrics
    • First observedai_opt_llm_ment_cross_agg_metrics
    • First observedai_opt_llm_ment_loc_and_lang
    • First observedai_opt_llm_ment_search
    • First observedai_opt_llm_ment_top_domains
    • First observedai_opt_llm_ment_top_pages
    • First observedai_optimization_chat_gpt_scraper
    • First observedai_optimization_chat_gpt_scraper_locations
    • First observedai_optimization_keyword_data_search_volume
    • First observedai_optimization_llm_mentions_filters
    • First observedai_optimization_llm_models
    • First observedai_optimization_llm_response
    • First observedbacklinks_anchors
    • First observedbacklinks_available_filters
    • First observedbacklinks_backlinks
    • First observedbacklinks_bulk_backlinks
    • First observedbacklinks_bulk_new_lost_backlinks
    • First observedbacklinks_bulk_new_lost_referring_domains
    • First observedbacklinks_bulk_pages_summary
    • First observedbacklinks_bulk_ranks
    • First observedbacklinks_bulk_referring_domains
    • First observedbacklinks_bulk_spam_score
    • First observedbacklinks_competitors
    • First observedbacklinks_domain_intersection
    • First observedbacklinks_domain_pages
    • First observedbacklinks_domain_pages_summary
    • First observedbacklinks_page_intersection
    • First observedbacklinks_referring_domains
    • First observedbacklinks_referring_networks
    • First observedbacklinks_summary
    • First observedbacklinks_timeseries_new_lost_summary
    • First observedbacklinks_timeseries_summary
    • First observedbusiness_data_business_listings_search
    • First observedcontent_analysis_phrase_trends
    • First observedcontent_analysis_search
    • First observedcontent_analysis_summary
    • First observeddataforseo_labs_amazon_bulk_search_volume
    • First observeddataforseo_labs_amazon_product_competitors
    • First observeddataforseo_labs_amazon_product_kw_intersections
    • First observeddataforseo_labs_amazon_product_rank_overview
    • First observeddataforseo_labs_amazon_ranked_keywords
    • First observeddataforseo_labs_amazon_related_keywords
    • First observeddataforseo_labs_available_filters
    • First observeddataforseo_labs_bulk_keyword_difficulty
    • First observeddataforseo_labs_bulk_traffic_estimation
    • First observeddataforseo_labs_google_competitors_domain
    • First observeddataforseo_labs_google_domain_intersection
    • First observeddataforseo_labs_google_domain_rank_overview
    • First observeddataforseo_labs_google_historical_keyword_data
    • First observeddataforseo_labs_google_historical_rank_overview
    • First observeddataforseo_labs_google_historical_serps
    • First observeddataforseo_labs_google_keyword_ideas
    • First observeddataforseo_labs_google_keyword_overview
    • First observeddataforseo_labs_google_keyword_suggestions
    • First observeddataforseo_labs_google_keywords_for_site
    • First observeddataforseo_labs_google_page_intersection
    • First observeddataforseo_labs_google_ranked_keywords
    • First observeddataforseo_labs_google_related_keywords
    • First observeddataforseo_labs_google_relevant_pages
    • First observeddataforseo_labs_google_serp_competitors
    • First observeddataforseo_labs_google_subdomains
    • First observeddataforseo_labs_google_top_searches
    • First observeddataforseo_labs_search_intent
    • First observeddomain_analytics_technologies_available_filters
    • First observeddomain_analytics_technologies_domain_technologies
    • First observeddomain_analytics_whois_available_filters
    • First observeddomain_analytics_whois_overview
    • First observedkw_data_dfs_trends_demography
    • First observedkw_data_dfs_trends_explore
    • First observedkw_data_dfs_trends_subregion_interests
    • First observedkw_data_google_ads_locations
    • First observedkw_data_google_ads_search_volume
    • First observedkw_data_google_trends_categories
    • First observedkw_data_google_trends_explore
    • First observedmerchant_amazon_asin_live_advanced
    • First observedmerchant_amazon_locations
    • First observedmerchant_amazon_products_live_advanced
    • First observedmerchant_amazon_sellers_live_advanced
    • First observedon_page_content_parsing
    • First observedon_page_instant_pages
    • First observedon_page_lighthouse
    • First observedserp_locations
    • First observedserp_organic_live_advanced
    • First observedserp_youtube_locations
    • First observedserp_youtube_organic_live_advanced
    • First observedserp_youtube_video_comments_live_advanced
    • First observedserp_youtube_video_info_live_advanced
    • First observedserp_youtube_video_subtitles_live_advanced
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.1/5.0
Disambiguation4/5

Most tools have distinct purposes with detailed descriptions. However, some close pairs exist (e.g., keyword suggestions vs. ideas; backlinks_referring_domains vs bulk variant), but descriptions help agents differentiate.

Naming Consistency3/5

Within each category (e.g., backlinks_, dataforseo_labs_google_) naming is fairly consistent, but across categories there is mixing of prefixes (kw_data vs dataforseo_labs) and inconsistent abbreviations (opt vs optimization), reducing overall predictability.

Tool Count2/5

89 tools is very high for an SEO API. While each tool serves a specific need, many could be consolidated into parameterized endpoints (e.g., bulk vs single). The volume may overwhelm agents and increase selection difficulty.

Completeness4/5

The toolset covers a broad range of SEO data: keyword research, backlinks, SERP (multiple engines), business listings, on-page analysis, domain intelligence, content analysis, and Amazon merchant data. Few obvious gaps exist for the stated domain.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • DataForSEO MCP Server

    Skobyn
    A
    license
    Not graded
    quality
    D
    maintenance
    A stdio-based server that enables interaction with the DataForSEO API through the Model Context Protocol, allowing users to fetch SEO data including search results, keywords data, backlinks, on-page analysis, and more.
    20
    7
    MIT
  • DataForSEO MCP Server by dataforseo

    DataForSEO MCP Serverofficial

    dataforseo
    A
    license
    B
    quality
    A
    maintenance
    A Model Context Protocol server that enables Claude to interact with DataForSEO APIs, allowing access to SEO data including SERPs, keyword research, on-page metrics, and domain analytics.
    17
    22,898
    242
    Apache 2.0

  • kwrds.ai MCP Server

    mkotsollaris
    A
    license
    Not graded
    quality
    D
    maintenance
    Model Context Protocol server that enables AI assistants to perform keyword research, SEO analysis, and content planning through natural language queries against kwrds.ai's SEO tools.
    7
    Apache 2.0
  • FetchSERP MCP Server by fetchSERP

    FetchSERP MCP Serverofficial

    fetchSERP
    -
    license
    C
    quality
    Not graded
    maintenance
    A Model Context Protocol server that provides AI assistants with access to FetchSERP API capabilities for SEO analysis, SERP data, web scraping, and keyword research.
    23
    19
    19
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dataforseo/mcp-server-typescript-deprecated'

If you have feedback or need assistance with the MCP directory API, please join our Discord server