prompteye-mcp

Official

by PROMPTEYE-SP-Z-O-O

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

List the requests bots made to the site

list_bot_visits

Read-only

The individual requests AI assistants and search engines made to the project's site, newest first — which bot, which path, what the site answered and how long it took.

Instructions

The individual requests AI assistants and search engines made to the project's site, newest first — which bot, which path, what the site answered and how long it took.

This is the evidence layer: call it to show what actually happened, or to see what a bot got when a page moved. For totals call count_bot_visits instead — paging through this to add requests up gives a wrong number, because only the newest 4 000 requests of the period are searched and a rarely matching filter comes back short of what the period held.

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.

A project whose integration is not connected answers this with zeros and empty lists, which reads exactly like a site nobody visits. Call get_integrations_status before reporting a zero or an empty list as a finding: it says whether Search Console, Google Analytics, the bot tracker and the sitemap are connected, and a sync that is failing. Not connected means the figures say nothing about the site, never that it had no traffic; say the integration is missing and that it can be connected in the PromptEye app.

Input Schema

Name	Required	Description
`kind`	No	`ai` for AI assistants and their bots, `seo` for search engines and SEO tools. Omit it for both.
`path`	No	Only this exact path, without the domain and starting with `/`, e.g. `/pricing`.
`botId`	No	Only 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.
`limit`	No	How many entries to return, at most 200. Defaults to 50.
`cursor`	No	The nextCursor of the previous page. Omit it to start from the first one.
`status`	No	An exact HTTP status code, or a class such as `4xx` to see only the failures.
`vendor`	No	Only 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.
`endDate`	No	Last 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.
`projectId`	Yes	The project to work on — its id from list_projects. Required on every call, so that parallel conversations never read or write each other's project.
`startDate`	No	First day to report on, inclusive. Defaults to 30 days before today.

Output Schema

Name	Required	Description	Default
`data`	Yes
`nextCursor`	Yes	Pass as cursor to read the next page. null = this was the last page.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.0.28Oct 23, 2026

addedInput schema / properties / projectId

Added value: +{
+  "description": "The project to work on — its id from list_projects. Required on every call, so that parallel conversations never read or write each other's project.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / required
```
Added value: +[
+  "projectId"
+]
```

Changed1 schema field changedv1.0.22Oct 2, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "data": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "at": {
+            "description": "When the bot made the request, ISO 8601 in UTC.",
+            "type": "string"
+          },
+          "botId": {
+            "type": "string"
+          },
+          "botType": {
+            "type": "string"
+          },
+          "category": {
+            "enum": [
+              "agent",
+              "assistant",
+              "search"
+            ],
+            "type": "string"
+          },
+          "country": {
+            "description": "Two-letter country the request came from. null = unknown.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "id": {
+            "type": "string"
+          },
+          "kind": {
+            "description": "ai = an AI assistant's bot, seo = search engines and SEO tools.",
+            "enum": [
+              "ai",
+              "seo"
+            ],
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          },
+          "redirectLocation": {
+            "description": "Where a redirect pointed. null = not a redirect.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "referer": {
+            "description": "The referrer the bot sent. null = none.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "responseTimeMs": {
+            "description": "How long the site took to answer, in milliseconds. null = not reported.",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "statusCode": {
+            "description": "HTTP status the site answered with. null = none reported.",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "vendor": {
+            "type": "string"
+          },
+          "verified": {
+            "description": "Whether the origin was confirmed as the bot it claims to be; false also when it could not be checked. Unverified requests are claims, so counts are upper bounds.",
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "id",
+          "at",
+          "botId",
+          "name",
+          "vendor",
+          "botType",
+          "kind",
+          "category",
+          "path",
+          "statusCode",
+          "redirectLocation",
+          "responseTimeMs",
+          "country",
+          "referer",
+          "verified"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "nextCursor": {
+      "description": "Pass as cursor to read the next page. null = this was the last page.",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "data",
+    "nextCursor"
+  ],
+  "type": "object"
+}

Addedv1.0.16Sep 23, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered; the description goes well beyond that by disclosing the 4 000-request search cap, the fact that only a bounded tail is searched (so filters can come back short), the verified/not-verified marking with no API filter for it, and that an unconnected integration returns zeros. These are nontrivial behavioral caveats an agent cannot infer from structured data.

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 long — five paragraphs — but front-loaded with purpose and routing, and each paragraph carries distinct value (routing, definition, verification caveat, integration caveat). A little narrative padding ('the supply side of visibility') could be trimmed, keeping it just below the top mark.

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?

Output schema exists so return values need no explanation, and the description covers the remaining agent-critical context: pagination via cursor, the search cap, the verified caveat, and the zero-vs-not-connected trap. Nothing needed to call or interpret this correctly is missing.

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

Parameters4/5

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

Schema coverage is 100% and the schema itself documents kind, path, botId, vendor, status, dates and cursor thoroughly, so the baseline is 3. The description still adds cross-tool meaning, notably that `vendor` is not the `assistant` field of get_ai_traffic, and reiterates the kind=ai/seo split — genuine semantics beyond the schema text.

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 names a concrete verb and resource ('individual requests AI assistants and search engines made to the project's site') plus the facts returned, and the body explicitly separates it from count_bot_visits, list_prompts, list_competitors, list_sources and get_ai_traffic. An agent can route correctly without opening the 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?

It states when to call it ('to show what actually happened, or to see what a bot got when a page moved') and when not to (totals belong in count_bot_visits, with the reason: only the newest 4 000 requests are searched). It also adds a pre-check rule — call get_integrations_status before reporting a zero — which is exactly the exclusions guidance this dimension rewards.

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

Deploy Server