Mark

Research Keywords

research_keywords

Finds keyword ideas for one to five seed terms. On labs, each idea contains its seed term. Every idea carries seed, the seed term it came from (null for a multi-seed google_ads run). Each call makes 1 request per seed term to the keyword provider (google_ads: 1 request in total), returning up to limit ideas in total. Each call spends provider calls. Every idea has search volume, CPC and competition. labs (the default) adds difficulty and intent; google_ads, for countries labs does not cover, has neither. A SERP overview per idea comes only with includeSerpInfo, on labs. With google_ads, close variants come back as one row listing them in closeVariants; its volume is the group's, so count it once. google_ads allows about 12 calls a minute across Mark: on a RATE_LIMITED error, wait the seconds it states or run calls one at a time. The text table lists up to 100 ideas; every idea is in the structured result. Results are not saved until you call save_keywords. If this refuses because the workspace is not set up, call get_setup_status and check its rows, including skipped ones. Related: check_keyword_audience, save_keywords, set_up_market.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "seedKeywords": "<seedKeywords>"
    },
    "name": "research_keywords"
  }
}

Input Schema

Name	Required	Description
`limit`	No	Max ideas to return. Default from the provider, up to 1000.
`source`	No	labs (default) or google_ads. google_ads has no difficulty, intent or SERP overview.
`languageCode`	No	Language code. Defaults to the priority market.
`locationCode`	No	DataForSEO location. Defaults to the priority market.
`seedKeywords`	Yes	One to five seed keywords or a topic.
`includeSerpInfo`	No	Add a SERP overview (serpInfo) to each idea. labs only; rejected with google_ads.

Output Schema

Name	Required	Description	Default
`items`	Yes
`taskId`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 20, 2026

addedInput schema / properties / includeSerpInfo

Added value: +{
+  "description": "Add a SERP overview (serpInfo) to each idea. labs only; rejected with google_ads.",
+  "type": "boolean"
+}

changedInput schema / properties / source / description

Previous value: -"labs (default) or google_ads."New value: +"labs (default) or google_ads. google_ads has no difficulty, intent or SERP overview."

Changed2 schema fields changedOct 7, 2026

removedOutput schema / properties / costUsd

Removed value: -{
-  "type": "number"
-}

changedOutput schema / required

Previous value: -[
-  "costUsd",
-  "items"
-]New value: +[
+  "items"
+]

First observedOct 1, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Goes well beyond the annotations: discloses cost (1 request per seed, 1 total for google_ads), a ~12 calls/minute rate limit with guidance for RATE_LIMITED errors, the fact that results are ephemeral until save_keywords, and the text-table truncation at 100 ideas versus the full structured result.

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?

Purpose is front-loaded, but the middle is tangled: 'On labs, each idea contains its seed term' is restated as 'Every idea carries seed...', and 'Each call spends provider calls' adds nothing. The labs/google_ads differences are scattered across three separate sentences rather than consolidated.

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

Completeness5/5

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

Complete for a six-parameter, cost-incurring tool with an output schema: source behavior, missing fields per source, rate limiting, variant grouping, truncation, and the failure/setup path are all covered, so an agent can invoke it correctly and interpret 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?

Schema coverage is already 100%, so the baseline is 3; the description still adds real meaning about seedKeywords (each idea back-references its seed, null for multi-seed google_ads), includeSerpInfo (labs only, rejected with google_ads), and limit counting variants as one row.

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

Purpose5/5

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

States a specific verb and resource plus scope: 'Finds keyword ideas for one to five seed terms.' It also distinguishes scope from siblings by naming save_keywords, check_keyword_audience and set_up_market as different operations.

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

Usage Guidelines4/5

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

Gives a concrete selection rule for the source enum ('google_ads, for countries labs does not cover') and explains the labs/google_ads feature trade-off. It also routes the agent after a failure ('call get_setup_status') and notes results must be persisted with save_keywords, though it never states when to prefer this over list_ideas or list_saved_keywords.

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

All Mark tools Inspect

Try in Browser

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

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?