Skip to main content
Glama

SEOAI - AI Visibility Tracker

Get search gaps

get_search_gaps
Read-onlyIdempotent

Compares the brand's search demand with its AI visibility, from ONE source per call: Google Search Console (provider google, default) or Bing Webmaster (bing). The two are never added together. Returns connected (false: no property mapped for that provider, nothing else), stale (true: the connection needs renewing, data is the last sync), window (the search data period) and ai_window (the period of AI runs). search_only: queries with impressions but no tracked prompt. tracked_absent: queries covered by a gap prompt (see gap_class, cited_share, prompt_id, runs, competitor). gap_class has the same values as in list_gaps. ai_only: prompts cited in AI answers with almost no search demand. Each list holds at most the top 50 by impressions; counts has the totals. Take prompt_id to get_gap_audit (same prompts as list_gaps); brand_id, topic_id come from list_brands. Filters: provider, topic_id, range (7d, 30d default, 90d), limit (default 20, max 100), offset.

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": {
      "brand_id": "<brand_id>"
    },
    "name": "get_search_gaps"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoItems per list and page. Default 20, max 100.
rangeNoPeriod of AI runs to read. Default 30d.
offsetNoItems to skip per list. Default 0.
brand_idYesBrand id from list_brands.
providerNoSearch data source, one per call. Default google.
topic_idNoOnly tracked_absent and ai_only rows of this topic (from list_brands).

Schema Changelog

Changes observed during successful MCP inspections.

No schema history has been recorded yet.

TDQS

A4.4/5.0
Behavior5/5

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

Well beyond the annotations: it discloses the per-provider isolation rule, the connected=false short-circuit ('nothing else'), what stale=true means (last sync data), the definitions of window vs. ai_window, and the top-50-per-list cap with counts carrying true totals. These are exactly the behavioral traits an agent needs before trusting partial results.

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?

Front-loaded with the core comparison, then return-shape semantics, then filters — no filler sentences. The compressed parenthetical notation ('connected (false: …)') is dense and takes a careful read, costing a point on structure.

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?

With no output schema, the description carries the full burden and does: it enumerates returned fields, explains each result bucket, states the 50-item list cap and that counts holds totals, and gives pagination truth via limit/offset. An agent can call this without further 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%, so defaults (provider google, range 30d, limit 20/max 100) are already documented in the schema. The description restates them and adds only marginal nuance, such as topic_id affecting only tracked_absent and ai_only rows, which the schema also states.

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 comparison (brand's search demand vs. AI visibility) with an explicit scope rule: one provider per call, never summed. The three result categories (search_only, tracked_absent, ai_only) make it clearly distinguishable from list_gaps and get_gap_audit, which it names.

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 concrete routing: prompt_id feeds get_gap_audit, brand_id and topic_id come from list_brands, and gap_class shares values with list_gaps. It also clarifies the provider default and that Bing/Google are never combined. It stops short of an explicit 'use list_gaps instead when…' exclusion, so no 5.

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