MCP tool reference
Use Connect through MCP for setup, approval, run lifecycle, and interpretation.
This reference contains 17 tools, generated from the pinned Rehoboam discovery manifest.
Source revision: baf8904bb7abac7d48460fc73ef9a3c612c685cf. Download the complete manifest.
Required and nullable are different. A required key must be present; a nullable value may be null. Nested schemas, unions, enumerations, defaults and output definitions are preserved below. Runtime authorization and cross-field validation still apply.
ask_experiment
Ask the causal chat agent a question about a completed experiment run.
Wraps the v1 chat agent (a smolagents ToolCallingAgent over the run's posterior draws + mappings) which does segment filtering, WTP, clustering, and posterior-plot interpretation. Non-streaming: returns the final answer text. Conversation history persists per user+run on disk and is shared with the web chat; pass reset_memory=True to start fresh.
| Input | Required | Meaning |
|---|---|---|
message | yes | See the typed definition below. |
reset_memory | no | See the typed definition below. |
run_id | yes | See the typed definition below. |
Complete input and output contract
{
"description": "Ask the causal chat agent a question about a completed experiment run.\n\nWraps the v1 chat agent (a smolagents ToolCallingAgent over the run's\nposterior draws + mappings) which does segment filtering, WTP, clustering,\nand posterior-plot interpretation. Non-streaming: returns the final answer\ntext. Conversation history persists per user+run on disk and is shared with\nthe web chat; pass reset_memory=True to start fresh.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"message": {
"type": "string"
},
"reset_memory": {
"default": false,
"type": "boolean"
},
"run_id": {
"type": "string"
}
},
"required": [
"run_id",
"message"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "ask_experiment",
"outputSchema": {
"properties": {
"response": {
"description": "Final answer text from the v1 chat agent (non-streaming).",
"type": "string"
},
"run_id": {
"description": "W&B run id the question was asked against.",
"type": "string"
}
},
"required": [
"run_id",
"response"
],
"type": "object"
}
}
check_causality
Check whether a research question is causal and suggest usable rewrites.
| Input | Required | Meaning |
|---|---|---|
num_suggestions | no | See the typed definition below. |
why_prompt | yes | Research question or decision the experiment should answer. |
Complete input and output contract
{
"description": "Check whether a research question is causal and suggest usable rewrites.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"num_suggestions": {
"default": 3,
"maximum": 5,
"minimum": 1,
"type": "integer"
},
"why_prompt": {
"description": "Research question or decision the experiment should answer.",
"maxLength": 4000,
"minLength": 1,
"type": "string"
}
},
"required": [
"why_prompt"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "check_causality",
"outputSchema": {
"example": {
"is_causal": false,
"suggestions": [
"What factors contribute to the evolutionary advantage of having two eyes?",
"What are the key features or benefits of binocular vision in humans?",
"How do different aspects of having two eyes impact human perception and survival?"
]
},
"properties": {
"is_causal": {
"default": false,
"type": "boolean"
},
"suggestions": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"suggestions"
],
"type": "object"
}
}
create_experiment_draft
Persist a partial or complete design; never invent or launch missing fields.
| Input | Required | Meaning |
|---|---|---|
draft | yes | A partial or complete experiment design supplied by the host agent. |
Complete input and output contract
{
"description": "Persist a partial or complete design; never invent or launch missing fields.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"draft": {
"additionalProperties": false,
"description": "A partial or complete experiment design supplied by the host agent.",
"properties": {
"advanced": {
"additionalProperties": false,
"description": "Partial reviewed settings for a draft; absent values are not invented.",
"properties": {
"add_neither_option": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"attribute_count": {
"anyOf": [
{
"maximum": 10,
"minimum": 2,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"confidence_level": {
"anyOf": [
{
"enum": [
"Low",
"Reasonable",
"High"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"do_research": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"expr_llm_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"level_count": {
"anyOf": [
{
"maximum": 10,
"minimum": 2,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"null_levels": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"optimization_context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"pre_cooked_attributes_and_levels_lookup": {
"anyOf": [
{
"items": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
]
},
"type": "array"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"respondent_dependent_variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"respondent_instructions_preamble": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"response_type": {
"anyOf": [
{
"enum": [
"discrete",
"probabilistic"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"target_behavior": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"year": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
"contradictions": {
"description": "Unresolved execution-relevant conflicts that block readiness.",
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"decision": {
"anyOf": [
{
"maxLength": 4000,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Business action this experiment is intended to inform."
},
"exclusions": {
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"experiment_type": {
"const": "conjoint",
"default": "conjoint",
"description": "V1.1 persisted drafts support conjoint experiments only.",
"type": "string"
},
"is_private": {
"default": true,
"type": "boolean"
},
"population": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"external_personas": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "External persona identifiers or URLs. Mutually exclusive with population_group."
},
"non_us_target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact non-US filters accepted by the population count validator.",
"example": {
"Age": [
18,
92
],
"Education_Level": [
"Masters",
"Bachelors",
"Some College",
"PhD",
"High School but no diploma",
"High School Diploma",
"Associates",
"Less than high school"
],
"Gender": [
"Female",
"Male"
],
"Home_Ownership": [
"Own",
"Rent"
],
"Household_Size": [
"4",
"2",
"1",
"3",
"More than 4 people"
],
"Household_with_Children": [
"Yes",
"No"
]
},
"properties": {
"Age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Education_Level": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Gender": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Home_Ownership": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_Size": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_with_Children": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed non-US demographic filters used for validation and execution."
},
"population_group": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Named population group to use. Mutually exclusive with external_personas.",
"examples": [
"Urban Singles"
]
},
"population_traits": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Modeled traits keyed by trait name, for example {'Travel frequency': ['Weekly']}. These enrich selected respondents; they do not select a population. Pair them with a supported population selection."
},
"target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact US filters accepted by both draft validation and execution.",
"properties": {
"age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"education_level": {
"anyOf": [
{
"items": {
"enum": [
"Some College",
"High School Diploma",
"Less than high school",
"High School but no diploma",
"Bachelors",
"Associates",
"Masters",
"PhD"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"gender": {
"anyOf": [
{
"items": {
"enum": [
"Male",
"Female"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"household_income": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"number_of_children": {
"anyOf": [
{
"items": {
"enum": [
"0",
"1",
"2",
"3",
"4+"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"racial_group": {
"anyOf": [
{
"items": {
"enum": [
"Mixed race",
"White",
"African American",
"Asian or Pacific Islander",
"Other race",
"American Indian or Alaska Native"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"state": {
"anyOf": [
{
"enum": [
"Alabama",
"Alaska",
"Arizona",
"Arkansas",
"California",
"Colorado",
"Connecticut",
"Delaware",
"Florida",
"Georgia",
"Hawaii",
"Idaho",
"Illinois",
"Indiana",
"Iowa",
"Kansas",
"Kentucky",
"Louisiana",
"Maine",
"Maryland",
"Massachusetts",
"Michigan",
"Minnesota",
"Mississippi",
"Missouri",
"Montana",
"Nebraska",
"Nevada",
"New Hampshire",
"New Jersey",
"New Mexico",
"New York",
"North Carolina",
"North Dakota",
"Ohio",
"Oklahoma",
"Oregon",
"Pennsylvania",
"Rhode Island",
"South Carolina",
"South Dakota",
"Tennessee",
"Texas",
"Utah",
"Vermont",
"Virginia",
"Washington",
"West Virginia",
"Wisconsin",
"Wyoming"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed US demographic filters used for validation and execution."
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null
},
"priority": {
"default": "high",
"enum": [
"default",
"high"
],
"type": "string"
},
"provenance": {
"items": {
"additionalProperties": false,
"properties": {
"field_path": {
"description": "Dot path of the draft value this provenance record supports.",
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"kind": {
"enum": [
"source",
"user_assertion",
"assumption",
"unresolved_question"
],
"type": "string"
},
"note": {
"maxLength": 4000,
"minLength": 1,
"type": "string"
},
"source_digest": {
"anyOf": [
{
"maxLength": 128,
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"source_uri": {
"anyOf": [
{
"maxLength": 2000,
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"field_path",
"kind",
"note"
],
"type": "object"
},
"maxItems": 200,
"type": "array"
},
"unresolved_questions": {
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"why_prompt": {
"anyOf": [
{
"maxLength": 4000,
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
}
},
"required": [
"draft"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "create_experiment_draft",
"outputSchema": {
"properties": {
"blocking_gaps": {
"items": {
"type": "string"
},
"type": "array"
},
"changes": {
"items": {
"properties": {
"after": {
"default": null,
"title": "After"
},
"before": {
"default": null,
"title": "Before"
},
"field_path": {
"type": "string"
}
},
"required": [
"field_path"
],
"type": "object"
},
"type": "array"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"draft": {
"additionalProperties": false,
"description": "A partial or complete experiment design supplied by the host agent.",
"properties": {
"advanced": {
"additionalProperties": false,
"description": "Partial reviewed settings for a draft; absent values are not invented.",
"properties": {
"add_neither_option": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"attribute_count": {
"anyOf": [
{
"maximum": 10,
"minimum": 2,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"confidence_level": {
"anyOf": [
{
"enum": [
"Low",
"Reasonable",
"High"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"do_research": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"expr_llm_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"level_count": {
"anyOf": [
{
"maximum": 10,
"minimum": 2,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"null_levels": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"optimization_context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"pre_cooked_attributes_and_levels_lookup": {
"anyOf": [
{
"items": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
]
},
"type": "array"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"respondent_dependent_variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"respondent_instructions_preamble": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"response_type": {
"anyOf": [
{
"enum": [
"discrete",
"probabilistic"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"target_behavior": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"year": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
"contradictions": {
"description": "Unresolved execution-relevant conflicts that block readiness.",
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"decision": {
"anyOf": [
{
"maxLength": 4000,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Business action this experiment is intended to inform."
},
"exclusions": {
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"experiment_type": {
"const": "conjoint",
"default": "conjoint",
"description": "V1.1 persisted drafts support conjoint experiments only.",
"type": "string"
},
"is_private": {
"default": true,
"type": "boolean"
},
"population": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"external_personas": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "External persona identifiers or URLs. Mutually exclusive with population_group."
},
"non_us_target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact non-US filters accepted by the population count validator.",
"example": {
"Age": [
18,
92
],
"Education_Level": [
"Masters",
"Bachelors",
"Some College",
"PhD",
"High School but no diploma",
"High School Diploma",
"Associates",
"Less than high school"
],
"Gender": [
"Female",
"Male"
],
"Home_Ownership": [
"Own",
"Rent"
],
"Household_Size": [
"4",
"2",
"1",
"3",
"More than 4 people"
],
"Household_with_Children": [
"Yes",
"No"
]
},
"properties": {
"Age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Education_Level": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Gender": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Home_Ownership": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_Size": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_with_Children": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed non-US demographic filters used for validation and execution."
},
"population_group": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Named population group to use. Mutually exclusive with external_personas.",
"examples": [
"Urban Singles"
]
},
"population_traits": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Modeled traits keyed by trait name, for example {'Travel frequency': ['Weekly']}. These enrich selected respondents; they do not select a population. Pair them with a supported population selection."
},
"target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact US filters accepted by both draft validation and execution.",
"properties": {
"age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"education_level": {
"anyOf": [
{
"items": {
"enum": [
"Some College",
"High School Diploma",
"Less than high school",
"High School but no diploma",
"Bachelors",
"Associates",
"Masters",
"PhD"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"gender": {
"anyOf": [
{
"items": {
"enum": [
"Male",
"Female"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"household_income": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"number_of_children": {
"anyOf": [
{
"items": {
"enum": [
"0",
"1",
"2",
"3",
"4+"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"racial_group": {
"anyOf": [
{
"items": {
"enum": [
"Mixed race",
"White",
"African American",
"Asian or Pacific Islander",
"Other race",
"American Indian or Alaska Native"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"state": {
"anyOf": [
{
"enum": [
"Alabama",
"Alaska",
"Arizona",
"Arkansas",
"California",
"Colorado",
"Connecticut",
"Delaware",
"Florida",
"Georgia",
"Hawaii",
"Idaho",
"Illinois",
"Indiana",
"Iowa",
"Kansas",
"Kentucky",
"Louisiana",
"Maine",
"Maryland",
"Massachusetts",
"Michigan",
"Minnesota",
"Mississippi",
"Missouri",
"Montana",
"Nebraska",
"Nevada",
"New Hampshire",
"New Jersey",
"New Mexico",
"New York",
"North Carolina",
"North Dakota",
"Ohio",
"Oklahoma",
"Oregon",
"Pennsylvania",
"Rhode Island",
"South Carolina",
"South Dakota",
"Tennessee",
"Texas",
"Utah",
"Vermont",
"Virginia",
"Washington",
"West Virginia",
"Wisconsin",
"Wyoming"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed US demographic filters used for validation and execution."
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null
},
"priority": {
"default": "high",
"enum": [
"default",
"high"
],
"type": "string"
},
"provenance": {
"items": {
"additionalProperties": false,
"properties": {
"field_path": {
"description": "Dot path of the draft value this provenance record supports.",
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"kind": {
"enum": [
"source",
"user_assertion",
"assumption",
"unresolved_question"
],
"type": "string"
},
"note": {
"maxLength": 4000,
"minLength": 1,
"type": "string"
},
"source_digest": {
"anyOf": [
{
"maxLength": 128,
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"source_uri": {
"anyOf": [
{
"maxLength": 2000,
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"field_path",
"kind",
"note"
],
"type": "object"
},
"maxItems": 200,
"type": "array"
},
"unresolved_questions": {
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"why_prompt": {
"anyOf": [
{
"maxLength": 4000,
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
"draft_id": {
"description": "Opaque server-minted draft handle.",
"type": "string"
},
"launch_request": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"advanced": {
"additionalProperties": false,
"description": "Reviewed experiment-design fields. Unknown internal controls are rejected.",
"properties": {
"add_neither_option": {
"default": true,
"type": "boolean"
},
"attribute_count": {
"default": 5,
"maximum": 10,
"minimum": 2,
"type": "integer"
},
"concept_description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"concept_heading": {
"default": "",
"type": "string"
},
"concept_statements": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"confidence_level": {
"default": "Low",
"enum": [
"Low",
"Reasonable",
"High"
],
"type": "string"
},
"context": {
"default": "",
"type": "string"
},
"country": {
"default": "United States",
"type": "string"
},
"design_seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Seed for the choice-task design. None (default) generates a fresh design every run; set it to repeat the design."
},
"deterministic_stages": {
"default": false,
"description": "True runs the pre-survey LLM stages (latent variables, persona bios, mood statements, decision strategy) at llm_temperature instead of a fixed 0.7.",
"type": "boolean"
},
"do_research": {
"default": false,
"type": "boolean"
},
"expr_llm_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"image_name1": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"image_name2": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"latent_variables_from_run": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Name of a previous run whose latent-variable bundle (artifact experiment_latent_variables_<name>) this run reuses, so respondent prompts repeat. Requires the same population."
},
"level_count": {
"default": 4,
"maximum": 10,
"minimum": 2,
"type": "integer"
},
"llm_temperature": {
"default": 0,
"description": "Sampling temperature for the survey step. 0.0 is the default and the only comparable setting.",
"maximum": 2,
"minimum": 0,
"type": "number"
},
"null_levels": {
"default": true,
"description": "When true, every attribute gains an injected `Not available` level. Send false explicitly when the design must contain only the submitted levels.",
"type": "boolean"
},
"optimization_context": {
"default": "",
"type": "string"
},
"population_seed": {
"default": 100,
"description": "Seed for drawing the synthetic population. The same request and seed draw the same respondents.",
"type": "integer"
},
"pre_cooked_attributes_and_levels_lookup": {
"description": "Closed-world design: `[[attribute, [level, ...]], ...]`. Submitted levels are used exactly as sent and are never reclassified as continuous; only `Not available` can be added, via `null_levels`.",
"items": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
]
},
"type": "array"
},
"type": "array"
},
"resample_population": {
"default": false,
"description": "True draws a fresh population on every run instead of honouring population_seed.",
"type": "boolean"
},
"respondent_dependent_variable": {
"default": "",
"description": "Exact choice instruction shown to respondents. A nonempty supplied value is measured content and must not be rewritten.",
"type": "string"
},
"respondent_instructions_preamble": {
"default": "",
"type": "string"
},
"response_type": {
"default": "discrete",
"enum": [
"discrete",
"probabilistic"
],
"type": "string"
},
"state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"target_behavior": {
"default": "",
"type": "string"
},
"year": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
"experiment_type": {
"default": "conjoint",
"description": "Experiment methodology to run. Conjoint is the default first-release MCP path.",
"enum": [
"conjoint",
"concept_testing"
],
"type": "string"
},
"is_private": {
"default": true,
"description": "Whether the resulting W&B run should be hidden from other users.",
"type": "boolean"
},
"population": {
"additionalProperties": false,
"description": "Required explicit audience selection. Empty populations are rejected.",
"properties": {
"external_personas": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "External persona identifiers or URLs. Mutually exclusive with population_group."
},
"non_us_target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact non-US filters accepted by the population count validator.",
"example": {
"Age": [
18,
92
],
"Education_Level": [
"Masters",
"Bachelors",
"Some College",
"PhD",
"High School but no diploma",
"High School Diploma",
"Associates",
"Less than high school"
],
"Gender": [
"Female",
"Male"
],
"Home_Ownership": [
"Own",
"Rent"
],
"Household_Size": [
"4",
"2",
"1",
"3",
"More than 4 people"
],
"Household_with_Children": [
"Yes",
"No"
]
},
"properties": {
"Age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Education_Level": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Gender": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Home_Ownership": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_Size": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_with_Children": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed non-US demographic filters used for validation and execution."
},
"population_group": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Named population group to use. Mutually exclusive with external_personas.",
"examples": [
"Urban Singles"
]
},
"population_traits": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Modeled traits keyed by trait name, for example {'Travel frequency': ['Weekly']}. These enrich selected respondents; they do not select a population. Pair them with a supported population selection."
},
"target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact US filters accepted by both draft validation and execution.",
"properties": {
"age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"education_level": {
"anyOf": [
{
"items": {
"enum": [
"Some College",
"High School Diploma",
"Less than high school",
"High School but no diploma",
"Bachelors",
"Associates",
"Masters",
"PhD"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"gender": {
"anyOf": [
{
"items": {
"enum": [
"Male",
"Female"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"household_income": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"number_of_children": {
"anyOf": [
{
"items": {
"enum": [
"0",
"1",
"2",
"3",
"4+"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"racial_group": {
"anyOf": [
{
"items": {
"enum": [
"Mixed race",
"White",
"African American",
"Asian or Pacific Islander",
"Other race",
"American Indian or Alaska Native"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"state": {
"anyOf": [
{
"enum": [
"Alabama",
"Alaska",
"Arizona",
"Arkansas",
"California",
"Colorado",
"Connecticut",
"Delaware",
"Florida",
"Georgia",
"Hawaii",
"Idaho",
"Illinois",
"Indiana",
"Iowa",
"Kansas",
"Kentucky",
"Louisiana",
"Maine",
"Maryland",
"Massachusetts",
"Michigan",
"Minnesota",
"Mississippi",
"Missouri",
"Montana",
"Nebraska",
"Nevada",
"New Hampshire",
"New Jersey",
"New Mexico",
"New York",
"North Carolina",
"North Dakota",
"Ohio",
"Oklahoma",
"Oregon",
"Pennsylvania",
"Rhode Island",
"South Carolina",
"South Dakota",
"Tennessee",
"Texas",
"Utah",
"Vermont",
"Virginia",
"Washington",
"West Virginia",
"Wisconsin",
"Wyoming"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed US demographic filters used for validation and execution."
}
},
"type": "object"
},
"priority": {
"default": "high",
"description": "Which worker tier runs this study. `high` routes to the `high_priority` queue and `default` to the `default` queue; each has its own dedicated worker, so `high` never queues behind `default` and `default` is never starved. Omit for `high`.",
"enum": [
"default",
"high"
],
"type": "string"
},
"why_prompt": {
"description": "Research question or decision the experiment should answer.",
"examples": [
"What factors drive consumer choice of electric vehicles?"
],
"minLength": 1,
"type": "string"
}
},
"required": [
"why_prompt",
"population"
],
"type": "object"
},
{
"type": "null"
}
],
"default": null
},
"population_validation": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"minimum_required": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"population_size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"status": {
"enum": [
"not_applicable",
"accepted",
"verified",
"insufficient",
"error"
],
"type": "string"
},
"suggestion": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"status"
],
"type": "object"
},
{
"type": "null"
}
],
"default": null
},
"revision": {
"minimum": 1,
"type": "integer"
},
"specification_hash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"status": {
"enum": [
"needs_input",
"invalid",
"ready"
],
"type": "string"
},
"warnings": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"draft_id",
"revision",
"status",
"draft",
"created_at"
],
"type": "object"
}
}
generate_attributes_levels
Generate bounded conjoint attributes and levels for a causal question.
| Input | Required | Meaning |
|---|---|---|
attribute_count | no | See the typed definition below. |
country | no | See the typed definition below. |
level_count | no | See the typed definition below. |
why_prompt | yes | Research question or decision the experiment should answer. |
year | no | See the typed definition below. |
Complete input and output contract
{
"description": "Generate bounded conjoint attributes and levels for a causal question.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"attribute_count": {
"default": 5,
"maximum": 10,
"minimum": 2,
"type": "integer"
},
"country": {
"default": "United States",
"maxLength": 100,
"minLength": 1,
"type": "string"
},
"level_count": {
"default": 4,
"maximum": 5,
"minimum": 2,
"type": "integer"
},
"why_prompt": {
"description": "Research question or decision the experiment should answer.",
"maxLength": 4000,
"minLength": 1,
"type": "string"
},
"year": {
"anyOf": [
{
"maximum": 2100,
"minimum": 1900,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"why_prompt"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "generate_attributes_levels",
"outputSchema": {
"properties": {
"attributes_levels": {
"description": "Generated conjoint attributes and their candidate levels.",
"items": {
"example": {
"attribute": "Battery Range per Charge",
"attribute_type": "non-monetary",
"level_type": "quantitative",
"levels": [
"Less than 150 miles",
"150 to 250 miles",
"250 to 350 miles",
"350 to 450 miles",
"More than 450 miles"
]
},
"properties": {
"attribute": {
"description": "Name of the attribute",
"type": "string"
},
"attribute_type": {
"default": "non-monetary",
"description": "Type of the attribute either monetary or non-monetary",
"type": "string"
},
"level_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Type of level, e.g. quantitative, qualitative"
},
"levels": {
"description": "List of levels for the attribute",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"attribute",
"levels",
"level_type"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"attributes_levels"
],
"type": "object"
}
}
generate_dependent_variable
Generate a respondent choice instruction for review without saving it.
| Input | Required | Meaning |
|---|---|---|
response_type | no | See the typed definition below. |
why_prompt | yes | Research question or decision the experiment should answer. |
Complete input and output contract
{
"description": "Generate a respondent choice instruction for review without saving it.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"response_type": {
"default": "discrete",
"enum": [
"discrete",
"probabilistic"
],
"type": "string"
},
"why_prompt": {
"description": "Research question or decision the experiment should answer.",
"maxLength": 4000,
"minLength": 1,
"type": "string"
}
},
"required": [
"why_prompt"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "generate_dependent_variable",
"outputSchema": {
"properties": {
"dependent_variable": {
"description": "Generated respondent choice instruction for review; never auto-saved.",
"minLength": 1,
"type": "string"
}
},
"required": [
"dependent_variable"
],
"type": "object"
}
}
get_analytics_metadata
Discover exact attribute levels and segment_labels before numeric analysis.
Segment keys include observed demographics, latent traits and personality. Numeric traits use full-sample quantile-bin labels. Missing respondent artifacts (including aggregate-only concept tests) produce a refusal.
| Input | Required | Meaning |
|---|---|---|
run_id | yes | See the typed definition below. |
Complete input and output contract
{
"annotations": {
"destructiveHint": false,
"readOnlyHint": true
},
"description": "Discover exact attribute levels and segment_labels before numeric analysis.\n\nSegment keys include observed demographics, latent traits and personality.\nNumeric traits use full-sample quantile-bin labels. Missing respondent\nartifacts (including aggregate-only concept tests) produce a refusal.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"run_id": {
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$",
"type": "string"
}
},
"required": [
"run_id"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "get_analytics_metadata",
"outputSchema": {
"properties": {
"data": {
"additionalProperties": true,
"type": "object"
},
"operation": {
"type": "string"
},
"provenance": {
"additionalProperties": true,
"type": "object"
},
"run_id": {
"type": "string"
}
},
"required": [
"run_id",
"operation",
"data",
"provenance"
],
"type": "object"
}
}
get_clusters_or_segments
Return numeric MFA/Ward clusters; at least 100 respondents, 25 per cluster.
Overall sample only; no DNF filter. Demographic/latent/personality descriptions use get_analytics_metadata.data.segment_labels. Cluster names are neutral IDs, not LLM-generated explanations. No respondent IDs returned.
| Input | Required | Meaning |
|---|---|---|
run_id | yes | See the typed definition below. |
Complete input and output contract
{
"annotations": {
"destructiveHint": false,
"readOnlyHint": true
},
"description": "Return numeric MFA/Ward clusters; at least 100 respondents, 25 per cluster.\n\nOverall sample only; no DNF filter. Demographic/latent/personality\ndescriptions use get_analytics_metadata.data.segment_labels. Cluster names\nare neutral IDs, not LLM-generated explanations. No respondent IDs returned.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"run_id": {
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$",
"type": "string"
}
},
"required": [
"run_id"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "get_clusters_or_segments",
"outputSchema": {
"properties": {
"data": {
"additionalProperties": true,
"type": "object"
},
"operation": {
"type": "string"
},
"provenance": {
"additionalProperties": true,
"type": "object"
},
"run_id": {
"type": "string"
}
},
"required": [
"run_id",
"operation",
"data",
"provenance"
],
"type": "object"
}
}
get_experiment_details
Return results only after success and analytics artifacts are verified.
| Input | Required | Meaning |
|---|---|---|
run_id | yes | See the typed definition below. |
Complete input and output contract
{
"description": "Return results only after success and analytics artifacts are verified.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"run_id": {
"type": "string"
}
},
"required": [
"run_id"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "get_experiment_details",
"outputSchema": {
"properties": {
"amce_data": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Extracted AMCE data, when analytics are available."
},
"analytics_artifacts_verified": {
"const": true,
"description": "True only after nonempty analytics artifacts are read back.",
"type": "boolean"
},
"artifacts": {
"description": "Digest-pinned descriptors for the full primary JSON artifacts.",
"items": {
"properties": {
"byte_size": {
"description": "Size of the canonical JSON bytes returned by the resource.",
"minimum": 0,
"type": "integer"
},
"name": {
"description": "Canonical name accepted by the run artifact resource.",
"enum": [
"analytics_output",
"experiment_definition"
],
"type": "string"
},
"resource_uri": {
"description": "Authenticated MCP resource URI for the full artifact JSON.",
"type": "string"
},
"sha256": {
"description": "SHA-256 digest of the canonical JSON bytes.",
"pattern": "^[0-9a-f]{64}$",
"type": "string"
}
},
"required": [
"name",
"byte_size",
"sha256",
"resource_uri"
],
"type": "object"
},
"type": "array"
},
"experiment_definition": {
"additionalProperties": true,
"description": "Primary experiment definition artifact JSON.",
"type": "object"
},
"extracted_experiment_details": {
"additionalProperties": true,
"description": "Agent-friendly extracted experiment summary.",
"type": "object"
},
"mindset_data": {
"description": "Extracted mindset part-worth rows.",
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"run_details": {
"additionalProperties": true,
"description": "Bounded run metadata from W&B.",
"type": "object"
},
"run_id": {
"description": "W&B run id for the completed experiment.",
"type": "string"
},
"run_name": {
"description": "Human-readable W&B run name.",
"type": "string"
},
"successful": {
"const": true,
"description": "True only after the normalized run status verifies success.",
"type": "boolean"
}
},
"required": [
"run_id",
"run_name",
"successful",
"analytics_artifacts_verified",
"run_details",
"experiment_definition",
"artifacts",
"extracted_experiment_details",
"amce_data",
"mindset_data"
],
"type": "object"
}
}
get_experiment_draft
Read the latest or an explicit tenant-bound experiment draft revision.
| Input | Required | Meaning |
|---|---|---|
draft_id | yes | See the typed definition below. |
revision | no | See the typed definition below. |
Complete input and output contract
{
"description": "Read the latest or an explicit tenant-bound experiment draft revision.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"draft_id": {
"type": "string"
},
"revision": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"draft_id"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "get_experiment_draft",
"outputSchema": {
"properties": {
"blocking_gaps": {
"items": {
"type": "string"
},
"type": "array"
},
"changes": {
"items": {
"properties": {
"after": {
"default": null,
"title": "After"
},
"before": {
"default": null,
"title": "Before"
},
"field_path": {
"type": "string"
}
},
"required": [
"field_path"
],
"type": "object"
},
"type": "array"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"draft": {
"additionalProperties": false,
"description": "A partial or complete experiment design supplied by the host agent.",
"properties": {
"advanced": {
"additionalProperties": false,
"description": "Partial reviewed settings for a draft; absent values are not invented.",
"properties": {
"add_neither_option": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"attribute_count": {
"anyOf": [
{
"maximum": 10,
"minimum": 2,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"confidence_level": {
"anyOf": [
{
"enum": [
"Low",
"Reasonable",
"High"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"do_research": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"expr_llm_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"level_count": {
"anyOf": [
{
"maximum": 10,
"minimum": 2,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"null_levels": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"optimization_context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"pre_cooked_attributes_and_levels_lookup": {
"anyOf": [
{
"items": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
]
},
"type": "array"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"respondent_dependent_variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"respondent_instructions_preamble": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"response_type": {
"anyOf": [
{
"enum": [
"discrete",
"probabilistic"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"target_behavior": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"year": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
"contradictions": {
"description": "Unresolved execution-relevant conflicts that block readiness.",
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"decision": {
"anyOf": [
{
"maxLength": 4000,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Business action this experiment is intended to inform."
},
"exclusions": {
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"experiment_type": {
"const": "conjoint",
"default": "conjoint",
"description": "V1.1 persisted drafts support conjoint experiments only.",
"type": "string"
},
"is_private": {
"default": true,
"type": "boolean"
},
"population": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"external_personas": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "External persona identifiers or URLs. Mutually exclusive with population_group."
},
"non_us_target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact non-US filters accepted by the population count validator.",
"example": {
"Age": [
18,
92
],
"Education_Level": [
"Masters",
"Bachelors",
"Some College",
"PhD",
"High School but no diploma",
"High School Diploma",
"Associates",
"Less than high school"
],
"Gender": [
"Female",
"Male"
],
"Home_Ownership": [
"Own",
"Rent"
],
"Household_Size": [
"4",
"2",
"1",
"3",
"More than 4 people"
],
"Household_with_Children": [
"Yes",
"No"
]
},
"properties": {
"Age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Education_Level": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Gender": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Home_Ownership": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_Size": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_with_Children": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed non-US demographic filters used for validation and execution."
},
"population_group": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Named population group to use. Mutually exclusive with external_personas.",
"examples": [
"Urban Singles"
]
},
"population_traits": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Modeled traits keyed by trait name, for example {'Travel frequency': ['Weekly']}. These enrich selected respondents; they do not select a population. Pair them with a supported population selection."
},
"target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact US filters accepted by both draft validation and execution.",
"properties": {
"age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"education_level": {
"anyOf": [
{
"items": {
"enum": [
"Some College",
"High School Diploma",
"Less than high school",
"High School but no diploma",
"Bachelors",
"Associates",
"Masters",
"PhD"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"gender": {
"anyOf": [
{
"items": {
"enum": [
"Male",
"Female"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"household_income": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"number_of_children": {
"anyOf": [
{
"items": {
"enum": [
"0",
"1",
"2",
"3",
"4+"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"racial_group": {
"anyOf": [
{
"items": {
"enum": [
"Mixed race",
"White",
"African American",
"Asian or Pacific Islander",
"Other race",
"American Indian or Alaska Native"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"state": {
"anyOf": [
{
"enum": [
"Alabama",
"Alaska",
"Arizona",
"Arkansas",
"California",
"Colorado",
"Connecticut",
"Delaware",
"Florida",
"Georgia",
"Hawaii",
"Idaho",
"Illinois",
"Indiana",
"Iowa",
"Kansas",
"Kentucky",
"Louisiana",
"Maine",
"Maryland",
"Massachusetts",
"Michigan",
"Minnesota",
"Mississippi",
"Missouri",
"Montana",
"Nebraska",
"Nevada",
"New Hampshire",
"New Jersey",
"New Mexico",
"New York",
"North Carolina",
"North Dakota",
"Ohio",
"Oklahoma",
"Oregon",
"Pennsylvania",
"Rhode Island",
"South Carolina",
"South Dakota",
"Tennessee",
"Texas",
"Utah",
"Vermont",
"Virginia",
"Washington",
"West Virginia",
"Wisconsin",
"Wyoming"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed US demographic filters used for validation and execution."
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null
},
"priority": {
"default": "high",
"enum": [
"default",
"high"
],
"type": "string"
},
"provenance": {
"items": {
"additionalProperties": false,
"properties": {
"field_path": {
"description": "Dot path of the draft value this provenance record supports.",
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"kind": {
"enum": [
"source",
"user_assertion",
"assumption",
"unresolved_question"
],
"type": "string"
},
"note": {
"maxLength": 4000,
"minLength": 1,
"type": "string"
},
"source_digest": {
"anyOf": [
{
"maxLength": 128,
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"source_uri": {
"anyOf": [
{
"maxLength": 2000,
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"field_path",
"kind",
"note"
],
"type": "object"
},
"maxItems": 200,
"type": "array"
},
"unresolved_questions": {
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"why_prompt": {
"anyOf": [
{
"maxLength": 4000,
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
"draft_id": {
"description": "Opaque server-minted draft handle.",
"type": "string"
},
"launch_request": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"advanced": {
"additionalProperties": false,
"description": "Reviewed experiment-design fields. Unknown internal controls are rejected.",
"properties": {
"add_neither_option": {
"default": true,
"type": "boolean"
},
"attribute_count": {
"default": 5,
"maximum": 10,
"minimum": 2,
"type": "integer"
},
"concept_description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"concept_heading": {
"default": "",
"type": "string"
},
"concept_statements": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"confidence_level": {
"default": "Low",
"enum": [
"Low",
"Reasonable",
"High"
],
"type": "string"
},
"context": {
"default": "",
"type": "string"
},
"country": {
"default": "United States",
"type": "string"
},
"design_seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Seed for the choice-task design. None (default) generates a fresh design every run; set it to repeat the design."
},
"deterministic_stages": {
"default": false,
"description": "True runs the pre-survey LLM stages (latent variables, persona bios, mood statements, decision strategy) at llm_temperature instead of a fixed 0.7.",
"type": "boolean"
},
"do_research": {
"default": false,
"type": "boolean"
},
"expr_llm_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"image_name1": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"image_name2": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"latent_variables_from_run": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Name of a previous run whose latent-variable bundle (artifact experiment_latent_variables_<name>) this run reuses, so respondent prompts repeat. Requires the same population."
},
"level_count": {
"default": 4,
"maximum": 10,
"minimum": 2,
"type": "integer"
},
"llm_temperature": {
"default": 0,
"description": "Sampling temperature for the survey step. 0.0 is the default and the only comparable setting.",
"maximum": 2,
"minimum": 0,
"type": "number"
},
"null_levels": {
"default": true,
"description": "When true, every attribute gains an injected `Not available` level. Send false explicitly when the design must contain only the submitted levels.",
"type": "boolean"
},
"optimization_context": {
"default": "",
"type": "string"
},
"population_seed": {
"default": 100,
"description": "Seed for drawing the synthetic population. The same request and seed draw the same respondents.",
"type": "integer"
},
"pre_cooked_attributes_and_levels_lookup": {
"description": "Closed-world design: `[[attribute, [level, ...]], ...]`. Submitted levels are used exactly as sent and are never reclassified as continuous; only `Not available` can be added, via `null_levels`.",
"items": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
]
},
"type": "array"
},
"type": "array"
},
"resample_population": {
"default": false,
"description": "True draws a fresh population on every run instead of honouring population_seed.",
"type": "boolean"
},
"respondent_dependent_variable": {
"default": "",
"description": "Exact choice instruction shown to respondents. A nonempty supplied value is measured content and must not be rewritten.",
"type": "string"
},
"respondent_instructions_preamble": {
"default": "",
"type": "string"
},
"response_type": {
"default": "discrete",
"enum": [
"discrete",
"probabilistic"
],
"type": "string"
},
"state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"target_behavior": {
"default": "",
"type": "string"
},
"year": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
"experiment_type": {
"default": "conjoint",
"description": "Experiment methodology to run. Conjoint is the default first-release MCP path.",
"enum": [
"conjoint",
"concept_testing"
],
"type": "string"
},
"is_private": {
"default": true,
"description": "Whether the resulting W&B run should be hidden from other users.",
"type": "boolean"
},
"population": {
"additionalProperties": false,
"description": "Required explicit audience selection. Empty populations are rejected.",
"properties": {
"external_personas": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "External persona identifiers or URLs. Mutually exclusive with population_group."
},
"non_us_target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact non-US filters accepted by the population count validator.",
"example": {
"Age": [
18,
92
],
"Education_Level": [
"Masters",
"Bachelors",
"Some College",
"PhD",
"High School but no diploma",
"High School Diploma",
"Associates",
"Less than high school"
],
"Gender": [
"Female",
"Male"
],
"Home_Ownership": [
"Own",
"Rent"
],
"Household_Size": [
"4",
"2",
"1",
"3",
"More than 4 people"
],
"Household_with_Children": [
"Yes",
"No"
]
},
"properties": {
"Age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Education_Level": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Gender": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Home_Ownership": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_Size": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_with_Children": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed non-US demographic filters used for validation and execution."
},
"population_group": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Named population group to use. Mutually exclusive with external_personas.",
"examples": [
"Urban Singles"
]
},
"population_traits": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Modeled traits keyed by trait name, for example {'Travel frequency': ['Weekly']}. These enrich selected respondents; they do not select a population. Pair them with a supported population selection."
},
"target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact US filters accepted by both draft validation and execution.",
"properties": {
"age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"education_level": {
"anyOf": [
{
"items": {
"enum": [
"Some College",
"High School Diploma",
"Less than high school",
"High School but no diploma",
"Bachelors",
"Associates",
"Masters",
"PhD"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"gender": {
"anyOf": [
{
"items": {
"enum": [
"Male",
"Female"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"household_income": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"number_of_children": {
"anyOf": [
{
"items": {
"enum": [
"0",
"1",
"2",
"3",
"4+"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"racial_group": {
"anyOf": [
{
"items": {
"enum": [
"Mixed race",
"White",
"African American",
"Asian or Pacific Islander",
"Other race",
"American Indian or Alaska Native"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"state": {
"anyOf": [
{
"enum": [
"Alabama",
"Alaska",
"Arizona",
"Arkansas",
"California",
"Colorado",
"Connecticut",
"Delaware",
"Florida",
"Georgia",
"Hawaii",
"Idaho",
"Illinois",
"Indiana",
"Iowa",
"Kansas",
"Kentucky",
"Louisiana",
"Maine",
"Maryland",
"Massachusetts",
"Michigan",
"Minnesota",
"Mississippi",
"Missouri",
"Montana",
"Nebraska",
"Nevada",
"New Hampshire",
"New Jersey",
"New Mexico",
"New York",
"North Carolina",
"North Dakota",
"Ohio",
"Oklahoma",
"Oregon",
"Pennsylvania",
"Rhode Island",
"South Carolina",
"South Dakota",
"Tennessee",
"Texas",
"Utah",
"Vermont",
"Virginia",
"Washington",
"West Virginia",
"Wisconsin",
"Wyoming"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed US demographic filters used for validation and execution."
}
},
"type": "object"
},
"priority": {
"default": "high",
"description": "Which worker tier runs this study. `high` routes to the `high_priority` queue and `default` to the `default` queue; each has its own dedicated worker, so `high` never queues behind `default` and `default` is never starved. Omit for `high`.",
"enum": [
"default",
"high"
],
"type": "string"
},
"why_prompt": {
"description": "Research question or decision the experiment should answer.",
"examples": [
"What factors drive consumer choice of electric vehicles?"
],
"minLength": 1,
"type": "string"
}
},
"required": [
"why_prompt",
"population"
],
"type": "object"
},
{
"type": "null"
}
],
"default": null
},
"population_validation": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"minimum_required": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"population_size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"status": {
"enum": [
"not_applicable",
"accepted",
"verified",
"insufficient",
"error"
],
"type": "string"
},
"suggestion": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"status"
],
"type": "object"
},
{
"type": "null"
}
],
"default": null
},
"revision": {
"minimum": 1,
"type": "integer"
},
"specification_hash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"status": {
"enum": [
"needs_input",
"invalid",
"ready"
],
"type": "string"
},
"warnings": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"draft_id",
"revision",
"status",
"draft",
"created_at"
],
"type": "object"
}
}
get_experiment_status
Read normalized run status.
Poll every 30–60 seconds. Keep polling for in-queue, running, and
unknown; never resubmit solely because one of those states is returned.
| Input | Required | Meaning |
|---|---|---|
run_id | yes | See the typed definition below. |
Complete input and output contract
{
"description": "Read normalized run status.\n\nPoll every 30–60 seconds. Keep polling for `in-queue`, `running`, and\n`unknown`; never resubmit solely because one of those states is returned.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"run_id": {
"type": "string"
}
},
"required": [
"run_id"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "get_experiment_status",
"outputSchema": {
"properties": {
"run_id": {
"description": "W&B run id supplied by start_experiment.",
"type": "string"
},
"status": {
"anyOf": [
{
"enum": [
"in-queue",
"running",
"unknown",
"finished",
"failed",
"crashed",
"killed",
"lost"
],
"type": "string"
},
{
"type": "string"
}
],
"description": "Normalized run state, resolved from W&B, Celery's result backend and the enqueue-time run record. `unknown` means no store has a record yet and is never terminal; `lost` requires a run record stuck non-terminal past the grace window."
},
"successful": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "True for successful terminal states, false for failed/lost terminal states, and null while still active."
},
"terminal": {
"description": "True when polling can stop for this status.",
"type": "boolean"
}
},
"required": [
"run_id",
"status",
"terminal",
"successful"
],
"type": "object"
}
}
get_factors_affecting_latent_trait
Return demographic associations with a trait, not causal trait drivers.
DNF segments use demographic/latent/personality keys from get_analytics_metadata.data.segment_labels. Numeric traits use Spearman; discrete traits additionally use normalized mutual information.
| Input | Required | Meaning |
|---|---|---|
latent_trait_name | yes | See the typed definition below. |
run_id | yes | See the typed definition below. |
segment_name_and_levels | no | See the typed definition below. |
Complete input and output contract
{
"annotations": {
"destructiveHint": false,
"readOnlyHint": true
},
"description": "Return demographic associations with a trait, not causal trait drivers.\n\nDNF segments use demographic/latent/personality keys from\nget_analytics_metadata.data.segment_labels. Numeric traits use Spearman;\ndiscrete traits additionally use normalized mutual information.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"latent_trait_name": {
"type": "string"
},
"run_id": {
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$",
"type": "string"
},
"segment_name_and_levels": {
"anyOf": [
{
"description": "DNF filter: OR across groups, AND across keys, OR within values. Use [{'overall': []}] for the full sample. Discover run-specific demographic, latent-trait and personality keys and exact observed/bin labels with get_analytics_metadata.data.segment_labels. Attributes are not segment keys. Numeric bins use full-sample quantile boundaries.",
"items": {
"additionalProperties": {
"items": {
"maxLength": 2048,
"minLength": 1,
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"propertyNames": {
"maxLength": 2048,
"minLength": 1
},
"type": "object"
},
"maxItems": 20,
"minItems": 1,
"type": "array"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"run_id",
"latent_trait_name"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "get_factors_affecting_latent_trait",
"outputSchema": {
"properties": {
"data": {
"additionalProperties": true,
"type": "object"
},
"operation": {
"type": "string"
},
"provenance": {
"additionalProperties": true,
"type": "object"
},
"run_id": {
"type": "string"
}
},
"required": [
"run_id",
"operation",
"data",
"provenance"
],
"type": "object"
}
}
get_feature_importance
Return attribute importance percentages, dispersion, counts and provenance.
DNF segments use demographic/latent/personality keys from get_analytics_metadata.data.segment_labels. No LLM or vision call.
| Input | Required | Meaning |
|---|---|---|
run_id | yes | See the typed definition below. |
segment_name_and_levels | no | See the typed definition below. |
Complete input and output contract
{
"annotations": {
"destructiveHint": false,
"readOnlyHint": true
},
"description": "Return attribute importance percentages, dispersion, counts and provenance.\n\nDNF segments use demographic/latent/personality keys from\nget_analytics_metadata.data.segment_labels. No LLM or vision call.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"run_id": {
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$",
"type": "string"
},
"segment_name_and_levels": {
"anyOf": [
{
"description": "DNF filter: OR across groups, AND across keys, OR within values. Use [{'overall': []}] for the full sample. Discover run-specific demographic, latent-trait and personality keys and exact observed/bin labels with get_analytics_metadata.data.segment_labels. Attributes are not segment keys. Numeric bins use full-sample quantile boundaries.",
"items": {
"additionalProperties": {
"items": {
"maxLength": 2048,
"minLength": 1,
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"propertyNames": {
"maxLength": 2048,
"minLength": 1
},
"type": "object"
},
"maxItems": 20,
"minItems": 1,
"type": "array"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"run_id"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "get_feature_importance",
"outputSchema": {
"properties": {
"data": {
"additionalProperties": true,
"type": "object"
},
"operation": {
"type": "string"
},
"provenance": {
"additionalProperties": true,
"type": "object"
},
"run_id": {
"type": "string"
}
},
"required": [
"run_id",
"operation",
"data",
"provenance"
],
"type": "object"
}
}
get_market_share
Compare complete product configurations using mean respondent softmax shares.
Specify every mapped attribute per product. Includes stored opt-out utility when present. Scenario shares are not observed market shares. DNF segments use demographic/latent/personality keys from get_analytics_metadata.
| Input | Required | Meaning |
|---|---|---|
products | yes | See the typed definition below. |
run_id | yes | See the typed definition below. |
segment_name_and_levels | no | See the typed definition below. |
Complete input and output contract
{
"annotations": {
"destructiveHint": false,
"readOnlyHint": true
},
"description": "Compare complete product configurations using mean respondent softmax shares.\n\nSpecify every mapped attribute per product. Includes stored opt-out utility\nwhen present. Scenario shares are not observed market shares. DNF segments\nuse demographic/latent/personality keys from get_analytics_metadata.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"products": {
"items": {
"additionalProperties": {
"maxLength": 2048,
"minLength": 1,
"type": "string"
},
"propertyNames": {
"maxLength": 2048,
"minLength": 1
},
"type": "object"
},
"maxItems": 50,
"minItems": 1,
"type": "array"
},
"run_id": {
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$",
"type": "string"
},
"segment_name_and_levels": {
"anyOf": [
{
"description": "DNF filter: OR across groups, AND across keys, OR within values. Use [{'overall': []}] for the full sample. Discover run-specific demographic, latent-trait and personality keys and exact observed/bin labels with get_analytics_metadata.data.segment_labels. Attributes are not segment keys. Numeric bins use full-sample quantile boundaries.",
"items": {
"additionalProperties": {
"items": {
"maxLength": 2048,
"minLength": 1,
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"propertyNames": {
"maxLength": 2048,
"minLength": 1
},
"type": "object"
},
"maxItems": 20,
"minItems": 1,
"type": "array"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"run_id",
"products"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "get_market_share",
"outputSchema": {
"properties": {
"data": {
"additionalProperties": true,
"type": "object"
},
"operation": {
"type": "string"
},
"provenance": {
"additionalProperties": true,
"type": "object"
},
"run_id": {
"type": "string"
}
},
"required": [
"run_id",
"operation",
"data",
"provenance"
],
"type": "object"
}
}
get_posterior_distribution
Summarize respondent utilities, not probability-point causal effects.
DNF segments use demographic/latent/personality keys from get_analytics_metadata.data.segment_labels. Intervals are empirical, not population confidence intervals. Requires at least 25 respondents.
| Input | Required | Meaning |
|---|---|---|
run_id | yes | See the typed definition below. |
segment_name_and_levels | no | See the typed definition below. |
Complete input and output contract
{
"annotations": {
"destructiveHint": false,
"readOnlyHint": true
},
"description": "Summarize respondent utilities, not probability-point causal effects.\n\nDNF segments use demographic/latent/personality keys from\nget_analytics_metadata.data.segment_labels. Intervals are empirical,\nnot population confidence intervals. Requires at least 25 respondents.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"run_id": {
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$",
"type": "string"
},
"segment_name_and_levels": {
"anyOf": [
{
"description": "DNF filter: OR across groups, AND across keys, OR within values. Use [{'overall': []}] for the full sample. Discover run-specific demographic, latent-trait and personality keys and exact observed/bin labels with get_analytics_metadata.data.segment_labels. Attributes are not segment keys. Numeric bins use full-sample quantile boundaries.",
"items": {
"additionalProperties": {
"items": {
"maxLength": 2048,
"minLength": 1,
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"propertyNames": {
"maxLength": 2048,
"minLength": 1
},
"type": "object"
},
"maxItems": 20,
"minItems": 1,
"type": "array"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"run_id"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "get_posterior_distribution",
"outputSchema": {
"properties": {
"data": {
"additionalProperties": true,
"type": "object"
},
"operation": {
"type": "string"
},
"provenance": {
"additionalProperties": true,
"type": "object"
},
"run_id": {
"type": "string"
}
},
"required": [
"run_id",
"operation",
"data",
"provenance"
],
"type": "object"
}
}
get_willingness_to_pay
Return legacy categorical utility ratios, NOT currency willingness to pay.
Dollar premiums are unsupported without a signed per-currency price slope. DNF segments use demographic/latent/personality keys from get_analytics_metadata.data.segment_labels. Includes denominator exclusions.
| Input | Required | Meaning |
|---|---|---|
monetary_attribute | yes | See the typed definition below. |
run_id | yes | See the typed definition below. |
segment_name_and_levels | no | See the typed definition below. |
Complete input and output contract
{
"annotations": {
"destructiveHint": false,
"readOnlyHint": true
},
"description": "Return legacy categorical utility ratios, NOT currency willingness to pay.\n\nDollar premiums are unsupported without a signed per-currency price slope.\nDNF segments use demographic/latent/personality keys from\nget_analytics_metadata.data.segment_labels. Includes denominator exclusions.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"monetary_attribute": {
"items": {
"maxLength": 2048,
"minLength": 1,
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"run_id": {
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$",
"type": "string"
},
"segment_name_and_levels": {
"anyOf": [
{
"description": "DNF filter: OR across groups, AND across keys, OR within values. Use [{'overall': []}] for the full sample. Discover run-specific demographic, latent-trait and personality keys and exact observed/bin labels with get_analytics_metadata.data.segment_labels. Attributes are not segment keys. Numeric bins use full-sample quantile boundaries.",
"items": {
"additionalProperties": {
"items": {
"maxLength": 2048,
"minLength": 1,
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"propertyNames": {
"maxLength": 2048,
"minLength": 1
},
"type": "object"
},
"maxItems": 20,
"minItems": 1,
"type": "array"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"run_id",
"monetary_attribute"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "get_willingness_to_pay",
"outputSchema": {
"properties": {
"data": {
"additionalProperties": true,
"type": "object"
},
"operation": {
"type": "string"
},
"provenance": {
"additionalProperties": true,
"type": "object"
},
"run_id": {
"type": "string"
}
},
"required": [
"run_id",
"operation",
"data",
"provenance"
],
"type": "object"
}
}
revise_experiment_draft
Apply a typed surgical patch to one expected immutable draft revision.
| Input | Required | Meaning |
|---|---|---|
draft_id | yes | See the typed definition below. |
expected_revision | yes | See the typed definition below. |
patch | yes | Typed merge patch; omitted fields are preserved and explicit null clears. |
Complete input and output contract
{
"description": "Apply a typed surgical patch to one expected immutable draft revision.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"draft_id": {
"type": "string"
},
"expected_revision": {
"type": "integer"
},
"patch": {
"additionalProperties": false,
"description": "Typed merge patch; omitted fields are preserved and explicit null clears.",
"properties": {
"advanced": {
"anyOf": [
{
"additionalProperties": false,
"description": "Partial reviewed settings for a draft; absent values are not invented.",
"properties": {
"add_neither_option": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"attribute_count": {
"anyOf": [
{
"maximum": 10,
"minimum": 2,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"confidence_level": {
"anyOf": [
{
"enum": [
"Low",
"Reasonable",
"High"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"do_research": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"expr_llm_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"level_count": {
"anyOf": [
{
"maximum": 10,
"minimum": 2,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"null_levels": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"optimization_context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"pre_cooked_attributes_and_levels_lookup": {
"anyOf": [
{
"items": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
]
},
"type": "array"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"respondent_dependent_variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"respondent_instructions_preamble": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"response_type": {
"anyOf": [
{
"enum": [
"discrete",
"probabilistic"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"target_behavior": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"year": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null
},
"contradictions": {
"anyOf": [
{
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"decision": {
"anyOf": [
{
"maxLength": 4000,
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"exclusions": {
"anyOf": [
{
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"experiment_type": {
"anyOf": [
{
"const": "conjoint",
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"is_private": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"population": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"external_personas": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "External persona identifiers or URLs. Mutually exclusive with population_group."
},
"non_us_target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact non-US filters accepted by the population count validator.",
"example": {
"Age": [
18,
92
],
"Education_Level": [
"Masters",
"Bachelors",
"Some College",
"PhD",
"High School but no diploma",
"High School Diploma",
"Associates",
"Less than high school"
],
"Gender": [
"Female",
"Male"
],
"Home_Ownership": [
"Own",
"Rent"
],
"Household_Size": [
"4",
"2",
"1",
"3",
"More than 4 people"
],
"Household_with_Children": [
"Yes",
"No"
]
},
"properties": {
"Age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Education_Level": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Gender": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Home_Ownership": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_Size": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_with_Children": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed non-US demographic filters used for validation and execution."
},
"population_group": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Named population group to use. Mutually exclusive with external_personas.",
"examples": [
"Urban Singles"
]
},
"population_traits": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Modeled traits keyed by trait name, for example {'Travel frequency': ['Weekly']}. These enrich selected respondents; they do not select a population. Pair them with a supported population selection."
},
"target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact US filters accepted by both draft validation and execution.",
"properties": {
"age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"education_level": {
"anyOf": [
{
"items": {
"enum": [
"Some College",
"High School Diploma",
"Less than high school",
"High School but no diploma",
"Bachelors",
"Associates",
"Masters",
"PhD"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"gender": {
"anyOf": [
{
"items": {
"enum": [
"Male",
"Female"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"household_income": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"number_of_children": {
"anyOf": [
{
"items": {
"enum": [
"0",
"1",
"2",
"3",
"4+"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"racial_group": {
"anyOf": [
{
"items": {
"enum": [
"Mixed race",
"White",
"African American",
"Asian or Pacific Islander",
"Other race",
"American Indian or Alaska Native"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"state": {
"anyOf": [
{
"enum": [
"Alabama",
"Alaska",
"Arizona",
"Arkansas",
"California",
"Colorado",
"Connecticut",
"Delaware",
"Florida",
"Georgia",
"Hawaii",
"Idaho",
"Illinois",
"Indiana",
"Iowa",
"Kansas",
"Kentucky",
"Louisiana",
"Maine",
"Maryland",
"Massachusetts",
"Michigan",
"Minnesota",
"Mississippi",
"Missouri",
"Montana",
"Nebraska",
"Nevada",
"New Hampshire",
"New Jersey",
"New Mexico",
"New York",
"North Carolina",
"North Dakota",
"Ohio",
"Oklahoma",
"Oregon",
"Pennsylvania",
"Rhode Island",
"South Carolina",
"South Dakota",
"Tennessee",
"Texas",
"Utah",
"Vermont",
"Virginia",
"Washington",
"West Virginia",
"Wisconsin",
"Wyoming"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed US demographic filters used for validation and execution."
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null
},
"priority": {
"anyOf": [
{
"enum": [
"default",
"high"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"provenance": {
"anyOf": [
{
"items": {
"additionalProperties": false,
"properties": {
"field_path": {
"description": "Dot path of the draft value this provenance record supports.",
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"kind": {
"enum": [
"source",
"user_assertion",
"assumption",
"unresolved_question"
],
"type": "string"
},
"note": {
"maxLength": 4000,
"minLength": 1,
"type": "string"
},
"source_digest": {
"anyOf": [
{
"maxLength": 128,
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"source_uri": {
"anyOf": [
{
"maxLength": 2000,
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"field_path",
"kind",
"note"
],
"type": "object"
},
"maxItems": 200,
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"unresolved_questions": {
"anyOf": [
{
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"why_prompt": {
"anyOf": [
{
"maxLength": 4000,
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
}
},
"required": [
"draft_id",
"expected_revision",
"patch"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "revise_experiment_draft",
"outputSchema": {
"properties": {
"blocking_gaps": {
"items": {
"type": "string"
},
"type": "array"
},
"changes": {
"items": {
"properties": {
"after": {
"default": null,
"title": "After"
},
"before": {
"default": null,
"title": "Before"
},
"field_path": {
"type": "string"
}
},
"required": [
"field_path"
],
"type": "object"
},
"type": "array"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"draft": {
"additionalProperties": false,
"description": "A partial or complete experiment design supplied by the host agent.",
"properties": {
"advanced": {
"additionalProperties": false,
"description": "Partial reviewed settings for a draft; absent values are not invented.",
"properties": {
"add_neither_option": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"attribute_count": {
"anyOf": [
{
"maximum": 10,
"minimum": 2,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"confidence_level": {
"anyOf": [
{
"enum": [
"Low",
"Reasonable",
"High"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"do_research": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"expr_llm_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"level_count": {
"anyOf": [
{
"maximum": 10,
"minimum": 2,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"null_levels": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"optimization_context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"pre_cooked_attributes_and_levels_lookup": {
"anyOf": [
{
"items": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
]
},
"type": "array"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"respondent_dependent_variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"respondent_instructions_preamble": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"response_type": {
"anyOf": [
{
"enum": [
"discrete",
"probabilistic"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"target_behavior": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"year": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
"contradictions": {
"description": "Unresolved execution-relevant conflicts that block readiness.",
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"decision": {
"anyOf": [
{
"maxLength": 4000,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Business action this experiment is intended to inform."
},
"exclusions": {
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"experiment_type": {
"const": "conjoint",
"default": "conjoint",
"description": "V1.1 persisted drafts support conjoint experiments only.",
"type": "string"
},
"is_private": {
"default": true,
"type": "boolean"
},
"population": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"external_personas": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "External persona identifiers or URLs. Mutually exclusive with population_group."
},
"non_us_target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact non-US filters accepted by the population count validator.",
"example": {
"Age": [
18,
92
],
"Education_Level": [
"Masters",
"Bachelors",
"Some College",
"PhD",
"High School but no diploma",
"High School Diploma",
"Associates",
"Less than high school"
],
"Gender": [
"Female",
"Male"
],
"Home_Ownership": [
"Own",
"Rent"
],
"Household_Size": [
"4",
"2",
"1",
"3",
"More than 4 people"
],
"Household_with_Children": [
"Yes",
"No"
]
},
"properties": {
"Age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Education_Level": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Gender": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Home_Ownership": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_Size": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_with_Children": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed non-US demographic filters used for validation and execution."
},
"population_group": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Named population group to use. Mutually exclusive with external_personas.",
"examples": [
"Urban Singles"
]
},
"population_traits": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Modeled traits keyed by trait name, for example {'Travel frequency': ['Weekly']}. These enrich selected respondents; they do not select a population. Pair them with a supported population selection."
},
"target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact US filters accepted by both draft validation and execution.",
"properties": {
"age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"education_level": {
"anyOf": [
{
"items": {
"enum": [
"Some College",
"High School Diploma",
"Less than high school",
"High School but no diploma",
"Bachelors",
"Associates",
"Masters",
"PhD"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"gender": {
"anyOf": [
{
"items": {
"enum": [
"Male",
"Female"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"household_income": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"number_of_children": {
"anyOf": [
{
"items": {
"enum": [
"0",
"1",
"2",
"3",
"4+"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"racial_group": {
"anyOf": [
{
"items": {
"enum": [
"Mixed race",
"White",
"African American",
"Asian or Pacific Islander",
"Other race",
"American Indian or Alaska Native"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"state": {
"anyOf": [
{
"enum": [
"Alabama",
"Alaska",
"Arizona",
"Arkansas",
"California",
"Colorado",
"Connecticut",
"Delaware",
"Florida",
"Georgia",
"Hawaii",
"Idaho",
"Illinois",
"Indiana",
"Iowa",
"Kansas",
"Kentucky",
"Louisiana",
"Maine",
"Maryland",
"Massachusetts",
"Michigan",
"Minnesota",
"Mississippi",
"Missouri",
"Montana",
"Nebraska",
"Nevada",
"New Hampshire",
"New Jersey",
"New Mexico",
"New York",
"North Carolina",
"North Dakota",
"Ohio",
"Oklahoma",
"Oregon",
"Pennsylvania",
"Rhode Island",
"South Carolina",
"South Dakota",
"Tennessee",
"Texas",
"Utah",
"Vermont",
"Virginia",
"Washington",
"West Virginia",
"Wisconsin",
"Wyoming"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed US demographic filters used for validation and execution."
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null
},
"priority": {
"default": "high",
"enum": [
"default",
"high"
],
"type": "string"
},
"provenance": {
"items": {
"additionalProperties": false,
"properties": {
"field_path": {
"description": "Dot path of the draft value this provenance record supports.",
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"kind": {
"enum": [
"source",
"user_assertion",
"assumption",
"unresolved_question"
],
"type": "string"
},
"note": {
"maxLength": 4000,
"minLength": 1,
"type": "string"
},
"source_digest": {
"anyOf": [
{
"maxLength": 128,
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"source_uri": {
"anyOf": [
{
"maxLength": 2000,
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"field_path",
"kind",
"note"
],
"type": "object"
},
"maxItems": 200,
"type": "array"
},
"unresolved_questions": {
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"why_prompt": {
"anyOf": [
{
"maxLength": 4000,
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
"draft_id": {
"description": "Opaque server-minted draft handle.",
"type": "string"
},
"launch_request": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"advanced": {
"additionalProperties": false,
"description": "Reviewed experiment-design fields. Unknown internal controls are rejected.",
"properties": {
"add_neither_option": {
"default": true,
"type": "boolean"
},
"attribute_count": {
"default": 5,
"maximum": 10,
"minimum": 2,
"type": "integer"
},
"concept_description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"concept_heading": {
"default": "",
"type": "string"
},
"concept_statements": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"confidence_level": {
"default": "Low",
"enum": [
"Low",
"Reasonable",
"High"
],
"type": "string"
},
"context": {
"default": "",
"type": "string"
},
"country": {
"default": "United States",
"type": "string"
},
"design_seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Seed for the choice-task design. None (default) generates a fresh design every run; set it to repeat the design."
},
"deterministic_stages": {
"default": false,
"description": "True runs the pre-survey LLM stages (latent variables, persona bios, mood statements, decision strategy) at llm_temperature instead of a fixed 0.7.",
"type": "boolean"
},
"do_research": {
"default": false,
"type": "boolean"
},
"expr_llm_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"image_name1": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"image_name2": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"latent_variables_from_run": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Name of a previous run whose latent-variable bundle (artifact experiment_latent_variables_<name>) this run reuses, so respondent prompts repeat. Requires the same population."
},
"level_count": {
"default": 4,
"maximum": 10,
"minimum": 2,
"type": "integer"
},
"llm_temperature": {
"default": 0,
"description": "Sampling temperature for the survey step. 0.0 is the default and the only comparable setting.",
"maximum": 2,
"minimum": 0,
"type": "number"
},
"null_levels": {
"default": true,
"description": "When true, every attribute gains an injected `Not available` level. Send false explicitly when the design must contain only the submitted levels.",
"type": "boolean"
},
"optimization_context": {
"default": "",
"type": "string"
},
"population_seed": {
"default": 100,
"description": "Seed for drawing the synthetic population. The same request and seed draw the same respondents.",
"type": "integer"
},
"pre_cooked_attributes_and_levels_lookup": {
"description": "Closed-world design: `[[attribute, [level, ...]], ...]`. Submitted levels are used exactly as sent and are never reclassified as continuous; only `Not available` can be added, via `null_levels`.",
"items": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
]
},
"type": "array"
},
"type": "array"
},
"resample_population": {
"default": false,
"description": "True draws a fresh population on every run instead of honouring population_seed.",
"type": "boolean"
},
"respondent_dependent_variable": {
"default": "",
"description": "Exact choice instruction shown to respondents. A nonempty supplied value is measured content and must not be rewritten.",
"type": "string"
},
"respondent_instructions_preamble": {
"default": "",
"type": "string"
},
"response_type": {
"default": "discrete",
"enum": [
"discrete",
"probabilistic"
],
"type": "string"
},
"state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"target_behavior": {
"default": "",
"type": "string"
},
"year": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
"experiment_type": {
"default": "conjoint",
"description": "Experiment methodology to run. Conjoint is the default first-release MCP path.",
"enum": [
"conjoint",
"concept_testing"
],
"type": "string"
},
"is_private": {
"default": true,
"description": "Whether the resulting W&B run should be hidden from other users.",
"type": "boolean"
},
"population": {
"additionalProperties": false,
"description": "Required explicit audience selection. Empty populations are rejected.",
"properties": {
"external_personas": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "External persona identifiers or URLs. Mutually exclusive with population_group."
},
"non_us_target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact non-US filters accepted by the population count validator.",
"example": {
"Age": [
18,
92
],
"Education_Level": [
"Masters",
"Bachelors",
"Some College",
"PhD",
"High School but no diploma",
"High School Diploma",
"Associates",
"Less than high school"
],
"Gender": [
"Female",
"Male"
],
"Home_Ownership": [
"Own",
"Rent"
],
"Household_Size": [
"4",
"2",
"1",
"3",
"More than 4 people"
],
"Household_with_Children": [
"Yes",
"No"
]
},
"properties": {
"Age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Education_Level": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Gender": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Home_Ownership": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_Size": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_with_Children": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed non-US demographic filters used for validation and execution."
},
"population_group": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Named population group to use. Mutually exclusive with external_personas.",
"examples": [
"Urban Singles"
]
},
"population_traits": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Modeled traits keyed by trait name, for example {'Travel frequency': ['Weekly']}. These enrich selected respondents; they do not select a population. Pair them with a supported population selection."
},
"target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact US filters accepted by both draft validation and execution.",
"properties": {
"age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"education_level": {
"anyOf": [
{
"items": {
"enum": [
"Some College",
"High School Diploma",
"Less than high school",
"High School but no diploma",
"Bachelors",
"Associates",
"Masters",
"PhD"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"gender": {
"anyOf": [
{
"items": {
"enum": [
"Male",
"Female"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"household_income": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"number_of_children": {
"anyOf": [
{
"items": {
"enum": [
"0",
"1",
"2",
"3",
"4+"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"racial_group": {
"anyOf": [
{
"items": {
"enum": [
"Mixed race",
"White",
"African American",
"Asian or Pacific Islander",
"Other race",
"American Indian or Alaska Native"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"state": {
"anyOf": [
{
"enum": [
"Alabama",
"Alaska",
"Arizona",
"Arkansas",
"California",
"Colorado",
"Connecticut",
"Delaware",
"Florida",
"Georgia",
"Hawaii",
"Idaho",
"Illinois",
"Indiana",
"Iowa",
"Kansas",
"Kentucky",
"Louisiana",
"Maine",
"Maryland",
"Massachusetts",
"Michigan",
"Minnesota",
"Mississippi",
"Missouri",
"Montana",
"Nebraska",
"Nevada",
"New Hampshire",
"New Jersey",
"New Mexico",
"New York",
"North Carolina",
"North Dakota",
"Ohio",
"Oklahoma",
"Oregon",
"Pennsylvania",
"Rhode Island",
"South Carolina",
"South Dakota",
"Tennessee",
"Texas",
"Utah",
"Vermont",
"Virginia",
"Washington",
"West Virginia",
"Wisconsin",
"Wyoming"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed US demographic filters used for validation and execution."
}
},
"type": "object"
},
"priority": {
"default": "high",
"description": "Which worker tier runs this study. `high` routes to the `high_priority` queue and `default` to the `default` queue; each has its own dedicated worker, so `high` never queues behind `default` and `default` is never starved. Omit for `high`.",
"enum": [
"default",
"high"
],
"type": "string"
},
"why_prompt": {
"description": "Research question or decision the experiment should answer.",
"examples": [
"What factors drive consumer choice of electric vehicles?"
],
"minLength": 1,
"type": "string"
}
},
"required": [
"why_prompt",
"population"
],
"type": "object"
},
{
"type": "null"
}
],
"default": null
},
"population_validation": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"minimum_required": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"population_size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"status": {
"enum": [
"not_applicable",
"accepted",
"verified",
"insufficient",
"error"
],
"type": "string"
},
"suggestion": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"status"
],
"type": "object"
},
{
"type": "null"
}
],
"default": null
},
"revision": {
"minimum": 1,
"type": "integer"
},
"specification_hash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"status": {
"enum": [
"needs_input",
"invalid",
"ready"
],
"type": "string"
},
"warnings": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"draft_id",
"revision",
"status",
"draft",
"created_at"
],
"type": "object"
}
}
start_experiment
Confirm and start at most one paid run for the exact specification.
A trusted MCP elicitation shows the normalized specification and its SHA-256 digest to the user. Acceptance is recorded in the durable approval store before dispatch. Reusing the same idempotency key returns the same reserved run and never submits a second paid experiment.
| Input | Required | Meaning |
|---|---|---|
idempotency_key | yes | Stable caller-generated key for this intended launch. Reuse the same key for retries; a different specification with the same key is rejected. |
request | yes | See the typed definition below. |
Complete input and output contract
{
"description": "Confirm and start at most one paid run for the exact specification.\n\nA trusted MCP elicitation shows the normalized specification and its\nSHA-256 digest to the user. Acceptance is recorded in the durable approval\nstore before dispatch. Reusing the same idempotency key returns the same\nreserved run and never submits a second paid experiment.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"idempotency_key": {
"description": "Stable caller-generated key for this intended launch. Reuse the same key for retries; a different specification with the same key is rejected.",
"maxLength": 128,
"minLength": 16,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{15,127}$",
"type": "string"
},
"request": {
"additionalProperties": false,
"properties": {
"advanced": {
"additionalProperties": false,
"description": "Reviewed experiment-design fields. Unknown internal controls are rejected.",
"properties": {
"add_neither_option": {
"default": true,
"type": "boolean"
},
"attribute_count": {
"default": 5,
"maximum": 10,
"minimum": 2,
"type": "integer"
},
"concept_description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"concept_heading": {
"default": "",
"type": "string"
},
"concept_statements": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"confidence_level": {
"default": "Low",
"enum": [
"Low",
"Reasonable",
"High"
],
"type": "string"
},
"context": {
"default": "",
"type": "string"
},
"country": {
"default": "United States",
"type": "string"
},
"design_seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Seed for the choice-task design. None (default) generates a fresh design every run; set it to repeat the design."
},
"deterministic_stages": {
"default": false,
"description": "True runs the pre-survey LLM stages (latent variables, persona bios, mood statements, decision strategy) at llm_temperature instead of a fixed 0.7.",
"type": "boolean"
},
"do_research": {
"default": false,
"type": "boolean"
},
"expr_llm_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"image_name1": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"image_name2": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"latent_variables_from_run": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Name of a previous run whose latent-variable bundle (artifact experiment_latent_variables_<name>) this run reuses, so respondent prompts repeat. Requires the same population."
},
"level_count": {
"default": 4,
"maximum": 10,
"minimum": 2,
"type": "integer"
},
"llm_temperature": {
"default": 0,
"description": "Sampling temperature for the survey step. 0.0 is the default and the only comparable setting.",
"maximum": 2,
"minimum": 0,
"type": "number"
},
"null_levels": {
"default": true,
"description": "When true, every attribute gains an injected `Not available` level. Send false explicitly when the design must contain only the submitted levels.",
"type": "boolean"
},
"optimization_context": {
"default": "",
"type": "string"
},
"population_seed": {
"default": 100,
"description": "Seed for drawing the synthetic population. The same request and seed draw the same respondents.",
"type": "integer"
},
"pre_cooked_attributes_and_levels_lookup": {
"description": "Closed-world design: `[[attribute, [level, ...]], ...]`. Submitted levels are used exactly as sent and are never reclassified as continuous; only `Not available` can be added, via `null_levels`.",
"items": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
]
},
"type": "array"
},
"type": "array"
},
"resample_population": {
"default": false,
"description": "True draws a fresh population on every run instead of honouring population_seed.",
"type": "boolean"
},
"respondent_dependent_variable": {
"default": "",
"description": "Exact choice instruction shown to respondents. A nonempty supplied value is measured content and must not be rewritten.",
"type": "string"
},
"respondent_instructions_preamble": {
"default": "",
"type": "string"
},
"response_type": {
"default": "discrete",
"enum": [
"discrete",
"probabilistic"
],
"type": "string"
},
"state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"target_behavior": {
"default": "",
"type": "string"
},
"year": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
"experiment_type": {
"default": "conjoint",
"description": "Experiment methodology to run. Conjoint is the default first-release MCP path.",
"enum": [
"conjoint",
"concept_testing"
],
"type": "string"
},
"is_private": {
"default": true,
"description": "Whether the resulting W&B run should be hidden from other users.",
"type": "boolean"
},
"population": {
"additionalProperties": false,
"description": "Required explicit audience selection. Empty populations are rejected.",
"properties": {
"external_personas": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "External persona identifiers or URLs. Mutually exclusive with population_group."
},
"non_us_target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact non-US filters accepted by the population count validator.",
"example": {
"Age": [
18,
92
],
"Education_Level": [
"Masters",
"Bachelors",
"Some College",
"PhD",
"High School but no diploma",
"High School Diploma",
"Associates",
"Less than high school"
],
"Gender": [
"Female",
"Male"
],
"Home_Ownership": [
"Own",
"Rent"
],
"Household_Size": [
"4",
"2",
"1",
"3",
"More than 4 people"
],
"Household_with_Children": [
"Yes",
"No"
]
},
"properties": {
"Age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Education_Level": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Gender": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Home_Ownership": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_Size": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"Household_with_Children": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed non-US demographic filters used for validation and execution."
},
"population_group": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Named population group to use. Mutually exclusive with external_personas.",
"examples": [
"Urban Singles"
]
},
"population_traits": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Modeled traits keyed by trait name, for example {'Travel frequency': ['Weekly']}. These enrich selected respondents; they do not select a population. Pair them with a supported population selection."
},
"target_population": {
"anyOf": [
{
"additionalProperties": false,
"description": "Exact US filters accepted by both draft validation and execution.",
"properties": {
"age": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"education_level": {
"anyOf": [
{
"items": {
"enum": [
"Some College",
"High School Diploma",
"Less than high school",
"High School but no diploma",
"Bachelors",
"Associates",
"Masters",
"PhD"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"gender": {
"anyOf": [
{
"items": {
"enum": [
"Male",
"Female"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"household_income": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"number_of_children": {
"anyOf": [
{
"items": {
"enum": [
"0",
"1",
"2",
"3",
"4+"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"racial_group": {
"anyOf": [
{
"items": {
"enum": [
"Mixed race",
"White",
"African American",
"Asian or Pacific Islander",
"Other race",
"American Indian or Alaska Native"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"state": {
"anyOf": [
{
"enum": [
"Alabama",
"Alaska",
"Arizona",
"Arkansas",
"California",
"Colorado",
"Connecticut",
"Delaware",
"Florida",
"Georgia",
"Hawaii",
"Idaho",
"Illinois",
"Indiana",
"Iowa",
"Kansas",
"Kentucky",
"Louisiana",
"Maine",
"Maryland",
"Massachusetts",
"Michigan",
"Minnesota",
"Mississippi",
"Missouri",
"Montana",
"Nebraska",
"Nevada",
"New Hampshire",
"New Jersey",
"New Mexico",
"New York",
"North Carolina",
"North Dakota",
"Ohio",
"Oklahoma",
"Oregon",
"Pennsylvania",
"Rhode Island",
"South Carolina",
"South Dakota",
"Tennessee",
"Texas",
"Utah",
"Vermont",
"Virginia",
"Washington",
"West Virginia",
"Wisconsin",
"Wyoming"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed US demographic filters used for validation and execution."
}
},
"type": "object"
},
"priority": {
"default": "high",
"description": "Which worker tier runs this study. `high` routes to the `high_priority` queue and `default` to the `default` queue; each has its own dedicated worker, so `high` never queues behind `default` and `default` is never starved. Omit for `high`.",
"enum": [
"default",
"high"
],
"type": "string"
},
"why_prompt": {
"description": "Research question or decision the experiment should answer.",
"examples": [
"What factors drive consumer choice of electric vehicles?"
],
"minLength": 1,
"type": "string"
}
},
"required": [
"why_prompt",
"population"
],
"type": "object"
}
},
"required": [
"request",
"idempotency_key"
],
"type": "object"
},
"meta": {
"fastmcp": {
"tags": []
}
},
"name": "start_experiment",
"outputSchema": {
"properties": {
"approval_expires_at": {
"description": "UTC expiry of the confirmation window recorded on the receipt.",
"format": "date-time",
"type": "string"
},
"approval_receipt": {
"description": "Opaque server-minted receipt for the trusted human confirmation.",
"type": "string"
},
"approved_at": {
"description": "UTC time when the trusted MCP elicitation was accepted.",
"format": "date-time",
"type": "string"
},
"idempotency_key": {
"description": "Caller-provided key durably bound to this subject and specification.",
"type": "string"
},
"launch_state": {
"description": "Durable idempotency state. Poll wandb_run_id for dispatching or dispatch_unknown; never resubmit with a new key solely because it is pending.",
"enum": [
"dispatching",
"submitted",
"dispatch_unknown"
],
"type": "string"
},
"queue_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The queue the study was actually enqueued on, so the caller can see where their work went rather than inferring it from the `priority` they sent. Null when the experiment ran inline (DEBUG mode)."
},
"specification_hash": {
"description": "SHA-256 digest of the exact normalized execution specification.",
"type": "string"
},
"wandb_run_id": {
"description": "W&B run id used for status polling and details lookup.",
"type": "string"
},
"wandb_run_name": {
"description": "Human-readable W&B run name generated by the backend.",
"type": "string"
}
},
"required": [
"approval_receipt",
"specification_hash",
"idempotency_key",
"approved_at",
"approval_expires_at",
"launch_state",
"wandb_run_id",
"wandb_run_name"
],
"type": "object"
}
}