Clarifying questions
When a request could mean a few concrete things, the assistant stops and asks instead of guessing.
The problem
Ask “which orders are running late?” and there’s a hidden fork: late against which promise? Express orders promise two days, standard promise five. A model that quietly picks one hands you an answer that looks complete and isn’t.
That’s the worst kind of wrong. A visible error gets checked. A confident partial answer gets trusted. In the demo, the guessing version finds 2 late orders and misses the other 3.
What I concluded
Give the loop one more way to end a step. Besides calling a tool or answering, it can ask. Asking is just another tool, and its schema forces the model to name the options up front.
const ask = {
name: "ask",
description: "Ask one question when the request has a few " +
"concrete readings.",
input_schema: {
type: "object",
properties: {
question: { type: "string" },
options: { type: "array", items: { type: "string" },
minItems: 2, maxItems: 4 },
},
required: ["question", "options"],
},
run: (input, ctx) => ctx.interrupt({ kind: "ask", ...input }),
};
The server turns the call into an interrupt on the same event stream as everything else, and the run waits. The client renders a card with the real options as buttons. Your pick goes back in as the tool result, as if you’d typed it.
Stop resolves the wait with nothing, so a waiting run ends as cleanly as a running one. The demo fakes the model with a script, but the pause and the card work the same way.
Rules
- Only ask when the options are few and concrete. “Which promise?” with three buttons is a good question. “What did you mean?” is the model handing its job back to you.
- Name the options in the schema. The model can’t ask an open-ended question if the tool won’t accept one.
- The pick is a normal tool result. No special resume path, so the rest of the loop doesn’t care that a person answered.
- Stopping ends the wait. A paused run must never hang around after you’ve moved on.
What you get
One question costs a few seconds. A confident wrong answer costs trust. Asking as a tool keeps the loop simple and makes the fork visible right when it matters.
Related: Agent loop, Event stream, Plant shop demo