Skip to main content
Glama

Client: the data to build the keyword map

keyword_research
Read-onlyIdempotent

The client's keyword map is the SEO strategy a full-stack agency works from: clusters of the searches that bring this business its customers (booked jobs, sales, leads or demos), each with the page that should rank, measured weekly by page from Search Console. Reads the data to build it: 90 days of searches with the page ranking for each, converting paid searches, the pages that bring visits and leads, Keyword Planner volumes and bids for the area, and what the site converts on. Then build the map and store it with keyword_map_save. Changes 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": {
      "client": "<client>"
    },
    "name": "keyword_research"
  }
}

Input Schema

NameRequiredDescriptionDefault
areaNoWhere its customers search from, when the set-up's answer doesn't fit: a city ("Boise, ID"), or a whole country ("United States", "United Kingdom", "Canada", "Australia")
seedsNoSearches to research from: what the business sells, in its buyers' own words. Pass them when the site's own searches are few or generic (a new site, a national or online business)
clientYesClient name from list_clients
competitorsNo2-3 sites that win this business's main searches (from competitor_pages, your own web search, or the set-up): their pages and the searches their sites are about come back, with volumes. Defaults to the set-up's competitors

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / area / description
      Previous value: -"Where its customers search from, when the set-up's answer doesn't fit: a city (\"Boise, ID\"), or \"United States\""New value: +"Where its customers search from, when the set-up's answer doesn't fit: a city (\"Boise, ID\"), or a whole country (\"United States\", \"United Kingdom\", \"Canada\", \"Australia\")"
  2. Changed3 schema fields changed
    • addedInput schema / properties / area
      Added value: +{
      +  "description": "Where its customers search from, when the set-up's answer doesn't fit: a city (\"Boise, ID\"), or \"United States\"",
      +  "maxLength": 80,
      +  "type": "string"
      +}
    • addedInput schema / properties / competitors
      Added value: +{
      +  "description": "2-3 sites that win this business's main searches (from competitor_pages, your own web search, or the set-up): their pages and the searches their sites are about come back, with volumes. Defaults to the set-up's competitors",
      +  "items": {
      +    "maxLength": 120,
      +    "type": "string"
      +  },
      +  "maxItems": 3,
      +  "type": "array"
      +}
    • addedInput schema / properties / seeds
      Added value: +{
      +  "description": "Searches to research from: what the business sells, in its buyers' own words. Pass them when the site's own searches are few or generic (a new site, a national or online business)",
      +  "items": {
      +    "maxLength": 80,
      +    "type": "string"
      +  },
      +  "maxItems": 20,
      +  "type": "array"
      +}
  3. Added

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint; the description's 'Changes nothing' merely restates that. It does add real context the annotations don't cover: the data is pulled from external systems (Search Console, Keyword Planner), measurement is weekly and per page, and the result must be persisted separately with keyword_map_save. It says nothing about latency, quota or cost, which matter for a multi-source external pull.

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?

Roughly two long sentences, the first of which is a pitch about SEO strategy and clusters rather than tool behavior, and the operational instruction ('store it with keyword_map_save') trails at the end instead of leading. The data-source enumeration earns its place, but the framing sentences do not.

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 output schema, the description must convey what comes back, and it only loosely implies a bundle of Search Console, ads, page and Keyword Planner data without saying whether that is raw records, ranked tables, or pre-clustered candidates. The read-only nature and the handoff to keyword_map_save are covered, but the return shape and any size limits remain ambiguous.

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 every parameter including required client is already fully documented in the schema. The description restates the seeds and area conditions but adds no syntax, defaults or edge cases beyond the schema text. Baseline 3 applies when the schema carries the load.

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 identifies the resource (keyword research data for a client's keyword map) and enumerates the specific data sources it reads: 90 days of Search Console searches, converting paid searches, pages bringing visits and leads, Keyword Planner volumes and bids, and conversion data. It also distinguishes itself from keyword_map_save, which stores the map. However, the first two sentences spend their space defining what a keyword map conceptually is rather than stating the tool's verb and output, so the actual operation is inferred from a list rather than declared.

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?

Parameter-level guidance is clear: pass seeds when the site's own searches are 'few or generic (a new site, a national or online business)', pass area only when the set-up's answer doesn't fit, and competitors defaults to the set-up's own list. The workflow position (research, then keyword_map_save) is implied but never stated as an explicit when-to-use instruction, and no exclusion against e.g. ads_keyword_ideas is given.

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.