prompteye-mcp

Official

Overview Schema Source Related Servers Discussions Admin

Start a brand analysis run

create_brand_analysis_run

Starts a brand analysis run for the active project, identifying topics where competitors outperform your brand and scoring each gap.

Instructions

Starts a brand analysis run for the active project: PromptEye looks at what the tracked prompts most recently found, works out the topics where a competitor answers better than this brand, and scores how big each gap is.

Starting one is instant; the analysis itself takes a little while. The run comes back processing and turns ready once it finishes, or error / corrupted_response if it fails — read it with get_brand_analysis_run until it does.

A run cannot always be started: one already in progress blocks another, and a run that already used the project's current tracking results is not repeated until they change. Call get_brand_analysis_availability first to know whether — and why — one can run; this call is refused for exactly the same reasons. Running an analysis also counts against the workspace's monthly plan quota for brand analyses.

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Output Schema

TableJSON Schema

Name	Required	Description
`id`	Yes
`gaps`	Yes	The topics where a competitor answers better than this brand. Empty until ready.
`error`	Yes	Why the run failed. null unless status is error or corrupted_response.
`status`	Yes	processing the moment it is requested, then ready, or error / corrupted_response when it failed — see error.
`createdAt`	Yes	When the run was requested, ISO 8601 in UTC.
`projectId`	Yes
`sentiment`	Yes	How the assistants talk about the brand when they mention it. null until ready.
`totalCost`	Yes
`updatedAt`	Yes	When the run last changed, ISO 8601 in UTC.
`maxContextGaps`	Yes	How many gaps this run may report at most.
`usedResultCount`	Yes	How many tracking results fed this run.
`activePromptCount`	Yes	How many active tracked prompts fed this run.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.0.22Oct 2, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations mark this as non-read-only, non-idempotent and open-world, and the description adds substantial context beyond that: the run is asynchronous, returns `processing` and later `ready`/`error`/`corrupted_response`, is blocked by an in-flight run or unchanged inputs, and consumes the workspace's monthly brand-analysis quota. That quota and blocking disclosure is exactly the kind of behavioral detail annotations cannot express.

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 tight paragraphs that front-load what the tool does, then lifecycle, then constraints. Every sentence carries information (states, polling, blocking rules, quota), though the lifecycle detail borders on verbose for a zero-parameter call.

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?

Despite an output schema existing, the description still supplies the asynchronous state machine and the refusal conditions an agent needs to call this correctly and interpret the returned status. Nothing needed to invoke or follow up 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?

The tool takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The description correctly spends no words on inputs.

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?

States a specific verb and resource ('starts a brand analysis run for the active project') and immediately explains the actual work performed: comparing tracked prompts against competitors to find and size topical gaps. This is clearly distinguishable from sibling analysis tools like create_audit or create_topical_map.

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 prerequisites and routing: call get_brand_analysis_availability first to learn whether and why a run is possible, and use get_brand_analysis_run to poll the result. It also names the exact conditions under which this call is refused (a run in progress, unchanged tracking results).

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

Deploy Server