Skip to main content
Glama
Sign In

CrowdOS

by ai.crowdos.api
OverviewDiscussionsAdmin

run_debate

Run a multi-round simulated debate (a Pulse debate). Respondents discuss the motion over several rounds and update their positions in response to each other. Returns the final consensus, the key arguments on each side, dissenting views and a synthesis, without individual answers. Use it to see whether a position survives scrutiny, not just a snapshot.

RECOMMENDED FLOW: if the user didn't pick an audience, call list_demographic_presets and propose one or two; call preview_cost for the price; confirm with the user; then run. Studies are charged to the account's wallet at the same per-respondent rate as on the web. A debate costs population_size × num_rounds, so preview it.

Your plan allows up to 20 respondents per study (Free 20, Pro 500, Max 1,000). The default debate is 30 respondents × 5 rounds.

WHEN IT FITS: whether a position survives argument, and which arguments move people. WHEN IT MISLEADS: read as a population estimate. Deliberation pulls a panel together; for the unprompted split, use run_focus_group.

Returns: final_consensus_score (0-1), summary, key_arguments_for, key_arguments_against, dissenting_views, num_rounds, agent_count (respondents counted in the final round), position_shifts_count, and breakdowns (final positions by age_band, gender, political_ideology, region and, where respondents carry their market's party lean, party).

Input Schema

NameRequiredDescriptionDefault
topicYesThe motion the panel debates, e.g. 'Should the federal minimum wage be $20/hr?'
contextNoBackground every respondent reads before answering: a product description, the ad copy, a news story, the terms of an offer. Plain text, up to 16,000 characters. The result's shown_to_respondents block echoes what the panel read.
languageNoLanguage the respondents answer in. Default: en.en
image_urlNoOptional public HTTPS URL of an image to attach to the debate topic. Same shape as run_focus_group.image_url.
num_roundsNoDebate rounds. Default 5 (platform standard). More rounds = more convergence pressure and cleaner consensus, but cost grows linearly.
custom_audienceNoOptional filter narrowing the panel INSIDE the market preset. Keys (all optional): countries, regions, cities (each market's own vocabulary), age_min / age_max, genders ('all' | 'men' | 'women' | 'non_binary'), interests / interest_exclusions (taxonomy tags), income_min_tier / income_max_tier (affluence ladder 0-7, 7 = top), income_currency + income_min_amount / income_max_amount (REAL annual household amounts in a named ISO currency — currency is required with amounts; e.g. {'income_currency': 'USD', 'income_min_amount': 100000}), income_match ('position' = the equivalent affluence standing within each market's own income ladder, the default; 'absolute' = actual earnings at indicative FX), ethnicities / religions (multi-ethnic markets only). Preview a custom_audience with the free estimate_reach tool before paying for a run — it reports the audience size and which constraint cuts hardest. A 'small' audience is not a blocker: the panel is still delivered at the population_size you ask for, with every respondent matching the filter, and its age and gender mix follows the market's profile within the filter's age, gender, place, income and heritage terms (interest tags pick who within each group, not how many of each). Results carry panel_check (the panel's age, gender and region mix against that profile) and, for an uncommon audience, audience_note. Guide: https://crowdos.ai/mcp.
population_sizeNoRespondents in the debate. Default 20. Your plan's limit is 20 (Free 20, Pro 500, Max 1,000).
stance_statementNoOptional declarative the agents argue FOR or AGAINST. Sharpens the split when the topic is open-ended.
demographic_presetNoAudience preset. Use list_demographic_presets to see all options. Default: us_general_population.us_general_population

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / image_url
      Added value: +{
+  "description": "Optional public HTTPS URL of an image to attach to the debate topic. Same shape as run_focus_group.image_url.",
+  "maxLength": 2048,
+  "type": "string"
+}
  2. Changed1 schema field changed
    • changedInput schema / properties / custom_audience / description
      Previous value: -"Optional filter narrowing the panel INSIDE the market preset. Keys (all optional): countries, regions, cities (each market's own vocabulary), age_min / age_max, genders ('all' | 'men' | 'women' | 'non_binary'), interests / interest_exclusions (taxonomy tags), income_min_tier / income_max_tier (affluence ladder 0-7, 7 = top), income_currency + income_min_amount / income_max_amount (REAL annual household amounts in a named ISO currency — currency is required with amounts; e.g. {'income_currency': 'USD', 'income_min_amount': 100000}), income_match ('position' = the equivalent affluence standing within each market's own income ladder, the default; 'absolute' = actual earnings at indicative FX), ethnicities / religions (multi-ethnic markets only). Preview a custom_audience with the free estimate_reach tool before paying for a run — it reports the audience size and which constraint cuts hardest. A 'small' audience is not a blocker: the panel is still delivered at the population_size you ask for, with every respondent matching the filter. Guide: https://crowdos.ai/mcp."New value: +"Optional filter narrowing the panel INSIDE the market preset. Keys (all optional): countries, regions, cities (each market's own vocabulary), age_min / age_max, genders ('all' | 'men' | 'women' | 'non_binary'), interests / interest_exclusions (taxonomy tags), income_min_tier / income_max_tier (affluence ladder 0-7, 7 = top), income_currency + income_min_amount / income_max_amount (REAL annual household amounts in a named ISO currency — currency is required with amounts; e.g. {'income_currency': 'USD', 'income_min_amount': 100000}), income_match ('position' = the equivalent affluence standing within each market's own income ladder, the default; 'absolute' = actual earnings at indicative FX), ethnicities / religions (multi-ethnic markets only). Preview a custom_audience with the free estimate_reach tool before paying for a run — it reports the audience size and which constraint cuts hardest. A 'small' audience is not a blocker: the panel is still delivered at the population_size you ask for, with every respondent matching the filter, and its age and gender mix follows the market's profile within the filter's age, gender, place, income and heritage terms (interest tags pick who within each group, not how many of each). Results carry panel_check (the panel's age, gender and region mix against that profile) and, for an uncommon audience, audience_note. Guide: https://crowdos.ai/mcp."
  3. Changed1 schema field changed
    • addedInput schema / properties / context
      Added value: +{
+  "description": "Background every respondent reads before answering: a product description, the ad copy, a news story, the terms of an offer. Plain text, up to 16,000 characters. The result's shown_to_respondents block echoes what the panel read.",
+  "maxLength": 16000,
+  "type": "string"
+}
  4. First observed

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does substantial work: it discloses the billing model (wallet charged per respondent), the cost formula population_size × num_rounds, plan caps, and that individual answers are deliberately excluded from the return. It also warns that more rounds means more convergence pressure, which is genuinely behavioral. It loses a point for an internal inconsistency: it claims "the default debate is 30 respondents × 5 rounds" while the schema caps population_size at 20 and defaults it to 20, so an agent relaying the default to a user would misstate it.

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?

Front-loaded with purpose, then clearly delimited blocks (RECOMMENDED FLOW, plan limits, WHEN IT FITS / WHEN IT MISLEADS, Returns). The Returns enumeration and the flow block both earn their place, but the cost point is made three times (wallet rate, population_size × num_rounds, "so preview it"), which is more repetition than a complex tool needs.

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 9-parameter, nested-object, no-output-schema, paid, non-annotated tool, the description covers everything an agent needs: what it costs, how to check cost first, plan caps, when to use a sibling instead, and a full enumeration of returned fields including num_rounds, position_shifts_count and the breakdown dimensions. Nothing material is missing apart from the default disagreement noted above.

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 coverage is 100% and the properties already document topic, context, language, num_rounds, custom_audience and population_size, so the baseline is 3. The description adds useful cost-per-round reasoning and a concrete pre-check (estimate_reach for custom_audience), but it also contradicts the schema on the population default (30 vs 20), which actively undermines parameter understanding rather than adding to it.

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?

Opens with a specific verb+resource ("Run a multi-round simulated debate") and immediately describes the mechanism: respondents discuss over rounds and update positions in response to each other. It explicitly distinguishes itself from the nearest sibling by naming run_focus_group as the tool for the unprompted split, so an agent can route without opening either 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?

Provides an explicit RECOMMENDED FLOW sequencing list_demographic_presets, preview_cost and user confirmation before running, plus a WHEN IT FITS / WHEN IT MISLEADS pair that names the failure mode (reading results as a population estimate) and the alternative (run_focus_group). Alternatives and exclusions are both stated.

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

All CrowdOS toolsInspect
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