prompteye-mcp

Official

by PROMPTEYE-SP-Z-O-O

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

List the domains assistants cite

list_sources

Read-only

The domains the assistants leaned on when answering the project's prompts, ranked by how often they were cited. Call this to see which pages shape what the assistants say about the brand, and where to go to change it.

Instructions

A cited domain is a site an assistant leaned on while answering the project's prompts. sourceOccurrences counts every time a page on that exact host appeared among an answer's sources, so one answer citing two of its pages counts twice, and other domains of the same brand are not added in. It is a count of sources, not of answers, so it is not comparable with citedAnswers from list_competitors. share is the domain's slice of every source occurrence on those prompts, so the domains describe one pie. ownDomain marks the project's own domain and the alternatives registered with it: a small own share means the assistants are describing the brand from other people's pages rather than its own, which is where the story about it is being written.

When the own domain holds a small share, create_content_brief starts an article of the brand's own for the assistants to cite on the prompt it targets.

The ranking answers with the most cited domains rather than a list to walk to the end of, so raise limit to see further down. model narrows it to one assistant, which is how to tell a source every assistant trusts from one that only a single assistant leans on.

Narrow the count to one prompt (promptId), one prompt group (groupId), or one category — categoryId alone, or categoryId with subcategoryId — the same way the app's own screens narrow it. Give at most one of these; combining them fails. list_source_pages does not take them.

includeOffers adds the WhitePress offers for each cited domain: a new sponsored article (price), a link insert in an existing article (linkInsert) or a mention in an existing article (mention), the latter two priced by linkOrMentionPriceFrom; plus DR and estimated monthly visits. Use it to build a shortlist of cited domains where the brand can buy a placement and rank them by cost per citation — the cheapest available price (price or linkOrMentionPriceFrom) divided by sourceOccurrences, which you compute yourself. Link and mention offers are checked in the background, so a domain seen for the first time may show none yet; calling again later can fill it. The own domain never carries an offer. The call takes noticeably longer because the offers are fetched, so before passing it ASK the user whether they want offers — unless the user already asked for prices, sponsored publications or where to buy articles, then pass it straight away.

Input Schema

Name	Required	Description
`limit`	No	How many domains to return, at most 200.
`model`	No	Report on this assistant alone instead of all of them.
`endDate`	No	Last day to report on, inclusive. Defaults to today, and must be within 366 days of startDate.
`groupId`	No	Count citations from this prompt group alone instead of every prompt in the project.
`promptId`	No	Count citations from this prompt alone instead of every prompt in the project.
`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.
`categoryId`	No	Count citations from only the prompts filed under this category, subcategories included.
`includeOffers`	No	Add each cited domain's sponsored publication offer (WhitePress availability, price, currency, DR, estimated monthly visits). Slower; ask the user first.
`subcategoryId`	No	Narrow `categoryId` further, to one of its subcategories. Needs `categoryId` alongside it.

Output Schema

Name	Required	Description
`data`	Yes
`brand`	Yes
`model`	Yes	The assistant the ranking is narrowed to. null = all assistants.
`nextCursor`	Yes	Pass as cursor to read the next page. null = this was the last page.
`projectName`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.0.28Oct 23, 2026

addedInput schema / properties / includeOffers

Added value: +{
+  "description": "Add each cited domain's sponsored publication offer (WhitePress availability, price, currency, DR, estimated monthly visits). Slower; ask the user first.",
+  "type": "boolean"
+}

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"
+]
```

addedOutput schema / properties / data / items / properties / offer

