Add declarative answer slots and force JSON output in MCP mode

- Force --output:json in McpToolAdapter so agents receive structured
  JSON instead of human-formatted tables and banners
- Add WithAnswer() fluent API and [Answer] attribute to declare
  interactive prompt slots on commands (confirmation, choices, etc.)
- Expose answer slots as answer:{name} properties in MCP tool schema
  so agents know which prefills are available before first call
- Answer types reuse route constraint names (string, bool, int, etc.)

Author: carldebilly

docs/mcp-server.md

@@ -206,7 +206,7 @@ Commands that use runtime prompts (`AskChoiceAsync`, `AskConfirmationAsync`, etc
 
 | Tier | Mechanism | When |
 |---|---|---|
-| 1. Prefill | Values from tool arguments (`answer:confirm=yes`) | Always tried first |
+| 1. Prefill | Values from tool arguments (`answer.confirm=yes`) | Always tried first |
 | 2. Elicitation | Structured form request to user through agent client | `PrefillThenElicitation` mode + client supports it |
 | 3. Sampling | LLM answers on behalf of user | `PrefillThenElicitation` or `PrefillThenSampling` + client supports it |
 | 4. Default/Fail | Use default value or fail with descriptive error | Fallback |

samples/08-mcp-server/Program.cs

@@ -54,7 +54,8 @@ The email must be unique across all contacts.
 			return Results.Success($"Contact {id} deleted.");
 		})
 		.WithDescription("Delete a contact")
-		.Destructive();
+		.Destructive()
+		.WithAnswer("confirm", "bool", "Confirm deletion");
 });
 
 // ── Prompts (reusable agent instructions) ──────────────────────────

src/Repl.Core/AnswerDeclaration.cs

@@ -0,0 +1,13 @@
+namespace Repl;
+
+/// <summary>
+/// Declares an interactive answer slot that can be pre-filled via
+/// <c>--answer:{name}=value</c> on the CLI or <c>answer:{name}</c> in MCP tool calls.
+/// </summary>
+/// <param name="Name">Answer name (matches the <c>name</c> parameter in <c>AskConfirmationAsync</c>, etc.).</param>
+/// <param name="Type">Value type using route constraint names: <c>string</c>, <c>bool</c>, <c>int</c>, <c>guid</c>, <c>email</c>, etc.</param>
+/// <param name="Description">Optional description for help text and agent tool schemas.</param>
+public sealed record AnswerDeclaration(
+	string Name,
+	string Type = "string",
+	string? Description = null);

src/Repl.Core/CommandBuilder.cs

@@ -86,6 +86,13 @@ internal CommandBuilder(string route, Delegate handler)
 	/// </summary>
 	public bool IsPrompt { get; private set; }
 
+	/// <summary>
+	/// Gets declared answer slots for interactive prompts.
+	/// </summary>
+	public IReadOnlyList<AnswerDeclaration> Answers => _answers;
+
+	private readonly List<AnswerDeclaration> _answers = [];
+
 	/// <summary>
 	/// Gets generic metadata entries for extensibility.
 	/// </summary>
@@ -231,6 +238,21 @@ public CommandBuilder WithMetadata(string key, object value)
 		return this;
 	}
 
+	/// <summary>
+	/// Declares an interactive answer slot that can be pre-filled via <c>--answer:{name}=value</c>
+	/// on the CLI or <c>answer:{name}</c> in MCP tool calls.
+	/// </summary>
+	/// <param name="name">Answer name (matches the <c>name</c> parameter in <c>AskConfirmationAsync</c>, <c>AskChoiceAsync</c>, etc.).</param>
+	/// <param name="type">Value type using route constraint names: <c>string</c>, <c>bool</c>, <c>int</c>, <c>guid</c>, <c>email</c>, etc.</param>
+	/// <param name="description">Optional description for help text and agent tool schemas.</param>
+	/// <returns>The same builder instance.</returns>
+	public CommandBuilder WithAnswer(string name, string type = "string", string? description = null)
+	{
+		ArgumentException.ThrowIfNullOrWhiteSpace(name);
+		_answers.Add(new AnswerDeclaration(name, type, description));
+		return this;
+	}
+
 	// ── Annotation shortcuts ───────────────────────────────────────────
 	// Same style as Hidden() — short, chainable, directly on CommandBuilder.
 	// Uses `with` expressions to preserve record immutability.

