prompteye-mcp

Official

by PROMPTEYE-SP-Z-O-O

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

Rank the brands answering alongside yours

list_competitors

Read-only

Every brand the assistants named on the project's prompts, measured the same way the project's own brand is and ranked by visibility, then by average position. Call this for 'who are we losing to' and for how a market splits between brands.

Instructions

The order is not share of voice. The ranking is cut to the strongest brands by visibility first, so re-sorting what it returns by share of voice does not give the strongest brands by share of voice.

Changes are signed so that positive always means improvement. For average position that means the brand was named earlier in the answer, so a positive change goes with a lower position number.

shareOfVoice is how much of all the naming that happened on the project's prompts went to one brand, so the brands in a ranking describe one pie. It answers a different question from visibility: visibility is how often a brand was named at all, and every brand can score high at once, while share of voice is what each took from the others. citedAnswers counts the answers that cited at least one domain assigned to the brand, its own or an alternative one, each domain at most once per answer, and citationShare is the share of answers carrying sources that did. It is a count of answers, not of sources, so it is not comparable with sourceOccurrences from list_sources, which counts every source on one host. Being cited can diverge from being named — a brand can be recommended without being linked, and linked without being recommended. The project's own brand is in the ranking and marked with ownBrand, so it can be read against the rest.

visibility is the share of answers that named the brand, 0 to 100; reachIndex is that figure weighted by how much of the market each assistant carries; averagePosition is where in the answer the brand was named, counting from 1. Each is null until it is measured.

The ranking answers with the strongest brands 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 brand that dominates everywhere from one that owns a single assistant.

Narrow the ranking to one prompt (promptId), one prompt group (groupId), or one category — categoryId alone, or categoryId with subcategoryId — the same way the app's own visibility screen narrows it. Give at most one of these; combining them fails. There is no single call for 'which prompts does competitor X outrank us on' — call list_prompts for the prompt ids, then this tool once per promptId, and keep the ones where the named competitor's position beats the brand's.

Input Schema

Name	Required	Description
`limit`	No	How many brands 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	Rank this prompt group alone instead of every prompt in the project.
`promptId`	No	Rank 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	Rank only the prompts filed under this category, subcategories included.
`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.

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

Changed5 schema fields changedv1.0.22Oct 2, 2026

addedInput schema / properties / categoryId

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

addedInput schema / properties / groupId

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

addedInput schema / properties / promptId

Added value: +{
+  "description": "Rank 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": {
+          "brand": {
+            "type": "string"
+          },
+          "change": {
+            "anyOf": [
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "averagePosition": {
+                    "description": "Places moved, signed so positive = named earlier (an improvement). null = either period could not measure it.",
+                    "type": [
+                      "number",
+                      "null"
+                    ]
+                  },
+                  "reachIndex": {
+                    "description": "Points reachIndex moved by; negative = fell. null = either period could not measure it.",
+                    "type": [
+                      "number",
+                      "null"
+                    ]
+                  },
+                  "visibility": {
+                    "description": "Percentage points visibility moved by; negative = fell. null = either period could not measure it.",
+                    "type": [
+                      "number",
+                      "null"
+                    ]
+                  }
+                },
+                "required": [
+                  "visibility",
+                  "reachIndex",
+                  "averagePosition"
+                ],
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Movement against the period of the same length directly before this one. null = no figure could be compared."
+          },
+          "citationShare": {
+            "description": "Share of the answers carrying any sources that cited this brand, in whole percent 0-100; brands do not add up to 100. null = no answer carried sources.",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "citedAnswers": {
+            "description": "Answers citing at least one domain of this brand, each domain once per answer; a count of answers, not sources. null = no figure for the period.",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "metrics": {
+            "additionalProperties": false,
+            "properties": {
+              "averagePosition": {
+                "description": "Mean place the brand was named at in the answers that named it, counting from 1; lower is earlier. null = not measured.",
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "reachIndex": {
+                "description": "Visibility weighted by how much of the market each assistant carries, 0-100, whole number. null = not measured.",
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "visibility": {
+                "description": "Share of answers that named the brand in the period, in percent 0-100. null = not measured.",
+                "type": [
+                  "number",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "visibility",
+              "reachIndex",
+              "averagePosition"
+            ],
+            "type": "object"
+          },
+          "ownBrand": {
+            "description": "True for the project's own brand, ranked alongside the rest.",
+            "type": "boolean"
+          },
+          "shareOfVoice": {
+            "description": "How much of the naming this brand took, in whole percent 0-100; all brands in the period add up to 100. null = no figure for the period.",
+            "type": [
+              "number",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "brand",
+          "ownBrand",
+          "metrics",
+          "change",
+          "shareOfVoice",
+          "citedAnswers",
+          "citationShare"
+        ],
+        "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

A4.7/5.0

Behavior5/5

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

With readOnlyHint and openWorldHint already covering safety, the description still adds substantial behavior: truncation semantics ("the strongest brands rather than a list to walk to the end of"), signed-change convention where positive always means improvement including the counterintuitive average-position inversion, nulls until measured, and a concrete failure mode ("Give at most one of these; combining them fails"). These are operational facts an agent could not infer from annotations.

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

Conciseness3/5

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

Purpose and the when-to-call are front-loaded and no sentence is pure filler, but the middle block spends several sentences glossing shareOfVoice, visibility, reachIndex, averagePosition, citedAnswers and citationShare — metrics an output schema already exists to document. The structure is sound; the length is partly duplication of structured data.

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 nine-parameter, multi-metric ranking tool this covers the full picture: what is ranked and why in that order, how to widen or narrow the cut, how the own brand appears in the results, how each metric relates to a sibling metric, and the workaround for a question the tool does not answer directly. Nothing needed to call it 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%, so the baseline is 3, but the description adds real meaning: `model` is framed as the way to tell a brand that dominates everywhere from one that owns a single assistant, `limit` is tied to the ranking's truncation, and the promptId/groupId/categoryId/subcategoryId family carries a mutual-exclusivity rule the schema does not state. Date-window constraints are left entirely to the schema.

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?

Opens with a specific verb and resource — every brand named by the assistants on the project's prompts, measured like the project's own brand and ranked by visibility then average position. It explicitly distinguishes itself from the share-of-voice ordering an agent might assume and names the sibling (list_prompts) needed for a related but different question, so it is unmistakable against list_sources or list_prompts.

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?

Gives explicit use cases ("who are we losing to", how a market splits between brands) plus an explicit anti-pattern: re-sorting by share of voice does not yield the strongest brands by share of voice. It also states what this tool cannot do and routes to the alternative ("call list_prompts for the prompt ids, then this tool once per promptId"), which is exactly the when/when-not/alternatives pattern.

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

Deploy Server