prompteye-mcp

Official

by PROMPTEYE-SP-Z-O-O

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

Check whether new suggestions can be generated for a group

get_prompt_suggestion_availability

Read-only

Check whether a prompt group can start a new suggestion run right now and why not, so you can diagnose empty or failed runs before polling for results.

Instructions

Whether generate_prompt_suggestions would schedule a new run for one prompt group of the project right now, and if not, why — the same check that tool runs itself, without scheduling anything.

After calling generate_prompt_suggestions, poll this endpoint until lastRun.status is not running. When a run finishes with producedCount 0, read emptyReason (or error if status is failed) to see why no suggestions were generated. list_prompt_suggestions returns only pending suggestions that have not yet been accepted or rejected.

Input Schema

Name	Required	Description	Default
`groupId`	Yes	Id of the prompt group, as list_prompt_groups 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.

Output Schema

Name	Required	Description
`canRun`	Yes	Whether generate_prompt_suggestions would schedule a run right now.
`reason`	Yes	Why a run would or would not be scheduled: not_eligible = the project's plan does not currently pay for background work, no_slots = no free prompt slots remain on the plan, running = a run is already in progress for this group, cooldown = the last run finished less than 7 days ago and its proposals still await a decision, nothing_to_suggest = the group is already healthy, or too few of its prompts are measured yet (a run needs at least 5 active prompts scored for purchase intent, or at least 2 with a computed business priority), ready = nothing is blocking a new run.
`lastRun`	Yes	This group's most recent run. null = it never had one.
`availableSlots`	Yes	Free prompt slots left on the plan; a run proposes at most this many.
`pendingSuggestionCount`	Yes	Suggestions from this group still awaiting a decision.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.0.30Oct 26, 2026

changedOutput schema / properties / reason / description

Previous value: -"Why a run would or would not be scheduled: not_eligible = the project's plan does not currently pay for background work, no_slots = no free prompt slots remain on the plan, running = a run is already in progress for this group, cooldown = the last run finished less than 7 days ago and its proposals still await a decision, nothing_to_suggest = the group is already healthy, ready = nothing is blocking a new run."New value: +"Why a run would or would not be scheduled: not_eligible = the project's plan does not currently pay for background work, no_slots = no free prompt slots remain on the plan, running = a run is already in progress for this group, cooldown = the last run finished less than 7 days ago and its proposals still await a decision, nothing_to_suggest = the group is already healthy, or too few of its prompts are measured yet (a run needs at least 5 active prompts scored for purchase intent, or at least 2 with a computed business priority), ready = nothing is blocking a new run."

Changed3 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: -[
-  "groupId"
-]New value: +[
+  "projectId",
+  "groupId"
+]

changedOutput schema / properties / lastRun / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "finishedAt": {
-        "description": "When it finished, ISO 8601 in UTC. null = still running.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "startedAt": {
-        "description": "When the run started, ISO 8601 in UTC.",
-        "type": "string"
-      },
-      "status": {
-        "description": "running, completed or failed.",
-        "type": "string"
-      }
-    },
-    "required": [
-      "status",
-      "startedAt",
-      "finishedAt"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "emptyReason": {
+        "anyOf": [
+          {
+            "description": "Why a completed run produced no suggestions: no_phrases = no search phrases could be derived for the group topic, no_phrase_volume = phrases have no measurable search demand, filtered_out = candidates did not match the funnel stage the group lacks, all_duplicates = every candidate duplicated existing prompts or earlier suggestions.",
+            "enum": [
+              "no_phrases",
+              "no_phrase_volume",
+              "filtered_out",
+              "all_duplicates"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "null when the run produced suggestions, failed, or is an older run recorded before reasons were kept. Otherwise why a completed run produced none."
+      },
+      "error": {
+        "description": "Failure message when the status is failed; null otherwise.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "finishedAt": {
+        "description": "When it finished, ISO 8601 in UTC. null = still running.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "producedCount": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "How many suggestions the run produced. null while the run has not finished. 0 on a finished run means it came back empty: read emptyReason (or error when status is failed) to see why."
+      },
+      "startedAt": {
+        "description": "When the run started, ISO 8601 in UTC.",
+        "type": "string"
+      },
+      "status": {
+        "description": "running, completed or failed.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "status",
+      "startedAt",
+      "finishedAt"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Addedv1.0.22Oct 2, 2026

TDQS

A4.3/5.0

Behavior4/5

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

With readOnlyHint=true already declared, the description still adds real value by stating nothing is scheduled and by explaining how to interpret fields (lastRun.status polling, producedCount 0 → read emptyReason, failed → error). It does not touch on rate limits or auth requirements, but the safety profile is fully covered by annotations plus the 'without scheduling anything' guarantee.

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?

Three sentences, front-loaded with the core purpose and then the operational guidance. Every sentence carries information, though the final sentence about list_prompt_suggestions is a slight non sequitur relative to the polling workflow and could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-field documentation is not required, and the description still usefully maps status/producedCount/emptyReason to diagnostic meaning. Purpose, workflow, and sibling differentiation are all present; only minor gaps (e.g., what conditions make availability false before any run) remain.

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%, and the schema already explains both projectId (from list_projects) and groupId (from list_prompt_groups). The description only implicitly reinforces that both scoping identifiers are required via 'one prompt group of the project,' adding no new syntax or format detail, so the baseline 3 applies.

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 opening sentence states a precise purpose: a pre-flight availability check for generate_prompt_suggestions scoped to one prompt group, and explicitly says it is the same check that tool runs internally without scheduling anything. It is clearly distinguishable from generate_prompt_suggestions (which schedules) and list_prompt_suggestions (which lists results).

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 a concrete workflow: call it to see whether a run would be scheduled, and after generate_prompt_suggestions, poll until lastRun.status is not running. It also names the alternative sibling list_prompt_suggestions and explains its differing semantics (only pending suggestions), so an agent knows which to reach for.

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

Deploy Server