src/Repl.Core/CoreReplApp.Documentation.cs

@@ -234,6 +234,8 @@ private ReplDocCommand BuildDocumentationCommand(RouteDefinition route)
 			});
 		var options = regularOptions.Concat(groupOptions).ToArray();
 
+		var answers = BuildDocumentationAnswers(route.Command);
+
 		return new ReplDocCommand(
 			Path: route.Template.Template,
 			Description: route.Command.Description,
@@ -244,10 +246,25 @@ private ReplDocCommand BuildDocumentationCommand(RouteDefinition route)
 			Details: route.Command.Details,
 			Annotations: route.Command.Annotations,
 			Metadata: route.Command.Metadata.Count > 0 ? route.Command.Metadata : null,
+			Answers: answers.Length > 0 ? answers : null,
 			IsResource: route.Command.IsResource,
 			IsPrompt: route.Command.IsPrompt);
 	}
 
+	private static ReplDocAnswer[] BuildDocumentationAnswers(CommandBuilder command)
+	{
+		var fluentAnswers = command.Answers
+			.Select(a => new ReplDocAnswer(a.Name, a.Type, a.Description));
+		var attributeAnswers = command.Handler.Method
+			.GetCustomAttributes<AnswerAttribute>()
+			.Select(a => new ReplDocAnswer(a.Name, a.Type, a.Description));
+		return fluentAnswers
+			.Concat(attributeAnswers)
+			.GroupBy(a => a.Name, StringComparer.OrdinalIgnoreCase)
+			.Select(g => g.First())
+			.ToArray();
+	}
+
 	private ReplDocApp BuildDocumentationApp()
 	{
 		var assembly = Assembly.GetEntryAssembly() ?? Assembly.GetExecutingAssembly();

src/Repl.Core/Documentation/ReplDocAnswer.cs

@@ -0,0 +1,9 @@
+namespace Repl.Documentation;
+
+/// <summary>
+/// Answer slot metadata for commands with interactive prompts.
+/// </summary>
+public sealed record ReplDocAnswer(
+	string Name,
+	string Type,
+	string? Description);

src/Repl.Core/Documentation/ReplDocCommand.cs

@@ -13,5 +13,6 @@ public sealed record ReplDocCommand(
 	string? Details = null,
 	CommandAnnotations? Annotations = null,
 	IReadOnlyDictionary<string, object>? Metadata = null,
+	IReadOnlyList<ReplDocAnswer>? Answers = null,
 	bool IsResource = false,
 	bool IsPrompt = false);

src/Repl.Core/HelpTextBuilder.cs

@@ -265,17 +265,18 @@ private static string BuildSingleCommandHelp(RouteDefinition route, bool useAnsi
 			: $"{Environment.NewLine}Aliases: {string.Join(", ", route.Command.Aliases)}";
 		var argumentSection = BuildArgumentSection(route, useAnsi, palette);
 		var optionSection = BuildOptionSection(route, useAnsi, palette);
+		var answerSection = BuildAnswerSection(route, useAnsi, palette);
 		if (!useAnsi)
 		{
-			return $"Usage: {displayTemplate}{Environment.NewLine}Description: {description}{aliases}{argumentSection}{optionSection}";
+			return $"Usage: {displayTemplate}{Environment.NewLine}Description: {description}{aliases}{argumentSection}{optionSection}{answerSection}";
 		}
 
 		var usage = $"{AnsiText.Apply("Usage:", palette.SectionStyle)} {AnsiText.Apply(displayTemplate, palette.CommandStyle)}";
 		var desc = $"{AnsiText.Apply("Description:", palette.SectionStyle)} {AnsiText.Apply(description, palette.DescriptionStyle)}";
 		var aliasText = route.Command.Aliases.Count == 0
 			? string.Empty
 			: $"{Environment.NewLine}{AnsiText.Apply("Aliases:", palette.SectionStyle)} {AnsiText.Apply(string.Join(", ", route.Command.Aliases), palette.CommandStyle)}";
-		return $"{usage}{Environment.NewLine}{desc}{aliasText}{argumentSection}{optionSection}";
+		return $"{usage}{Environment.NewLine}{desc}{aliasText}{argumentSection}{optionSection}{answerSection}";
 	}
 
 	private static string BuildArgumentSection(RouteDefinition route, bool useAnsi, AnsiPalette palette)
@@ -321,6 +322,31 @@ private static string BuildArgumentSection(RouteDefinition route, bool useAnsi,
 		return builder.ToString();
 	}
 
+	private static string BuildAnswerSection(RouteDefinition route, bool useAnsi, AnsiPalette palette)
+	{
+		if (route.Command.Answers.Count == 0)
+		{
+			return string.Empty;
+		}
+
+		var builder = new StringBuilder();
+		builder.AppendLine();
+		builder.Append(useAnsi
+			? AnsiText.Apply("Answers:", palette.SectionStyle)
+			: "Answers:");
+		foreach (var answer in route.Command.Answers)
+		{
+			var token = $"--answer:{answer.Name}";
+			var desc = answer.Description ?? $"({answer.Type})";
+			builder.AppendLine();
+			builder.Append(useAnsi
+				? $"  {AnsiText.Apply(token, palette.CommandStyle)}  {AnsiText.Apply(desc, palette.DescriptionStyle)}"
+				: $"  {token}  {desc}");
+		}
+
+		return builder.ToString();
+	}
+
 	private static string BuildOptionSection(RouteDefinition route, bool useAnsi, AnsiPalette palette)
 	{
 		var parameters = route.Command.Handler.Method.GetParameters()

src/Repl.Core/Parameters/Attributes/AnswerAttribute.cs

@@ -0,0 +1,18 @@
+namespace Repl;
+
+/// <summary>
+/// Declares an interactive answer slot on a command handler method.
+/// Equivalent to calling <see cref="CommandBuilder.WithAnswer"/> in the fluent API.
+/// </summary>
+[AttributeUsage(AttributeTargets.Method, AllowMultiple = true)]
+public sealed class AnswerAttribute(string name, string type = "string") : Attribute
+{
+	/// <summary>Answer name (matches the <c>name</c> parameter in <c>AskConfirmationAsync</c>, etc.).</summary>
+	public string Name { get; } = name;
+
+	/// <summary>Value type using route constraint names: <c>string</c>, <c>bool</c>, <c>int</c>, etc.</summary>
+	public string Type { get; } = type;
+
+	/// <summary>Optional description for help text and agent tool schemas.</summary>
+	public string? Description { get; set; }
+}

src/Repl.Mcp/McpInteractionChannel.cs

@@ -64,7 +64,7 @@ public async ValueTask<int> AskChoiceAsync(
 
 		throw new McpInteractionException(
 			$"Interactive prompt '{name}' requires a value. " +
-			$"Provide it as a tool argument 'answer:{name}'. Choices: {string.Join(", ", choices)}");
+			$"Provide it as a tool argument 'answer.{name}'. Choices: {string.Join(", ", choices)}");
 	}
 
 	public async ValueTask<bool> AskConfirmationAsync(
@@ -100,7 +100,7 @@ public async ValueTask<bool> AskConfirmationAsync(
 
 		throw new McpInteractionException(
 			$"Interactive prompt '{name}' requires a value. " +
-			$"Provide it as a tool argument 'answer:{name}' (true/false).");
+			$"Provide it as a tool argument 'answer.{name}' (true/false).");
 	}
 
 	public async ValueTask<string> AskTextAsync(
@@ -136,7 +136,7 @@ public async ValueTask<string> AskTextAsync(
 
 		throw new McpInteractionException(
 			$"Interactive prompt '{name}' requires a value. " +
-			$"Provide it as a tool argument 'answer:{name}'.");
+			$"Provide it as a tool argument 'answer.{name}'.");
 	}
 
 	public ValueTask<string> AskSecretAsync(
@@ -152,7 +152,7 @@ public ValueTask<string> AskSecretAsync(
 
 		throw new McpInteractionException(
 			$"Secret prompt '{name}' requires a prefilled value. " +
-			$"Provide it as a tool argument 'answer:{name}'.");
+			$"Provide it as a tool argument 'answer.{name}'.");
 	}
 
 	public async ValueTask<IReadOnlyList<int>> AskMultiChoiceAsync(
@@ -185,7 +185,7 @@ public async ValueTask<IReadOnlyList<int>> AskMultiChoiceAsync(
 
 		throw new McpInteractionException(
 			$"Interactive prompt '{name}' requires a value. " +
-			$"Provide it as a tool argument 'answer:{name}' (comma-separated). " +
+			$"Provide it as a tool argument 'answer.{name}' (comma-separated). " +
 			$"Choices: {string.Join(", ", choices)}");
 	}