Skip to main content
Glama

Get keyword research results

get_keyword_research_results
Read-onlyIdempotent

The result of a keyword research run (results stream in: while it runs, finished countries are returned, a country still scoring is marked provisional with the terms scored so far, and pending names the rest): per country, the scored candidates with their score breakdowns and top apps, and the listing variants with character counters, checks and modeled coverage before/after. Popularity, difficulty, relevance and opportunity are modeled 0-100 indexes, not store-reported search volume. Read-only; spends nothing.

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": {
      "run_id": "<run_id>"
    },
    "name": "get_keyword_research_results"
  }
}

Input Schema

NameRequiredDescriptionDefault
run_idYesRun id.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), yet the description adds substantial non-redundant context: progressive/partial result semantics with explicit provisional and pending states, and the caveat that popularity, difficulty, relevance and opportunity are modeled 0-100 indexes rather than store-reported search volume. The added 'spends nothing' cost note is useful though partly implied by readOnlyHint. It does not cover error behavior for an unknown run_id or how to detect a fully complete run.

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 content is all relevant, but it is delivered as one long sentence with a nested parenthetical inside another parenthetical, which makes the streaming semantics hard to parse on first read. The core statement ('The result of a keyword research run') is front-loaded, but the stream/provisional explanation should be its own sentence rather than an interrupting clause.

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

Completeness4/5

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

With no output schema, the description carries the return-value burden and does so well: it enumerates candidate scores, breakdowns, top apps, listing variants, counters, checks, and before/after coverage, plus the meaning of the numeric indexes. Missing only edge-case behavior (invalid or expired run_id, whether pending countries eventually resolve) for full 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?

There is a single required parameter, run_id, and the schema already documents it at 100% coverage. The description references the run implicitly ('the result of a keyword research run') but adds no syntax, format, or source guidance for where the id comes from. Baseline 3 is appropriate when the schema does the heavy lifting.

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 names the specific resource (the results of a keyword research run) and enumerates the payload shape per country: scored candidates with score breakdowns, top apps, and listing variants with character counters and modeled coverage. That is far more than a restated title. It stops short of distinguishing itself from the sibling get_keyword_research_status, which an agent must infer from context rather than read.

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?

Usage is only implied: the note that results 'stream in: while it runs, finished countries are returned, a country still scoring is marked provisional' tells an agent this tool is callable mid-run and can be polled, but there is no explicit when-to-use, when-not-to-use, or named alternative. The agent must derive the polling pattern itself.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources