Demand Discovery AI

Check / stream the paid Demand Discovery Report

get_demand_report_status

Read-onlyIdempotent

Poll the status of a paid Demand Discovery Report after the user has started checkout with validate_real_demand. Call this with the orderId it returned, once the user says they've paid. The report builds over ~2-3 minutes. If your runtime supports repeated tool execution, call this every ~10-15s, rendering each new block as it arrives, until status is "ready". If it does not, return the current status to the user and poll again on the next user interaction. Each poll is cheap and returns everything generated so far.

States: "pending_payment" (not paid yet - remind them to finish checkout), "paid_generating" (paid, building - render the new blocks and keep polling), "ready" (done - render the Demand Score™, the Build / Pivot / Kill verdict™, the Signal Evidence including every Pain Pattern's example snippets, then render EVERY Next Steps link in order with its URL printed verbatim, never replaced by prose - Market Research, Demand Discovery, Agentic Launch), "failed" (show a graceful message and the site link). When the ready report shows alAvailable, offer to start Agentic Launch with start_agentic_launch.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`orderId`	Yes	REQUIRED. The order handle returned by validate_real_demand.

Output Schema

TableJSON Schema

Name	Required	Description
`done`	Yes	True when generation is complete (no more blocks coming).
`paid`	Yes	True once payment is confirmed (status paid_generating or ready).
`ready`	Yes	True when the full inline report is available in `report`.
`blocks`	No	Report blocks generated so far (cumulative). Render any seq you haven't shown yet.
`report`	No	Present when ready: the inline cut's machine-readable fields. The full breakdown stays on reportUrl.
`status`	Yes	pending_payment \| paid_generating \| ready \| failed \| unknown_order \| unconfigured_fallback \| error_fallback.
`nextSteps`	No	Ordered end-of-report navigation links, present when ready: Market Research (only if DD provided it) -> Demand Discovery -> Agentic Launch. When you render from structuredContent (not the report markdown), render these in order as the final navigation, ALWAYS keeping the Demand Discovery link alongside Market Research. Markdown clients should use the links already in the report markdown instead of re-rendering these. The agentic_launch entry's actionTool names the tool to CALL when the user wants to generate prospects; its url is the section to land on afterward.
`reportUrl`	No	Link to the full hosted report (Score Breakdown + all analytics).
`nextAction`	Yes	What to do next.
`productUrl`	Yes
`marketResearchUrl`	No	Link to the earlier free Market Research page for this idea, when DD provides it. Passthrough only — link reportUrl as the primary report.

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare readOnly, idempotent, and non-destructive hints, reducing the burden. The description goes far beyond by enumerating all states with precise handling instructions, revealing that 'Each poll is cheap and returns everything generated so far', and detailing exactly what to render at each stage. No contradiction with annotations.

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?

Although lengthy, the description is dense with actionable content. It is front-loaded with the core purpose, then systematically covers polling behavior, states, and rendering. Every sentence earns its place; the only minor issue is a typo ('alAvailable'), but it does not detract from clarity or structure.

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?

Given the tool's complexity (polling, streaming, multiple states), the description is exceptionally complete. With an output schema present, it correctly focuses on behavior rather than return formats. It also integrates with sibling tools and provides fallback logic, leaving no obvious gaps for an agent to invoke and handle the tool correctly.

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?

The input schema already fully describes the only parameter (orderId) as required and sourced from validate_real_demand. The description repeats this ('Call this with the orderId it returned') but adds no new parameter-level meaning beyond reinforcing the flow. Schema coverage is 100%, so baseline 3 is appropriate.

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 verb+resource: 'Poll the status of a paid Demand Discovery Report', clearly distinguishing this tool from siblings like start_demand_report and validate_real_demand. It further clarifies its role in the checkout flow, making the purpose unambiguous.

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?

Explicitly states when to use: 'after the user has started checkout with validate_real_demand', and exactly when to call: 'once the user says they've paid'. Provides polling cadence guidance, fallback behavior for non-polling runtimes, and even directs the next action ('offer to start Agentic Launch with start_agentic_launch'). No alternatives are excluded, but the context is fully specified.

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

All Demand Discovery AI tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0

Disambiguation4/5

Tools have mostly distinct purposes, but ask_demand_discovery is a catch-all that could overlap with explainer tools like explain_demand_signals or get_product_details. The detailed trigger phrases help route correctly, but some ambiguity remains.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (ask_, compare_, explain_, get_, start_, validate_) using snake_case throughout. No mixed conventions or inconsistent patterns.

Tool Count5/5

With 10 tools, the server is well-scoped for its purpose of startup idea validation. Each tool serves a clear role in the workflow, from free research to paid reports to outreach, without unnecessary bloat or missing essentials.

Completeness4/5

The tool set covers the full customer journey (free report, paid report, status polling, outreach launch) and provides educational tools for methodology. Minor gaps like report history or user management are absent but not critical for the primary function.

Resources

Need Help?