Skip to main content
Glama

SEO metrics

seo_metrics
Read-only

Answer questions about search visibility and search demand — keywords, rankings, links, domains, and how interest in a subject moves over time and across a country.

Use when the question is about how a site or a market performs in search rather than about what a page says: which keywords a domain ranks for, which pages earn its traffic, who competes with it, which terms it buys ads on, which sites rank or buy ads for a set of keywords, what links to it, how a keyword's demand and difficulty compare, whether interest in a subject is rising or falling, and which of a country's regions search for it most.

Examples:

  • "keywords ahrefs.com ranks in the top 3 for, with real volume"

  • "which pages of this site bring the most organic traffic"

  • "who competes with this domain and how big are they"

  • "keyword ideas around link building that are not brutally competitive"

  • "which sites are running Google ads on these keywords right now"

Ask in plain language. Do not write field names, operators or query syntax — the request is composed from your question, and what came back is described in the answer so you can check it matched what you meant.

Not for: what a specific page says (use advanced_web_fetch), or what people are posting right now (use advanced_web_search).

Results are stored as citable Data records — a large report comes back as a summary plus a line index, so read the parts you need with read_collected_records or search across them with grep_collected_records. Every relevant result carries mdOrHtmlDownloadUrl — a ready-to-use link that downloads that record as Markdown, no key attached, so it can be passed on as-is. Swap its ?type=md for ?type=html and the same link hands back the page's original HTML exactly as the site served it, markup and all — what an SEO reader needs and what Markdown drops; web-page fetches only.

If status: "running" is returned, poll get_task_results({ taskIds }).

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": {
      "requests": "<requests>"
    },
    "name": "seo_metrics"
  }
}

Input Schema

