From 9e1f6161365634e6942e16762f9221ddd148ed80 Mon Sep 17 00:00:00 2001
From: alt-glitch <balyan.sid@gmail.com>
Date: Mon, 15 Jun 2026 15:58:06 +0530
Subject: [PATCH] =?UTF-8?q?fix(clarify):=20docstring=20=E2=80=94=20put=20o?=
 =?UTF-8?q?ptions=20in=20choices[]=20only,=20never=20enumerate=20in=20ques?=
 =?UTF-8?q?tion=20text?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The model was enumerating options inside the question string (dead prose the UI
can't render as pickable rows). Schema description now spells out: choices[] is
REQUIRED for selectable options; question holds ONLY the question.
---
 tools/clarify_tool.py | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/tools/clarify_tool.py b/tools/clarify_tool.py
index 3560ccf6126..e831d38fb4d 100644
--- a/tools/clarify_tool.py
+++ b/tools/clarify_tool.py
@@ -131,6 +131,12 @@ CLARIFY_SCHEMA = {
         "or types their own answer via a 5th 'Other' option.\n"
         "2. **Open-ended** — omit choices entirely. The user types a free-form "
         "response.\n\n"
+        "CRITICAL: when you are offering options, put each option ONLY in the "
+        "`choices` array — NEVER enumerate the options inside the `question` "
+        "text. The UI renders `choices` as selectable rows; options written "
+        "into the question string render as dead prose the user can't pick. "
+        "Right: question='Which deployment target?', choices=['staging', "
+        "'prod']. Wrong: question='Which target? 1) staging 2) prod', choices=[].\n\n"
         "Use this tool when:\n"
         "- The task is ambiguous and you need the user to choose an approach\n"
         "- You want post-task feedback ('How did that work out?')\n"
@@ -145,16 +151,22 @@ CLARIFY_SCHEMA = {
         "properties": {
             "question": {
                 "type": "string",
-                "description": "The question to present to the user.",
+                "description": (
+                    "The question itself, and ONLY the question (e.g. 'Which "
+                    "deployment target?'). Do NOT embed the answer options here "
+                    "— pass them as separate elements in `choices`."
+                ),
             },
             "choices": {
                 "type": "array",
                 "items": {"type": "string"},
                 "maxItems": MAX_CHOICES,
                 "description": (
-                    "Up to 4 answer choices. Omit this parameter entirely to "
-                    "ask an open-ended question. When provided, the UI "
-                    "automatically appends an 'Other (type your answer)' option."
+                    "REQUIRED whenever you are presenting selectable options: "
+                    "each distinct option is its own array element (up to 4). "
+                    "The UI renders these as pickable rows and auto-appends an "
+                    "'Other (type your answer)' option. Omit this parameter "
+                    "entirely ONLY for a genuinely open-ended free-text question."
                 ),
             },
         },