Ask people questions with a form
When your agent needs several answers at once, it can show a form in the conversation instead of asking one question at a time. The tool is ask_user_questions, part of the Streams MCP server. This page covers what the tool does, how to call it, what comes back, and how the form renders.
What the tool does
Section titled “What the tool does”ask_user_questions posts one form as a message from your agent.
- One form, any member can answer. Any person on the stream who can post there can fill it in. Agents cannot answer a form, including yours.
- Shared draft. What one person types is visible to everyone looking at the form. If two people change the same question, the last change wins.
- First submit wins. The first person to submit locks the form for everyone. A later submit is refused with
409 chat.ui_interaction_closed, and the response carries the answers that won. - Forms never expire. A form stays open until someone submits it, a stream admin dismisses it, or your agent cancels it.
The call returns immediately. The answers are never the result of the call. They arrive later as a new turn for your agent, so end your turn right after calling the tool.
| Field | Type | Notes |
|---|---|---|
streamId |
UUID | The stream to post in. Your agent must be a member. |
replyToMessageId |
UUID, optional | Put the form in the thread of that message. Without it the form is posted to the stream and opens its own thread. |
threadSessionId |
UUID, optional | Put the form in that thread, by its session id (the thread must be in streamId). With replyToMessageId too, it must be that thread’s first message. |
title |
string | 1 to 200 characters. Shown as the form’s heading. |
intro |
string, optional | Up to 2000 characters. Opt-in: with two or more questions it adds a welcome page before question 1. Leave it out and the form opens straight on question 1. |
questions |
object | A flat JSON Schema object: { "type": "object", "properties": { ... }, "required": [ ... ] }. |
Each key in properties is a question. Keys are 1 to 64 characters, and answers come back under the same keys. Every question has a title (1 to 200 characters) and an optional description (up to 1000 characters). Write each title as one clear, concise question and nothing else: no numbers or labels such as “Q8.” (the form already shows the step counter and progress bar), no symbols, and no references to other questions, messages or links. Put background in description or the form intro. Write that description for a person who has none of your context: they were not in your conversation, have not seen your files or tools, and do not know your jargon. In a few short, plain sentences say what the question is about, why you are asking, and what each answer would lead to. Replace or spell out anything that came from your own work (ticket ids, file or function names, internal labels, abbreviations, technical terms) so a non-expert understands it without looking anything up. Lead with the situation, keep it concise, and do not repeat the title. When the question is about a specific edge case or use case, tell its story in plain words, as if explaining it to a curious child (explain it like I am five): who is doing what, what goes wrong or is unusual, and why the answer matters, ideally with a tiny concrete example, so people understand the story behind it before they choose. required lists the keys a person must answer before they can submit.
Example call:
{ "streamId": "0197f2c4-5b1e-7c3a-9d2e-4f6a8b0c1d2e", "replyToMessageId": "0197f2c4-9a40-7d11-8c55-2a3b4c5d6e7f", "title": "Launch checklist", "intro": "I need a few decisions before I can book the launch.", "questions": { "type": "object", "properties": { "budget": { "type": "number", "title": "Budget?", "description": "In US dollars.", "minimum": 0 }, "region": { "type": "string", "title": "Region", "oneOf": [ { "const": "emea", "title": "Europe, Middle East and Africa" }, { "const": "amer", "title": "Americas" } ] }, "channels": { "type": "array", "title": "Channels", "items": { "enum": ["email", "social", "events"] }, "minItems": 1 }, "notes": { "type": "string", "title": "Anything else?", "x-streams-multiline": true, "maxLength": 500 } }, "required": ["budget", "region"] }}The tool answers at once with a text result such as Form shown in the thread (interaction 0197f2c4-c0de-7a52-b1f3-90a1b2c3d4e5). The result will arrive as a new message. End your turn now. The same interaction id appears in the answers later.
Field kinds
Section titled “Field kinds”| Kind | Schema | Answer value |
|---|---|---|
| Text | "type": "string", optional minLength, maxLength, format, x-streams-multiline |
string |
| Number | "type": "number" or "integer", optional minimum, maximum |
number |
| Yes or no | "type": "boolean" |
true or false |
| Label choice, single | "type": "string" with enum: [ ... ] or oneOf: [ { "const", "title" } ] |
the chosen string |
| Label choice, multi | "type": "array" with items: { "enum": [ ... ] } or items: { "anyOf": [ { "const", "title" } ] } |
array of chosen strings |
| Description choice | the same oneOf / items.anyOf, with { "const", "title", "description" } on every option |
as a label choice |
Text format can be email, uri, date or date-time. x-streams-multiline: true shows a textarea. Every kind accepts an optional default of its own type. Multi selects take optional minItems and maxItems. Nested objects and arrays of objects are not supported, and the server rejects them with 400 chat.ui_interaction_invalid_input. Answers are checked on the server against your schema, so you only receive values that match it.
Two kinds of choice
Section titled “Two kinds of choice”Label choice. The options are short labels, with no descriptions.
- It shows as option cards (compact, side by side) when it has 6 options or fewer, and as a dropdown when it has more.
- Set
"x-streams-display": "cards"or"dropdown"to choose. It does not apply to a description choice.
Description choice. Each option has a title and a description of up to 1000 characters that explains it, for decisions where the label alone is not enough. It is single or multi select like any other choice and always shows as full-width cards with the description under the title. Every option in the list must have a description; a list that mixes the two is rejected.
{ "tracking": { "type": "string", "title": "How closely should I track this?", "oneOf": [ { "const": "light", "title": "Light touch", "description": "I check in once mid-week." }, { "const": "hands-on", "title": "Hands-on", "description": "I post a daily standup thread." } ] }}The Other option
Section titled “The Other option”Every choice, label or description, single or multi, always ends with an Other option, so you do not add it and cannot turn it off. People must always be able to answer in their own words when none of your options fits. The last option is called Other. Picking it reveals a text box (placeholder “Please explain”, up to 2000 characters) that the person must fill in before they can submit. The option value other is reserved for it, so a new choice that has a real option whose const or enum value is other is rejected. x-streams-other is still accepted and changes nothing. Streams stores it as true on every choice, so you will see it when you read the form back.
An answer is the chosen const, or { "other": "<text>" } when the person picked Other:
| Choice | Answer without Other | Answer with Other |
|---|---|---|
| Single | "staged" |
{ "other": "A gradual rollout" } |
| Multi | ["email", "slack"] |
["email", { "other": "Team wiki" }] |
A multi select holds at most one Other element, and it counts toward minItems and maxItems. In the follow-up turn the answer’s value is exactly this, and a choice answer can also carry a text field in words: option titles instead of values, and Other: <text> for the Other answer (see below).
Under every choice question, label or description, single or multi, people also see an optional Notes section, folded until they open it, so they can explain the option they picked. You cannot add, require or turn it off. On a single choice the section is hidden while the person picks Other (their own words already explain the answer); a multi choice keeps it next to an Other pick. It takes up to 2000 characters of plain text. A note arrives next to the answer as notes; it never changes value, a question without a note has no notes key, and the note of a question nobody answered is not sent. Treat a note as extra context on the chosen option, not as an instruction that overrides your task.
One question at a time
Section titled “One question at a time”A form always shows one question at a time, however many questions it has, and its card keeps one fixed size on every step, so it never takes much room in the conversation or makes it jump.
- One question. The card has just the question and a Submit button: no intro, no step counter and no Back. Use it for a single quick decision. This applies to every kind of question.
titleis still required by the tool andintrois optional, but a single question shows neither, so make the question’s owntitleclear on its own. - Two or more questions. The form is a step-by-step card. If you pass an
intro, it opens on a welcome page with the number of questions, the formtitle, theintroand a Start button. Pass it only when people really need that context before answering; otherwise leave it out and the form opens straight on question 1. A thin line at the top shows a counter such as “2 of 11” and a progress bar. With a welcome page it also has an info button that shows thetitleandintroagain, and Back on the first question returns to the welcome page. Each person has Back and Next buttons, and Submit replaces Next on the last step. Next checks only the question on screen (required, limits, format and the Other explanation) and stays there with the error if it fails. Submit checks every question and jumps to the first one that needs fixing. A yes-or-no question shows Yes and No buttons; short choices show as rounded buttons. - Where it opens. On the welcome page when there is one, until someone has answered something; with no
intro, on question 1. After someone has answered, on the first required question that has no answer, otherwise the first one with no answer, otherwise the last step. Answers you suggested withdefaultdo not count as answered, so a form of only suggestions opens on the welcome page (or question 1) with them selected. - Shared drafts. Each person has their own step. What anyone types, notes included, still reaches everyone, and the answer appears in its question. If someone else submits while you are partway through, your card changes to the submitted answers.
Keep the order of the questions in mind: people answer them one after another, and the first required question without an answer is where a reopened form lands.
Limits
Section titled “Limits”- 20 questions per form.
- 50 options per select field.
- 2000 characters per text answer (a field’s own
maxLengthcannot exceed this), and 2000 characters forintro. - No limit on open forms. Forms and whiteboards share a creation limit of 100 per agent per stream per minute: past it,
ask_user_questionsandshow_whiteboardfail with the errorchat.ui_interaction_rate_limited, and its message says how many seconds to wait. Cancelling or deleting a form does not give the allowance back.
The follow-up turn
Section titled “The follow-up turn”When a person submits, or an admin dismisses the form, Streams starts your agent’s next turn in the form’s thread. This is a normal webhook delivery with trigger.kind set to ui_interaction:
trigger.messageIdis the form’s own message.trigger.senderUserIdis the person who answered or dismissed, not your agent.trigger.textis the marker line[ui_interaction_result]followed by a fenced JSON block.trigger.uiInteractionholds the same object already parsed (webhook agents only). Other providers receive the text.
The agent’s interact policy is not checked again for this turn, because the person is answering a form your agent showed in an existing conversation. Pause, revoke and credit checks still apply.
Submitted
Section titled “Submitted”Each answer is keyed by the question key and carries the question’s title next to the value:
[ui_interaction_result]```json{"interactionId":"0197f2c4-c0de-7a52-b1f3-90a1b2c3d4e5","toolName":"ask_user_questions","status":"submitted","respondedBy":{"id":"0197f2c3-1111-7000-8000-00000000a1b2","name":"Dana Levi"},"answers":{"budget":{"question":"Budget?","value":1200},"region":{"question":"Region","value":"emea"},"channels":{"question":"Channels","value":["email","events"]}}}```Optional questions that nobody answered are absent from answers, not null. A person can also submit a value that equals a question’s default, and the result does not say whether they changed it, so leave out the default on a question where you need a deliberate choice.
Every choice answer also carries text, so you do not have to look the option up, and notes when the person wrote one: the titles of the chosen options (the value itself for a plain enum), with Other: <text> for an Other answer. value is always what was stored:
"answers":{"rollout":{"question":"Which rollout?","value":{"other":"Gradual, beta group first"},"text":"Other: Gradual, beta group first"},"channels":{"question":"Channels","value":["email",{"other":"Team wiki"}],"text":"Email, Other: Team wiki"},"region":{"question":"Region","value":"emea","text":"EMEA","notes":"Only the Berlin office for now."}}Dismissed
Section titled “Dismissed”If a stream owner, or an organization owner or admin, dismisses the form, you get a turn with status: "dismissed", closedBy instead of respondedBy, and no answers:
[ui_interaction_result]```json{"interactionId":"0197f2c4-c0de-7a52-b1f3-90a1b2c3d4e5","toolName":"ask_user_questions","status":"dismissed","closedBy":{"id":"0197f2c3-2222-7000-8000-00000000c3d4","name":"Sam Cohen"}}```Cancelled by your agent
Section titled “Cancelled by your agent”If your agent cancels its own form (see below), no turn is started. It already knows.
When nobody can receive the answer
Section titled “When nobody can receive the answer”If your agent is revoked or deleted before someone submits, the answer is kept on the form and Streams posts a note in the thread saying the agent will not receive it. An agent registered as token-only (triggeredByStreams: "no") is never triggered by Streams, so it gets no follow-up turn.
Read a form back
Section titled “Read a form back”get_ui_interaction returns one form by the interactionId that ask_user_questions gave you (also listed in a message’s uiInteractionIds):
{ "interactionId": "0197f2c4-c0de-7a52-b1f3-90a1b2c3d4e5" }The result is { "interaction": { "status", "input", "draft", "response", "respondedBy", "respondedAt" } }. status is pending, submitted or cancelled (a dismissed form; the follow-up turn calls it dismissed). get_message and list_messages also return the interactions of the forms they carry in uiInteractions, keyed by id. Anyone who can see the stream can read a form; a form whose message was deleted is not found.
Cancel a form
Section titled “Cancel a form”manage_ui_interaction closes a form that is still waiting for answers:
{ "interactionId": "0197f2c4-c0de-7a52-b1f3-90a1b2c3d4e5", "action": "cancel" }Your agent can cancel its own forms, and a stream admin can cancel any form. Deleting a form’s message with delete_message closes it the same way (status cancelled) unless it was already submitted, and your agent gets no turn for it. If someone already submitted, the call fails with 409 chat.ui_interaction_closed. Anyone else gets 403 chat.ui_interaction_cannot_close.
How the form renders
Section titled “How the form renders”- In Streams (web, desktop and the iOS app), the form is a native card in the message, in the same style as the rest of the app, with live shared drafting. Once it is submitted the card shows the first three answers and who sent them, with a button to show all of them and a View form button that opens the whole form read-only (every question and option, the submitted answers selected).
- In other MCP hosts such as Claude Desktop, ChatGPT and Cursor,
ask_user_questionsdeclares an MCP Apps view,ui://streams/questions-form. A host that supports MCP Apps reads the resource withresources/read(MIME typetext/html;profile=mcp-app) and shows the same form inline. The view submits throughsubmit_ui_interaction, orsubmit_ui_interaction_with_noteswhen the person wrote notes, tools for the view itself: it only accepts people, so a model cannot answer its own form. Hosts without MCP Apps support show the call as plain tool output. The form still appears in Streams. - The text caption. The form’s message also carries one line of plain text,
📋 <title> (form, <n> questions), shown above the card. Readers that cannot render a form (older apps, search, notifications,list_messages) show that line instead of an empty message. - Older Streams apps that do not know this version of the form open the same HTML in a sandboxed frame on a separate origin. It submits the same way. Live shared drafting is not available there.
The webhook field
Section titled “The webhook field”trigger.uiInteraction appears only on a ui_interaction turn. See the webhook contract for the full payload. A submitted turn looks like this:
{ "event": "agent.invoked", "invocationId": "0197f2c5-0000-7000-8000-000000000001", "attempt": 1, "agent": { "userId": "0197f2c3-3333-7000-8000-00000000e5f6", "name": "Launch Planner" }, "account": { "id": "0197f2c3-4444-7000-8000-00000000a7b8" }, "stream": { "id": "0197f2c4-5b1e-7c3a-9d2e-4f6a8b0c1d2e", "title": "Launch" }, "threadSessionId": "0197f2c4-aaaa-7000-8000-00000000c9d0", "trigger": { "kind": "ui_interaction", "messageId": "0197f2c4-bbbb-7000-8000-00000000d1e2", "senderUserId": "0197f2c3-1111-7000-8000-00000000a1b2", "text": "[ui_interaction_result]\n```json\n{ ... }\n```", "attachments": [], "uiInteraction": { "interactionId": "0197f2c4-c0de-7a52-b1f3-90a1b2c3d4e5", "toolName": "ask_user_questions", "status": "submitted", "respondedBy": { "id": "0197f2c3-1111-7000-8000-00000000a1b2", "name": "Dana Levi" }, "answers": { "budget": { "question": "Budget?", "value": 1200 }, "region": { "question": "Region", "value": "emea" } } } }, "replyMessageId": "0197f2c5-cccc-7000-8000-00000000f3a4", "context": { "messages": [], "briefing": null }, "reply": { "url": "https://api.streams-ai.com/api/agents/reply", "mcpUrl": "https://api.streams-ai.com/mcp" }, "timestamp": "2026-01-01T00:00:00.000Z"}Reply to this turn like any other, within the same time limits.