prompteye-mcp

Official

by PROMPTEYE-SP-Z-O-O

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

Read one prompt

get_prompt

Read-only

One prompt of the project, with its visibility broken down per assistant — only the assistants that actually answered are listed. Call this to see which assistant is carrying a prompt and which is dropping the brand from it.

Instructions

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.

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.

aiTraffic is the demand behind a prompt: PromptEye expands the question into the phrasings people actually use for it, weighs each one by how much of the question it carries, and adds up how much demand they attract per month. It is a property of the prompt, not a measurement of a period. 0 means it was measured and the demand is below the reporting floor of 50 searches a month. null means there is no figure: with aiTrafficMeasuredAt null it has not been measured yet, with a date it was measured and none of the phrasings came back with a volume, so it is unknown rather than zero. aiTrafficMeasuredAt is when the figure was last measured; a failed refresh keeps the earlier figure and its date. It is not what get_ai_traffic reports: that tool counts sessions that actually reached the site from an assistant, while this counts the demand behind the question.

businessPriority is how much the project should bet on a prompt: the average of how close to a purchase the question is asked and where the prompt ranks on demand among the project's own prompts. It is banded very_high above 0.8, high above 0.6, medium above 0.4, low above 0.2 and very_low below that. A priority set by hand in the app wins over the computed one, and the two are not reported apart, so a surprising value may be someone's deliberate call. It is null before the prompt has been ranked.

Input Schema

Name	Required	Description
`endDate`	No	Last day to report on, inclusive. Defaults to today, and must be within 366 days of startDate.
`promptId`	Yes	Id of the prompt, as list_prompts reports it.
`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
`id`	Yes
`change`	Yes	Movement against the period of the same length directly before this one. null = no figure could be compared.
`prompt`	Yes
`status`	Yes	active = asked on every run, paused = not asked, pending = added but not measured yet.
`byModel`	Yes	One entry per assistant that actually answered.
`groupId`	Yes	null = the prompt is ungrouped.
`keyword`	Yes	Keyword the prompt was built around. Empty when it was written by hand.
`metrics`	Yes
`aiTraffic`	Yes	Estimated monthly searches behind the prompt; a property of the prompt, not of the period. 0 = measured, below the reporting floor of 50 searches a month. null = no figure: not measured yet when aiTrafficMeasuredAt is null, otherwise measured with no volume found (unknown, not zero).
`createdAt`	Yes	When the prompt was added, ISO 8601 in UTC.
`categories`	Yes
`subcategories`	Yes
`businessPriority`	Yes	very_high, high, medium, low or very_low. null = not ranked yet. A priority set by hand wins over the computed one.
`aiTrafficMeasuredAt`	No	When aiTraffic was last measured, ISO 8601 in UTC. null = never measured. A failed refresh keeps the previous figure and date.
`businessPriorityReason`	Yes	Why the priority was set by hand. null = the computed priority, or no reason given.

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"
+}

changedInput schema / required

Previous value: -[
-  "promptId"
-]New value: +[
+  "projectId",
+  "promptId"
+]

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": {
+    "aiTraffic": {
+      "description": "Estimated monthly searches behind the prompt; a property of the prompt, not of the period. 0 = measured, below the reporting floor of 50 searches a month. null = no figure: not measured yet when aiTrafficMeasuredAt is null, otherwise measured with no volume found (unknown, not zero).",
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "aiTrafficMeasuredAt": {
+      "description": "When aiTraffic was last measured, ISO 8601 in UTC. null = never measured. A failed refresh keeps the previous figure and date.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "businessPriority": {
+      "description": "very_high, high, medium, low or very_low. null = not ranked yet. A priority set by hand wins over the computed one.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "businessPriorityReason": {
+      "description": "Why the priority was set by hand. null = the computed priority, or no reason given.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "byModel": {
+      "description": "One entry per assistant that actually answered.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "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"
+                ]
+              },
+              "visibility": {
+                "description": "Share of answers that named the brand in the period, in percent 0-100. null = not measured.",
+                "type": [
+                  "number",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "visibility",
+              "averagePosition"
+            ],
+            "type": "object"
+          },
+          "model": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "model",
+          "metrics"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "categories": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "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."
+    },
+    "createdAt": {
+      "description": "When the prompt was added, ISO 8601 in UTC.",
+      "type": "string"
+    },
+    "groupId": {
+      "description": "null = the prompt is ungrouped.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "id": {
+      "type": "string"
+    },
+    "keyword": {
+      "description": "Keyword the prompt was built around. Empty when it was written by hand.",
+      "type": "string"
+    },
+    "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"
+    },
+    "prompt": {
+      "type": "string"
+    },
+    "status": {
+      "description": "active = asked on every run, paused = not asked, pending = added but not measured yet.",
+      "type": "string"
+    },
+    "subcategories": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "id",
+    "prompt",
+    "keyword",
+    "status",
+    "categories",
+    "subcategories",
+    "groupId",
+    "createdAt",
+    "aiTraffic",
+    "businessPriority",
+    "businessPriorityReason",
+    "metrics",
+    "change",
+    "byModel"
+  ],
+  "type": "object"
+}

First observedv1.0.5Sep 16, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond them, explaining that null means unmeasured versus 0 meaning measured-below-floor, that a failed refresh keeps the earlier figure and date, that a hand-set priority silently overrides the computed one, and that sign conventions are inverted for averagePosition. That is exactly the kind of caveat an agent cannot infer. It stops short of 5 because most of the text is per-field semantics rather than tool-level behavior (latency, freshness cadence, access requirements).

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?

The purpose is front-loaded in sentence one, but the description then runs six dense blocks covering every metric, priority band thresholds, and a comparison with get_ai_traffic. Much of that duplicates what an output schema with field definitions would carry, and lines like "It is a property of the prompt, not a measurement of a period" restate rather than add. Well organized but oversized for a single-record read.

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 read-only, four-parameter tool with a 100%-covered schema, existing annotations, and an output schema, nothing an agent needs is absent: it knows the trigger, the sibling boundaries, and the null/zero/staleness traps that would otherwise cause misreads. The only redundancy is that it explains return values at greater length than strictly required.

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 schema already documents projectId, promptId, and the date range, and the description adds nothing about them. It only implicitly signals that the metrics are period-based while aiTraffic is not, which is a small hint about how startDate/endDate affect results. Baseline 3 for a fully documented 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?

The first sentence states a specific verb and resource — read one prompt of a project — plus its scope (visibility broken down per assistant, only assistants that answered). It also distinguishes itself from siblings by naming get_ai_traffic and create_content_brief as different concerns, so an agent can place it 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 Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Call this to see which assistant is carrying a prompt and which is dropping the brand from it" gives an explicit trigger, and "when the brand is weak here, create_content_brief starts an article aimed at this prompt" routes to the natural next step. It also draws a clear boundary against get_ai_traffic. What is missing is any exclusion versus get_prompt_answers or list_prompts, which would complete the when-not guidance.

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

Deploy Server