From 4a131f7752f17f2f91fd6669e45a74888240d86e Mon Sep 17 00:00:00 2001
From: Erik Kotsiuba <eko24old@gmail.com>
Date: Sun, 19 Apr 2026 14:07:35 +0200
Subject: [PATCH] feat: sharpen ask_user tool guidance

---
 src/ask-tool.ts | 11 ++++++-----
 src/schema.ts   | 44 ++++++++++++++++++++++++++++++++------------
 2 files changed, 38 insertions(+), 17 deletions(-)

diff --git a/src/ask-tool.ts b/src/ask-tool.ts
index 3d2549d..6aa21ad 100644
--- a/src/ask-tool.ts
+++ b/src/ask-tool.ts
@@ -13,13 +13,14 @@ export function registerAskTool(pi: ExtensionAPI) {
 		name: "ask_user",
 		label: "Ask User",
 		description:
-			"Ask the user one or more structured questions when clarification is required. Supports single-select, multi-select, and preview questions. Use `preview` when an option needs a dedicated preview pane (for example, code, layout, or configuration previews). Return the selected answers as structured data instead of guessing.",
+			"Interactive clarification tool for cases where the next step depends on user preferences, missing requirements, or choosing between multiple valid directions. Ask a short structured interview, collect normalized answers, and continue using those answers explicitly instead of guessing. Supports single-select, multi-select, and preview questions with a dedicated preview pane.",
 		promptSnippet:
-			"Ask the user structured clarification questions and return the answers as structured data",
+			"Clarify ambiguous or preference-sensitive decisions with a short interactive interview before proceeding",
 		promptGuidelines: [
-			"Use this tool when requirements are ambiguous or when user preferences materially affect implementation.",
-			"Ask 1-3 concise questions instead of guessing.",
-			"Prefer short labels and 2-4 clear options per question.",
+			"Use this tool before making preference-sensitive decisions about scope, tone, UX, naming, architecture, docs, or implementation direction.",
+			"When multiple valid directions exist, ask 1-3 concise questions instead of committing to one path on your own.",
+			"Prefer one focused decision per question and use short labels with 2-4 clear options.",
+			'Use `type: "single"` by default, `type: "multi"` only when several answers can genuinely apply, and `type: "preview"` when options need a dedicated preview pane.',
 		],
 		parameters: AskParamsSchema,
 
diff --git a/src/schema.ts b/src/schema.ts
index 1e23ab6..860fe84 100644
--- a/src/schema.ts
+++ b/src/schema.ts
@@ -2,47 +2,67 @@ import { Type } from "@sinclair/typebox";
 
 export const AskOptionSchema = Type.Object({
 	value: Type.String({
-		description: "Machine-readable value returned for this option",
+		description:
+			"Machine-readable value returned for this option in the result",
+	}),
+	label: Type.String({
+		description: "Short visible option label shown in the list",
 	}),
-	label: Type.String({ description: "Short option title shown in the list" }),
 	description: Type.Optional(
-		Type.String({ description: "Optional subtitle/description" })
+		Type.String({
+			description: "Optional one-line explanation to help the user choose",
+		})
 	),
 	preview: Type.Optional(
 		Type.String({
 			description:
-				"Optional preview text shown in the dedicated preview pane for preview questions",
+				"Optional preview content shown in the dedicated preview pane for preview questions",
 		})
 	),
 });
 
 export const AskQuestionSchema = Type.Object({
-	id: Type.String({ description: "Unique question identifier" }),
+	id: Type.String({
+		description:
+			"Stable question identifier used as the key in returned answers",
+	}),
 	label: Type.Optional(
-		Type.String({ description: "Short tab label, e.g. Scope or Runtime" })
+		Type.String({
+			description: "Short tab label, e.g. Goal, Audience, Tone, Scope",
+		})
 	),
-	prompt: Type.String({ description: "Full question prompt" }),
+	prompt: Type.String({
+		description:
+			"Direct question shown to the user; ask about one decision at a time",
+	}),
 	type: Type.Optional(
 		Type.Union(
 			[Type.Literal("single"), Type.Literal("multi"), Type.Literal("preview")],
-			{ description: "Question type" }
+			{
+				description:
+					"Question type: use `single` by default, `multi` when several answers may apply, and `preview` when each option needs a preview pane",
+			}
 		)
 	),
 	required: Type.Optional(
 		Type.Boolean({
-			description: "Optional metadata flag; submit is never blocked",
+			description:
+				"Advisory only; marks the question as important but never blocks submission",
 		})
 	),
 	options: Type.Array(AskOptionSchema, {
-		description: "Available answer options",
+		description: "Answer options; prefer 2-4 clear choices when possible",
 	}),
 });
 
 export const AskParamsSchema = Type.Object({
 	title: Type.Optional(
-		Type.String({ description: "Optional title shown above the interview" })
+		Type.String({
+			description:
+				"Optional short title shown above the clarification flow, e.g. README direction",
+		})
 	),
 	questions: Type.Array(AskQuestionSchema, {
-		description: "Questions to ask the user",
+		description: "Questions to ask in the interactive clarification flow",
 	}),
 });