feat: sharpen ask_user tool guidance

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",
 	}),
 });