Skip to main content
Glama

Validate real demand - start the Demand Discovery Report

validate_real_demand
Idempotent

Check the account status for this idea's full Demand Discovery Report and return the user's next step. This call NEVER moves money and never transacts on the user's behalf - it only looks up whether the given email already has an account with available report slots or a report already running. It returns ONE of: the existing report path (alreadyRunning=true, chargeRequired=false, nothing new started), a no-charge slot path when the idea is already covered, or a secure hosted link the user may CHOOSE to open in their own browser to order the report (normally $49). Any purchase happens entirely on that hosted page and is initiated by the user - never by this tool. Once the order is confirmed, call get_demand_report_status with the returned orderId to stream the finished report into chat.

Demand Discovery’s main deliverable is real people describing your idea, each quote linked to the source, followed by ready-to-post replies to those people.

The Demand Discovery Report grades the idea on a 0-100 Demand Score™ with a Build / Pivot / Kill verdict™, grounded in real behavioral signals (search, conversation, adoption, capital). It normally follows a free Market Research report (start_demand_report). If that step returned a reportId, pass that EXACT id here - it ties the paid order to the existing record. If you do NOT have a reportId, OMIT it entirely; DD resolves the idea from name/problem/solution. NEVER invent, guess, or placeholder a reportId - a fabricated id is rejected.

Call this when the user wants the full/paid report, e.g. "run the $49 report", "yes, validate it for real", "I want the Demand Score", "run Demand Discovery on this", "do the deep report". Pass the SAME name/problem/solution used for the free report so the order ties back to it, the user's email, and the reportId from the free step if you have it.

If a paid report already exists for this idea (for example an existing pack slot was already used), this returns that report's status with alreadyRunning=true instead of starting a new order - in that case do NOT re-run the free step or surface a new payment link; poll get_demand_report_status (when pollWith is set) or open the returned link.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "email": "<email>",
      "name": "<name>",
      "problem": "<problem>",
      "solution": "<solution>"
    },
    "name": "validate_real_demand"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesShort startup or product name - the SAME one used for the free Market Research report.
emailYesREQUIRED. The user's own email, provided by them in chat for report delivery - the order is tied to this email and Agentic Launch replies route here. This was captured at the free Market Research email gate.
problemYesOne sentence on the problem - the SAME wording used for the free report (ties the order back to it).
reportIdNoOptional but strongly preferred: the EXACT reportId returned by the free Market Research step (start_demand_report). It ties the paid order to that record. OMIT it if you don't have one - DD resolves the idea from name/problem/solution. NEVER invent, guess, or placeholder a reportId; a fabricated id is rejected.
solutionYesOne sentence on the solution - the SAME wording used for the free report.
target_marketNoOptional ICP phrase; refines what was captured on the free report if given.
current_workaroundNoOptional: how the audience copes today. Only pass if already known; never block on it.

Output Schema

