Skip to main content
Glama
Sign In

Keytomic

by com.keytomic.app
OverviewDiscussionsAdmin

Get search insight

get_search_insight
Read-only

Answers one common Search Console question, chosen with kind, with tested thresholds, and says how in a method block. Google keeps and returns rows ranked by clicks, up to a daily row limit, so on large sites low-click rows can be missing even when the result is not truncated, and such a row can then show as new, lost or a zombie. Data comes from the site’s connected Google Search Console property, web search only. By default the period is the last 28 days that have final data, which usually ends 2 to 3 days ago. Search Console does not separate AI Overviews or AI Mode traffic from web search. new_rankings, improving, and declining compare the period with the 28 days before it by default. The default period does not apply to zombie_pages, which has its own fixed period. Every kind takes projectId, cursor and pageSize; an input the kind does not take gives invalid_arguments. Page through with cursor and nextCursor.

  • top_rankings: Which pages or queries have the strongest Google visibility? The most clicks, or the most impressions with sortBy "impressions", with at least 50 impressions by default. Inputs: startDate, endDate, includeSearchOperatorQueries, rowCap, dimension, minImpressions, sortBy.

  • new_rankings: Which pages or queries started to appear in Google Search? At least 50 impressions in the period by default and no row in the comparison period. Most impressions first. Nothing is listed as new when the comparison read hits the row cap. Inputs: startDate, endDate, includeSearchOperatorQueries, rowCap, compareWith, dimension, minImpressions.

  • improving: Which pages or queries are gaining? Average position up by 1 or more, or clicks or impressions up against the property. A change in clicks or impressions counts when it beats or trails the whole property’s change by at least 20 percentage points by default, so a site-wide drop does not flag every row. Rows that moved both ways are counted in mixedRows and listed in neither. Rows need 50 impressions in both periods by default. Biggest click gain first. Inputs: startDate, endDate, includeSearchOperatorQueries, rowCap, compareWith, dimension, minImpressions, relativeDeltaPoints.

  • declining: Which pages or queries are losing traffic or rankings? Average position down by 1 or more, or clicks or impressions down against the property, plus rows with enough impressions before and none now (status "lost", left out when the current read hits the row cap). A change in clicks or impressions counts when it beats or trails the whole property’s change by at least 20 percentage points by default, so a site-wide drop does not flag every row. Rows that moved both ways are counted in mixedRows and listed in neither. Declined rows need 50 impressions in both periods by default, and lost rows in the comparison period. Each declined page carries a likely cause: position_loss (position worse by 2 or more), demand_loss (position stable, impressions fell against the property), ctr_loss (position and impressions stable, CTR fell) or unclear. Biggest click loss first. Inputs: startDate, endDate, includeSearchOperatorQueries, rowCap, compareWith, dimension, minImpressions, relativeDeltaPoints.

  • low_hanging_fruits: Which pages or queries rank just below the top results and are easiest to improve? An average position from 11 up to, not including, 21, with at least 50 impressions by default. Most impressions first. Inputs: startDate, endDate, includeSearchOperatorQueries, rowCap, dimension, minImpressions.

  • underperforming: Which pages or queries get fewer clicks than their position should give? At least 100 impressions by default and a CTR below 50% of the expected CTR of their position band. The bands are average positions 1, 2, 3, 4 to 5, 6 to 10, 11 to 20; a band from a to b holds positions from a up to, not including, b + 1. Expected CTR is the property's median CTR over the band's rows with 50 or more impressions; a band under 1,000 impressions, or with no such row, uses an approximate industry CTR, and method.bands gives each source. A band whose median CTR is 0 lists no rows. Most missed clicks first. Inputs: startDate, endDate, includeSearchOperatorQueries, rowCap, dimension, minImpressions.

  • cannibalization: Which search queries have 2 or more pages of the site competing? Groups are signals with no search intent or page-role check. Queries group by exact and close match (English rules): case, accents, punctuation (. and - split words, & is and), a possessive 's, word order, stop words, and a regular plural when the singular is also in the data; other symbols stay part of a word, as in c++. A group needs 100 impressions by default and 2 or more pages that each get 10% or more of its page impressions; Google counts an impression for each page a search shows. brandTerms leaves out every group with a brand query. Most impressions first. Inputs: startDate, endDate, includeSearchOperatorQueries, rowCap, brandTerms, minImpressions.

  • zombie_pages: Which pages in the submitted sitemaps got no Google impressions in the last 90 days of final data? Its period is fixed. A sitemap URL whose canonical URL is another one has no data of its own, so it shows as a zombie. Sitemap indexes are read one level deep, up to 50 sitemaps and 50,000 URLs. Pages with a sitemap lastmod in the last 30 days count as recent, not zombie; a page with no lastmod is never skipped. URLs match without scheme, www, host case, trailing slash or fragment. Rows are the zombie pages, then sitemap entries Search Console cannot report (status unmatched). counts, unreadSitemaps and pageRowsRead give the rest. The sitemaps are downloaded from the site, so they can differ from what Google last read. Inputs: none of its own.

  • question_queries: Which search queries are questions or long and conversational, and so show what people ask? Queries that start with an English question word (who, what, when, where, why, how, which, can, does, do, is, are, should, will) or have 6 or more words; each row says which rule it met. Words are whole words, so a query never matches because a word contains "ai". This tool does not detect AI search traffic. Most impressions first. Inputs: startDate, endDate, includeSearchOperatorQueries, rowCap.

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": {
      "projectId": "<projectId>",
      "kind": "<kind>"
    },
    "name": "get_search_insight"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindYesThe question to answer. The description lists each kind with its rule and inputs.
cursorNonextCursor from the previous page. Keep every other input the same; pageSize may change. Later pages come from the rows read for the first page, with no new Search Console read. A cursor expires 10 minutes after the first page was read, or earlier if those rows leave the cache or the site's Search Console property or default period changes; then start again without a cursor.
rowCapNoMost rows to read from Google for each query or page list; default 50,000, at most 200,000. The result says truncated when the cap stopped a read.
sortByNoRank by clicks (default) or by impressions.
endDateNoLast day, YYYY-MM-DD. Defaults to the last day with final data. A later day reads data Google still collects, and the result says so.
pageSizeNoRows per page. Default 50.
dimensionNo"page" lists pages; "query" lists search queries. Required by every kind that takes it.
projectIdYesSite to act on, from list_sites. Only its connected Search Console property is used.
startDateNoFirst day, YYYY-MM-DD. Defaults to 28 days ending on endDate.
brandTermsNoLeave out every query group with a query that contains every word of one of these, such as the brand name, as whole words in any order. A possessive or a regular plural of a word also matches, so Lowe's matches lowes. Close matches of a brand query leave with its group, so Bank of America also removes the group of bank america. A one-word term matches every query with that word, so give the full brand, such as On Running.
compareWithNo"previous": the period of equal length just before. "sameLastYear": the same dates one year earlier, for seasonal sites. Default "previous".
minImpressionsNoImpressions a row, or a query group for cannibalization, needs. Default 50; 100 for underperforming, 100 for cannibalization.
relativeDeltaPointsNoPercentage points by which a row’s clicks or impressions change must beat or trail the whole property’s change. Default 20.
includeSearchOperatorQueriesNoKeep queries with a search operator, such as site:, inurl:, intitle:, filetype: or before:, in the lists. Totals always include them. Default false.

Schema Changelog

Changes observed during successful MCP inspections.

No schema history has been recorded yet.

TDQS

A4.1/5.0
Behavior5/5

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

Annotations only establish read-only, non-destructive, open-world; the description goes far beyond them by disclosing that Google ranks and truncates rows (so low-click rows can be missing and misread as new/lost/zombie), that the default period ends 2-3 days back, that zombie_pages has a fixed 90-day period, that AI Overviews/AI Mode traffic is not separated, that sitemaps are downloaded from the site and read one level deep, and that cursors expire after 10 minutes or when the cache/property/period changes. These are exactly the caveats that prevent an agent from misinterpreting results or retrying a stale cursor.

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?

The preamble front-loads the shared caveats before the per-kind bullet list, and the bullets are consistently framed as question-plus-rule-plus-inputs, so it is navigable despite its length. It is nonetheless very long for a tool descriptor, and the sentence about 20-percentage-point relative deltas is repeated verbatim under both `improving` and `declining`, which is avoidable duplication.

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 14-parameter, nine-mode tool with no output schema, the definition supplies the period defaults, per-kind thresholds, exclusion and truncation behavior, cursor paging rules, and even the names of secondary result fields (method.bands, counts, unreadSitemaps, pageRowsRead, mixedRows, nextCursor). An agent has what it needs to pick a kind, fill only the inputs that kind accepts, and interpret a short or empty result correctly.

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 the baseline applies: each parameter already carries rich schema text (cursor expiry, rowCap semantics, brandTerms matching, compareWith). The description adds real value by mapping which inputs each kind accepts and by stating per-kind default thresholds (50 impressions, 100 for underperforming and cannibalization, 20 percentage points for relative delta), but that is a partial layer over an already complete schema rather than net-new meaning for individual parameters.

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 opening sentence gives a specific verb and resource (answers one common Search Console question, selected by `kind`) and signals the distinguishing trait: curated, threshold-tested answers plus a method block rather than raw rows. What it never does is name or route away from likely siblings such as get_search_performance or search_analytics_query, so an agent must infer that this tool is the pre-analyzed path and those are the raw-data path.

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?

Usage is specified at the finest useful grain: each of the nine `kind` values is framed as a concrete question, with its qualifying rule and its accepted inputs listed, and the definition warns that passing an input a kind does not take yields invalid_arguments. There is no explicit 'use this instead of X' or when-not-to-use guidance relative to the sibling analytics tools, which is the only gap.

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

All Keytomic toolsInspect
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