Questions are a tool for preserving judgment. They should be specific, answerable, and useful to the future agent session that receives the answer.
Ask when judgment is needed
Use ask_question when:
- The instructions are ambiguous
- The next step changes human priorities
- The agent has multiple reasonable options
- The action is blocked without a decision
- Proceeding would create risk or unwanted side effects
Do not ask when the order already authorizes the decision. Execute instead.
Required shape
A strong question includes:
| Part | Why it matters |
|---|
question | The human-facing decision. Markdown is allowed. |
choices | Optional bounded answers when the decision can be framed clearly. |
on_answer | Instructions for what the future agent should do with the answer. |
| Scope | action_id, project_id, or order_id when the question belongs to existing work. |
| Links | External context needed to answer. |
Always include on_answer. The agent that sees the response later may not have the original chat
context.
Example
{
"action_id": "act_reconcile_march",
"question": "How should I categorize the $47.23 Target charge from March 18?",
"choices": ["Groceries", "Household", "Kids"],
"on_answer": "Apply the selected category to transaction txn_4421, then continue the March reconciliation batch from item 18."
}
Closing your own question
If the agent finds the answer before the human responds, it can call close_question with a response. That records the resolution and removes the open question from the human’s attention queue.
Human responses
When a human answers, the answer becomes part of the question record. The agent should reread the scoped action, project, or order before continuing so it does not resume from stale context. 