Skip to main content
Glama
PROMPTEYE-SP-Z-O-O

prompteye-mcp

Official
by PROMPTEYE-SP-Z-O-O
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Count the requests bots made, grouped

count_bot_visits
Read-only

Count bot visits grouped by bot, path, status, day, or category to reveal which AI assistants can fetch your site, what they read, and crawl failures that may lose citations.

Instructions

The same requests as list_bot_visits, counted by the API rather than listed. groupBy picks the question:

  • bot — which assistants read the site, and which never turn up

  • path — what they read, the nearest thing to knowing what they can quote

  • status — crawl health: every 4xx and 5xx is a page an assistant tried to read and could not

  • day — whether the attention is growing or fading

  • category — bots fetching for a waiting user against those building an index

A failing status is worth more than its count suggests: an assistant that cannot fetch a page does not retry it for the person waiting, it answers from something else. Each one is a citation that went elsewhere.

botId=chatgpt-user with groupBy=path is the sharpest reading here — that bot fetches because somebody has just asked ChatGPT something, so those paths are being read into answers as they are requested.

The answer is ranked, not paged: the limit largest groups come back and there is no cursor. partial is true when the period held more requests than could be read, so the counts then describe the newest ones only.

A bot visit is a machine fetching a page, not a person reading one. It is the supply side of visibility: an assistant can only quote a page its bot was able to fetch, so this says whether the site is reachable and readable to them at all. It is a different measurement from being named in an answer (list_prompts, list_competitors), from being cited as a source (list_sources), and from somebody arriving afterwards (get_ai_traffic). kind=ai is the assistants; kind=seo is classic search engines and SEO tools.

A request carries the name of the bot in its User-Agent, which is free text anybody can send, so each one is marked verified or not. The API has no filter for it and counts cannot be split by it, so any total here includes requests that only claimed to be that bot. Report a count as an upper bound and say so; never present it as measured reach without the caveat.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
kindNo`ai` for AI assistants and their bots, `seo` for search engines and SEO tools. Omit it for both.
pathNoOnly this exact path, without the domain and starting with `/`, e.g. `/pricing`.
botIdNoOnly this one bot, by the id the other traffic tools report — `chatgpt-user`, `gptbot`, `googlebot` and so on. An unknown id is rejected by the API rather than ignored.
limitNoHow many groups to return, at most 200.
statusNoAn exact HTTP status code, or a class such as `4xx` to see only the failures.
vendorNoOnly bots run by this company, spelled as the API spells it: OpenAI, Anthropic, Google, Perplexity, Meta, Amazon, Apple, Microsoft, ByteDance, Yandex, DuckDuckGo, Ahrefs, Semrush, Moz, CommonCrawl, Mistral, Cohere and others. This is not the `assistant` of get_ai_traffic, which matches a referrer instead.
endDateNoLast day to report on, inclusive. Defaults to today, and must be within 31 days of startDate — these endpoints read a month at a time, not a year.
groupByYesWhat to count by.
startDateNoFirst day to report on, inclusive. Defaults to 30 days before today.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.0.16

TDQS

A5/5.0
Behavior5/5

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

The description discloses key behavioral traits beyond the annotations: it is read-only (consistent with readOnlyHint=true), it returns ranked results not paged (with no cursor), it has a 'partial' flag indicating truncated counts, and it warns about User-Agent spoofing (bot IDs are free text, counts are upper bounds). It also explains the semantics of status codes and the difference between kind=ai and kind=seo. This goes far beyond the annotations and is essential for correct usage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence carries weight. It opens with the core purpose, then systematically covers groupBy semantics, pagination behavior, spoofing caveats, and differentiation from related tools. It uses paragraphs and bullet-like formatting for readability. No redundant phrases; each sentence either informs or directs the agent.

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?

Given the tool's complexity (9 parameters, 5 groupBy modes, status patterns, multiple related tools), the description is remarkably complete. It explains return structure (ranked, partial flag), the meaning of counts (upper bounds due to spoofing), and the practical significance of failures. Since there is no output schema, this description fully compensates by explaining what the agent should expect and how to interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema already covers all parameters (100% coverage), the description adds substantial meaning: it elaborates on the groupBy enum values ('bot', 'path', 'status', 'day', 'category') with concrete interpretations, explains the 31-day date window, clarifies that vendor is not the same as get_ai_traffic's assistant, and provides examples of botId values. It also warns about the spoofing issue affecting count accuracy. This is far beyond the schema's per-parameter descriptions.

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 description opens with a precise statement: 'The same requests as list_bot_visits, counted by the API rather than listed.' This clearly identifies the verb (count), the resource (bot visits), and differentiates it from its listing sibling. It also explains the groupBy options and their meanings, leaving no ambiguity about what the tool does.

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?

It explicitly contrasts with list_bot_visits ('counted by the API rather than listed') and names alternative tools (list_prompts, list_competitors, list_sources, get_ai_traffic) to clarify when not to use this tool. It also provides a concrete recommendation: 'botId=chatgpt-user with groupBy=path is the sharpest reading here.' This is actionable guidance an agent can follow.

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

Deploy Server

Other Tools