SurveysAI Qualitative Analysis – interview and focus group analysis

Start a paid analysis

qualitative_start_analysis

DestructiveIdempotent

Starts a paid, prepaid analysis package from text inputs; the whole quoted price is charged in credits immediately. Call it only after the user approved the quoted price from qualitative_quote_analysis (show price, model and effort first). Requires an API key with the runs:write scope. Pass quoted_price_credits, expected_model and expected_effort from that quote: if the price or the model changed, the call fails with quote_stale or model_changed and nothing is charged; show the new values to the user and ask again. Inputs are JSON text only (inputs.transcript: 1-10 items {name, text}; every other slot: one item), at most about 1 MB of text per call; larger inputs need the REST API with a multipart upload. It returns at once with a run_id; the analysis runs in the background, so follow it with qualitative_get_run. Do not call this tool again to check progress. Without an idempotency_key the key is derived from the exact input, so an identical call within 24 hours returns the same analysis (replayed: true) and is not charged again (after 24 hours it starts and charges a new one); to deliberately start a second identical analysis, pass a new idempotency_key. Without enough credits it answers payment_required with a link a human must open to top up.

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": {
      "title": "<title>",
      "preset_id": "<preset_id>",
      "analysis_brief": "<analysis_brief>",
      "quoted_price_credits": "<quoted_price_credits>",
      "expected_model": "<expected_model>",
      "expected_effort": "<expected_effort>",
      "inputs": "<inputs>"
    },
    "name": "qualitative_start_analysis"
  }
}

Input Schema

Name	Required	Description	Default
`title`	Yes	Short title of the analysis, shown in the web app.
`inputs`	Yes	Input texts by slot: transcript 1-10 items {name, text}, every other slot one item. At most about 1 MB of text in total; larger inputs need the REST API.
`language`	No	Analysis output language, a BCP 47 code such as en, cs or de.	en
`preset_id`	Yes	A preset id from qualitative_list_presets.
`analysis_brief`	Yes	The research objective (required, up to 5000 characters) and optional context.
`expected_model`	Yes	The `model` of the approved quote.
`expected_effort`	Yes	The `effort` of the approved quote (null when the quote has none).
`idempotency_key`	No	Optional key (printable ASCII, at most 255 characters). Omit it normally: the key is derived from the exact input, so an identical call within 24 hours returns the same analysis (`replayed`: true) and is not charged again. To deliberately start a second identical analysis, pass a new idempotency_key.
`report_audience`	No
`report_language`	No
`selected_reports`	No
`quoted_price_credits`	Yes	The `price_credits` of the quote the user approved (qualitative_quote_analysis). A higher server price fails with quote_stale and charges nothing.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 11, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes far beyond the annotations (destructiveHint=true, idempotentHint=true) by disclosing the billing model (full quoted price charged in credits immediately), the free-failure cases (quote_stale / model_changed charge nothing), the 24-hour idempotency derivation and replay behavior, the new-charge-after-24h rule, and the payment_required top-up link requiring a human. These are exactly the operational facts an agent needs before triggering a paid, destructive call.

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?

Purpose and the spend warning are front-loaded, and the long text is dense with error codes, idempotency rules, and size limits rather than filler. It is near the upper bound of useful length, with a few clauses (e.g. the idempotency explanation) partially duplicating the schema's own parameter description.

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 12-parameter, nested-input, paid mutation with no output schema, the description covers the return value (immediate run_id, background execution), the follow-up tool, the key failure codes, and the billing consequences. An agent has enough to call it correctly and recover from each documented failure.

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?

At 75% schema coverage the schema already documents most fields, yet the description adds real meaning: where the three quote parameters must come from, what happens if they mismatch, and the input slot limits (transcript 1-10 items, one item per other slot, ~1 MB per call, REST needed for larger). The ~1 MB total figure sits somewhat in tension with the schema's per-file 5 MB limit, though both are plausibly about different scopes.

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 paid, prepaid analysis package from text inputs') and immediately distinguishes itself from the quote step and from the follow-up polling tool. The agent can tell it apart from qualitative_quote_analysis and qualitative_get_run 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 Guidelines5/5

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

Gives an explicit precondition ('Call it only after the user approved the quoted price from qualitative_quote_analysis (show price, model and effort first)') and an explicit negative instruction ('Do not call this tool again to check progress'), pointing at qualitative_get_run instead. It also tells the agent what to do on stale quotes: show the new values and ask the user again.

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

All SurveysAI Qualitative Analysis – interview and focus group analysis tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?