NameRequiredDescriptionDefault
requestsYesOne or more questions. Each pairs a question with the sources to ask it of; requests and sources run in parallel.
isResearchNoDefault true. True means this call is part of an investigation: you will come back to what it collects, weigh it against other sources and cite it, so it is worth preparing the material for repeated use. Set false for a one-off question you are waiting on right now and will answer in this same turn — that trades the preparation for the fastest reply the source allows.
maxWaitSecNoHow long to wait before returning `status: "running"` with a `taskId` to poll via `get_task_results`. Defaults to 50 seconds, which is also the server's ceiling — a larger value is clamped down to it, not honoured. Results stream as they are produced: each completed unit of work appears in `streaming.chunks[]` as soon as it is ready.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / requests / items / properties / sources / description
      Previous value: -"Which sources to ask. `keywords` — Monthly search demand for phrases in a country and language: how often each is searched, how that moved over the past year, what advertisers pay per click, how hard the top results are to displace, and whether searchers want to learn, compare, buy or navigate. Start from a phrase and get the longer queries containing it; from a subject and get adjacent terms; from a website and get the territory it sits in; from nothing at all and get a market's biggest queries; or hand over exact phrases and get their numbers side by side. Filter and rank by any of these measures. `rankings` — Search-ranking data for any website. Ask what terms a site ranks for and in which positions, which of its pages and sections bring the most visitors, which subjects it covers, and how much monthly traffic each is worth. Compare two sites to see the terms they share or the ones only one of them holds. Find which sites compete with it and how far the overlap goes. Or supply a list of search terms and learn which sites own them. Anything can be narrowed by country and language, by kind of result, and by those numbers; history over past months is available on request. `backlinks` — Inbound links to any website, section or single page. Ask who links to it, from which pages, and with what wording; how many linking sites and links there are in total; how strong and how trustworthy those sources look; when each link was first seen and whether it is still there. Also which pages of a site attract the most links, and which wording is used most often to link to it. Ask for links that are still live, or for ones that were lost. Phrase it as a sentence — name the site or page, and say what about its links you want to know. `domain` — Profiles of websites, not the search results they appear in. Name the sites you know, or describe the ones to find. Covers when a domain was registered, when it expires, who registered it, and whether it is still live; what the site is built with — CMS, store platform, analytics, payments, CRM — plus contact details and social links it publishes; and how big its unpaid and paid search presence is. It queries a large index, so you can also ask for every site matching a description: an age, an ending, a technology, a country. For which keywords or pages a site ranks, ask the rankings source. `trends` — How much people search for something, and how that has moved. One term, or up to five side by side: whether interest is rising or falling across a window from the past hour to every month back to 2004, or which of a country's own regions search for it most. Web, image, news, shopping or video searching. Three limits: one request answers one of those two questions and never both, so wanting movement AND regions is two requests; every report covers one country, with no worldwide figure; and figures are relative — 100 is the busiest point in the window asked about, so two reports never line up. Several can run at once when a question spans them."New value: +"Which sources to ask. `keywords` — Monthly search demand for phrases in a country and language: how often each is searched, how that moved over the past year, what advertisers pay per click, how hard the top results are to displace, and whether searchers want to learn, compare, buy or navigate. Start from one or several phrases and get the longer queries containing them or what people search beside them; from a subject and get its wider category; from a website and get its territory; from nothing and get a market's biggest queries; or look up exact phrases. Filter and rank by any of these measures. `rankings` — Search-ranking data for any website. Ask what terms a site ranks for and in which positions, which terms its own ads appear on, which of its pages and sections bring the most visitors, which subjects it covers, and how much monthly traffic each is worth. Compare two sites' shared or exclusive terms. Find which sites compete with it. Or supply a list of search terms and learn which sites own them, or which sites show ads on them right now. Narrow by country or city and language, kind of result and those numbers; history over past months on request. `backlinks` — Inbound links to any website, section or single page. Ask who links to it, from which pages, and with what wording; how many linking sites and links there are in total; how strong and how trustworthy those sources look; when each link was first seen and whether it is still there. Also which pages of a site attract the most links, and which wording is used most often to link to it. Ask for links that are still live, or for ones that were lost. Phrase it as a sentence — name the site or page, and say what about its links you want to know. `domain` — Profiles of websites, not the search results they appear in. Name the sites you know, or describe the ones to find. Covers when a domain was registered, when it expires, who registered it, and whether it is still live; what the site is built with — CMS, store platform, analytics, payments, CRM — plus contact details and social links it publishes; and how big its unpaid and paid search presence is. It queries a large index, so you can also ask for every site matching a description: an age, an ending, a technology, a country. For which keywords or pages a site ranks, ask the rankings source. `trends` — How much people search for something, and how that has moved. One term, or up to five side by side: whether interest is rising or falling across a window from the past hour to every month back to 2004, or which of a country's own regions search for it most. Web, image, news, shopping or video searching. Three limits: one request answers one of those two questions and never both, so wanting movement AND regions is two requests; every report covers one country, with no worldwide figure; and figures are relative — 100 is the busiest point in the window asked about, so two reports never line up. Several can run at once when a question spans them."
  2. Changed1 schema field changed
    • changedInput schema / properties / requests / items / properties / desiredResultsCount / description
      Previous value: -"How many rows you would like back (default 25). A source may return fewer if fewer match."New value: +"How many rows you would like back (default 25). Large counts are read page by page; a source returns fewer when fewer match, and the answer says when the account's balance or plan stopped it early."
  3. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond that. It discloses that results are persisted as citable `Data` records, that large reports return as a summary plus line index readable via `read_collected_records`/`grep_collected_records`, that every record carries an unauthenticated `mdOrHtmlDownloadUrl` with a `?type=html` variant, and that long-running calls return a pollable task id — all non-obvious behaviors.

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?

It is front-loaded correctly: capability sentence, then when-to-use, then examples, then exclusions, then mechanics. The example list and the source recap partially duplicate the schema's enum descriptions, and the `mdOrHtmlDownloadUrl` passage runs several clauses longer than needed, but given the tool's breadth the length is largely earned.

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?

For a high-complexity, multi-source, async research tool with no output schema, the description still covers return shape (summary plus line index), retrieval path (read/grep collected records), download affordance, and async polling. Nothing an agent needs in order to call it correctly or handle its response is missing.

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% and the per-source semantics are already documented in the `sources` enum descriptions, so the schema carries most of the parameter burden. The description reinforces the key constraint — ask in plain language, syntax will be read literally — but adds no new meaning for `requests`, `isResearch`, `maxWaitSec`, or `desiredResultsCount`.

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 first sentence states a specific verb and resource — answering questions about search visibility and demand — and enumerates the concrete data domains (keywords, rankings, links, domains, trends) that map onto the `sources` enum. The 'Not for' clause names `advanced_web_fetch` and `advanced_web_search` and draws the boundary between search-performance data and page content or social chatter, so an agent can disambiguate without opening a schema.

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

Usage Guidelines5/5

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

Usage is spelled out in both directions: a positive 'Use when' clause with concrete question archetypes, and an explicit 'Not for' clause routing to the two sibling tools. It also covers operational flow — plain-language input only, no field names or operators, poll `get_task_results` when `status: "running"` — which is exactly the alternative-path guidance an agent needs.

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