Added value: +{
+  "additionalProperties": false,
+  "description": "The sponsored publication offer for the domain. Present only when includeOffers was passed, and never on the own domain.",
+  "properties": {
+    "available": {
+      "description": "Whether WhitePress sells anything on this domain: a new sponsored article, a link insert in an existing article, or a mention in an existing article.",
+      "type": "boolean"
+    },
+    "currency": {
+      "description": "The currency of `price`. null = no new article on sale.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "domainRank": {
+      "description": "The domain's DataForSEO rank, shown as DR in the app. null = unknown.",
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "linkInsert": {
+      "description": "Whether a link can be bought in an existing article on this domain.",
+      "type": "boolean"
+    },
+    "linkOrMentionCurrency": {
+      "description": "The currency of `linkOrMentionPriceFrom`. null = none or not checked yet.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "linkOrMentionPriceFrom": {
+      "description": "The cheapest link insert or mention price, in `linkOrMentionCurrency`. null = none or not checked yet.",
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "mention": {
+      "description": "Whether a brand mention can be bought in an existing article on this domain.",
+      "type": "boolean"
+    },
+    "monthlyVisits": {
+      "description": "Estimated monthly organic visits to the domain. null = unknown.",
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "price": {
+      "description": "The price of a NEW sponsored article, in `currency`. null = no new article on sale.",
+      "type": [
+        "number",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "available",
+    "price",
+    "currency",
+    "linkInsert",
+    "mention",
+    "linkOrMentionPriceFrom",
+    "linkOrMentionCurrency",
+    "domainRank",
+    "monthlyVisits"
+  ],
+  "type": "object"
+}

Changed5 schema fields changedv1.0.22Oct 2, 2026

addedInput schema / properties / categoryId

Added value: +{
+  "description": "Count citations from only the prompts filed under this category, subcategories included.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / groupId

Added value: +{
+  "description": "Count citations from this prompt group alone instead of every prompt in the project.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / promptId

Added value: +{
+  "description": "Count citations from this prompt alone instead of every prompt in the project.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / subcategoryId

Added value: +{
+  "description": "Narrow `categoryId` further, to one of its subcategories. Needs `categoryId` alongside it.",
+  "minLength": 1,
+  "type": "string"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "brand": {
+      "type": "string"
+    },
+    "data": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "domain": {
+            "type": "string"
+          },
+          "ownDomain": {
+            "description": "Whether it is the project's own domain or one of its alternatives.",
+            "type": "boolean"
+          },
+          "share": {
+            "description": "The domain's share of the source occurrences across the domains reported, in percent 0-100 with up to five decimals.",
+            "type": "number"
+          },
+          "sourceOccurrences": {
+            "description": "Times a page on this exact host appeared among an answer's sources; a count of sources, not answers.",
+            "type": "number"
+          }
+        },
+        "required": [
+          "domain",
+          "sourceOccurrences",
+          "share",
+          "ownDomain"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "model": {
+      "description": "The assistant the ranking is narrowed to. null = all assistants.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "nextCursor": {
+      "description": "Pass as cursor to read the next page. null = this was the last page.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "projectName": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "data",
+    "nextCursor",
+    "projectName",
+    "brand",
+    "model"
+  ],
+  "type": "object"
+}

First observedv1.0.5Sep 16, 2026

TDQS

A5/5.0

Behavior5/5

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

Beyond the readOnlyHint and openWorldHint annotations, the description explains counting semantics (sourceOccurrences counts each page occurrence, not answers), share as a slice of one pie, ownDomain behavior, and that includeOffers makes the call noticeably slower with background offer checks. It also warns that combining filters fails and that the own domain never carries an offer.

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 front-loaded with purpose and organized into focused paragraphs covering counts, filters, offers, and user-asking behavior. Every sentence adds a distinct operational detail, and none repeat the schema or annotations.

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 an output schema and safety annotations already present, the description still covers the ranking behavior, filter constraints, offer semantics, background-fetch timing, and the need to ask before using includeOffers. It leaves no material ambiguity for selecting or invoking the tool correctly.

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 schema coverage is 100%, the description adds substantial meaning: limit is a ranking cutoff rather than pagination, model distinguishes a broadly trusted source from one assistant's preference, and at most one of promptId/groupId/categoryId may be given, with categoryId optionally paired with subcategoryId. It also explains includeOffers' added fields and the cost-per-citation calculation.

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 specific resource and ranking: 'The domains the assistants leaned on when answering the project's prompts, ranked by how often they were cited.' It clearly distinguishes the tool from list_source_pages and list_competitors, so an agent can identify its role 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 gives explicit usage conditions: use includeOffers to build a shortlist and compute cost per citation, and ASK the user before passing it unless they already asked for prices or sponsored publications. It names alternatives such as list_source_pages and list_competitors, and explains how to narrow the count with promptId, groupId, or categoryId.

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

Deploy Server