NameRequiredDescriptionDefault
reasonNoPresent on the needs_upgrade path: 'no_credits' (current pack's reports are used) or 'slot_cap_reached' (every idea slot is occupied).
statusYes'pending_payment' on success; 'already_running'/'processing' if a paid report already exists for this idea; 'needs_upgrade' when the account's current pack has no report slots left (see upsellOptions); 'blocked'/'failed' if the reportId didn't resolve; 'unconfigured_fallback'/'error_fallback' when the inline path was unavailable.
orderIdYesThe order handle to poll with get_demand_report_status. Null if no order was created.
pollWithYesThe tool to call next to stream the report (get_demand_report_status) once paid. Null when not applicable.
expiresAtNoWhen the checkout session expires, if provided.
nextActionYesThe immediate next action the user/agent should take.
productUrlYes
checkoutUrlYesHosted page the user opens in a browser to pay. On fallback/misconfig this is a hosted deep link to continue on the site.
upsellOptionsNoWays the user can keep going when their current pack is used up (or alongside a checkout, as alternatives). Render EVERY option with its link printed verbatim and let the user choose — the user opens links in their own browser; nothing is ever purchased from chat.
alreadyRunningNoTrue if the paid report already exists (running or completed) for this idea - e.g. an existing pack slot was already used. Do NOT start a new checkout or re-run the free step; poll get_demand_report_status (if pollWith is set) or open checkoutUrl.
chargeRequiredNoFalse when no payment is due - the idea is already covered (a plan slot or a prior purchase), so do NOT open a checkout. Present on the alreadyRunning path.
checkoutCreatedYesTrue if a checkout session was created and a checkoutUrl is present.
needsFreeReportFirstYesTrue if the paid step was refused because no valid free Market Research report backs this idea - run start_demand_report first.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedOutput schema / properties / reason
      Added value: +{
      +  "description": "Present on the needs_upgrade path: 'no_credits' (current pack's reports are used) or 'slot_cap_reached' (every idea slot is occupied).",
      +  "type": "string"
      +}
    • changedOutput schema / properties / status / description
      Previous value: -"'pending_payment' on success; 'already_running'/'processing' if a paid report already exists for this idea; 'blocked'/'failed' if the reportId didn't resolve; 'unconfigured_fallback'/'error_fallback' when the inline path was unavailable."New value: +"'pending_payment' on success; 'already_running'/'processing' if a paid report already exists for this idea; 'needs_upgrade' when the account's current pack has no report slots left (see upsellOptions); 'blocked'/'failed' if the reportId didn't resolve; 'unconfigured_fallback'/'error_fallback' when the inline path was unavailable."
    • addedOutput schema / properties / upsellOptions
      Added value: +{
      +  "description": "Ways the user can keep going when their current pack is used up (or alongside a checkout, as alternatives). Render EVERY option with its link printed verbatim and let the user choose — the user opens links in their own browser; nothing is ever purchased from chat.",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "creditNote": {
      +        "type": "string"
      +      },
      +      "label": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "pack": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "url": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "pack",
      +      "label",
      +      "url"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
  2. Changed1 schema field changed
    • changedInput schema / properties / email / description
      Previous value: -"REQUIRED. The buyer's own email, provided by them in chat for report delivery - the order is tied to it and Agentic Launch replies route here. This was captured at the free Market Research email gate."New value: +"REQUIRED. The user's own email, provided by them in chat for report delivery - the order is tied to this email and Agentic Launch replies route here. This was captured at the free Market Research email gate."
  3. Changed1 schema field changed
    • changedInput schema / properties / email / description
      Previous value: -"REQUIRED. The buyer's email - the order is tied to it and Agentic Launch replies route here. This was captured at the free Market Research email gate."New value: +"REQUIRED. The buyer's own email, provided by them in chat for report delivery - the order is tied to it and Agentic Launch replies route here. This was captured at the free Market Research email gate."
  4. Changed4 schema fields changed
    • removedInput schema / properties / name / maxLength
      Removed value: -80
    • removedInput schema / properties / problem / maxLength
      Removed value: -200
    • removedInput schema / properties / solution / maxLength
      Removed value: -200
    • removedInput schema / properties / target_market / maxLength
      Removed value: -200
  5. Changed1 schema field changed
    • addedOutput schema / properties / chargeRequired
      Added value: +{
      +  "description": "False when no payment is due - the idea is already covered (a plan slot or a prior purchase), so do NOT open a checkout. Present on the alreadyRunning path.",
      +  "type": "boolean"
      +}
  6. Changed2 schema fields changed
    • addedOutput schema / properties / alreadyRunning
      Added value: +{
      +  "description": "True if the paid report already exists (running or completed) for this idea - e.g. an existing pack slot was already used. Do NOT start a new checkout or re-run the free step; poll get_demand_report_status (if pollWith is set) or open checkoutUrl.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / status / description
      Previous value: -"'pending_payment' on success; 'blocked'/'failed' if the reportId didn't resolve; 'unconfigured_fallback'/'error_fallback' when the inline path was unavailable."New value: +"'pending_payment' on success; 'already_running'/'processing' if a paid report already exists for this idea; 'blocked'/'failed' if the reportId didn't resolve; 'unconfigured_fallback'/'error_fallback' when the inline path was unavailable."
  7. Changed3 schema fields changed
    • changedInput schema / properties / reportId / description
      Previous value: -"REQUIRED. The reportId returned by the free Market Research step (start_demand_report). The paid report builds on this record; DD will not fabricate a brand-new idea at the paid step. If you don't have one, run start_demand_report first."New value: +"Optional but strongly preferred: the EXACT reportId returned by the free Market Research step (start_demand_report). It ties the paid order to that record. OMIT it if you don't have one - DD resolves the idea from name/problem/solution. NEVER invent, guess, or placeholder a reportId; a fabricated id is rejected."
    • removedInput schema / properties / reportId / minLength
      Removed value: -1
    • changedInput schema / required
      Previous value: -[
      -  "reportId",
      -  "email",
      -  "name",
      -  "problem",
      -  "solution"
      -]New value: +[
      +  "email",
      +  "name",
      +  "problem",
      +  "solution"
      +]
  8. Added

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already flag openWorldHint=true and readOnlyHint=false, and the description goes well beyond them: it enumerates the three possible outcomes (alreadyRunning path, no-charge slot path, hosted $49 order link), states that no money moves here and that the user initiates any purchase in their own browser, and describes the idempotent behavior when a paid report already exists. Minor cost: the 'never transacts' point is repeated in two paragraphs.

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 safety disclaimer are front-loaded, but the text is long with noticeable redundancy: the 'NEVER invent, guess, or placeholder a reportId' rule appears twice (once in prose, once effectively via schema), and the 'never transacts on the user's behalf' claim is restated. Tightening would improve scanability without losing information.

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?

For a 7-parameter, order-creating tool with an output schema, the description covers the preconditions, the outcome branches, the money-safety guarantee, and the follow-up call. Since an output schema exists, omitting detailed return-field documentation is acceptable, and the enumerated outcome paths are a helpful supplement rather than a gap-filler.

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: reportId must be the EXACT id from the free step, must be omitted (not faked) if absent, and a fabricated id is rejected; name/problem/solution must reuse the same wording as the free report so the order ties back. That is semantic guidance the schema alone does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a concrete action (look up account status for this idea's full Demand Discovery Report and return the user's next step) and names the two siblings it hands off to (start_demand_report, get_demand_report_status). It is slightly muddled because the tool both 'checks status' and can produce an order link / start a slot path, so the core verb is not as crisp as the name 'validate_real_demand' implies.

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?

Explicit trigger phrases are given ('run the $49 report', 'I want the Demand Score', 'do the deep report'), plus a clear when-not: if alreadyRunning=true, do NOT re-run the free step or surface a new payment link, and instead poll get_demand_report_status or open the returned link. The prerequisite (a prior free Market Research report) and what to pass from it are spelled out.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources