Fixed tool calling with Groq and OpenRouter (#1003)

app/MindWork AI Studio/Provider/BaseProvider.cs

@@ -1245,6 +1245,7 @@ public abstract class BaseProvider : IProvider, ISecretId
     /// <param name="requestPath">The request path, relative to the provider base URL.</param>
     /// <param name="headersAction">Optional additional headers to add.</param>
     /// <param name="mayAskForSequentialToolCalls">Whether a request which offers tools may ask for one call at a time. False for a provider which rejects the parallel_tool_calls parameter.</param>
+    /// <param name="enforcesStrictToolSchemas">Whether the provider binds the model's tool calls to a strict schema. Only then are tools offered in strict mode; everywhere else a strict schema would only tell the model that every argument is required.</param>
     /// <param name="token">The cancellation token.</param>
     /// <typeparam name="TRequest">The request DTO type.</typeparam>
     /// <typeparam name="TDelta">The delta stream line type.</typeparam>
@@ -1262,6 +1263,7 @@ public abstract class BaseProvider : IProvider, ISecretId
         string requestPath = "chat/completions",
         Action<HttpRequestHeaders>? headersAction = null,
         bool mayAskForSequentialToolCalls = true,
+        bool enforcesStrictToolSchemas = false,
         [EnumeratorCancellation] CancellationToken token = default)
         where TRequest : ChatCompletionAPIRequest
         where TDelta : IResponseStreamLine
@@ -1300,7 +1302,7 @@ public abstract class BaseProvider : IProvider, ISecretId
             if (runnableTools.Count > 0)
             {
                 var adapter = new ChatCompletionToolCallingAdapter<TRequest>(requestFactory, systemPrompt, apiParameters,
-                    runnableTools.Select(x => ProviderToolAdapters.ToChatCompletionTool(x.Definition)).ToList(), mayAskForSequentialToolCalls, runnableTools,
+                    runnableTools.Select(x => ProviderToolAdapters.ToChatCompletionTool(x.Definition, enforcesStrictToolSchemas)).ToList(), mayAskForSequentialToolCalls, runnableTools,
                     (requestDto, requestToken) => this.StreamChatCompletionRequest(requestDto, providerName, requestPath, requestedSecret, headersAction, requestToken),
                     ChatCompletionSourceReader.Read<TDelta, TAnnotation>,
                     this.logger);

app/MindWork AI Studio/Provider/OpenAI/ProviderOpenAI.cs

@@ -168,6 +168,16 @@ public sealed class ProviderOpenAI() : BaseProvider(LLMProviders.OPEN_AI, new Ur
                                },
                                systemPromptRole: systemPromptRole,
                                requestPath: "chat/completions",
+
+                               //
+                               // OpenAI binds a strict function's arguments to its schema -- read on
+                               // 2026-09-24 at https://developers.openai.com/api/docs/guides/function-calling.
+                               // Most other hosts of this API do not: Groq applies strict mode to
+                               // response formats only (https://console.groq.com/docs/structured-outputs,
+                               // same day) and merely validates a tool call afterward, so it rejects
+                               // every call that leaves out an argument the strict schema requires:
+                               //
+                               enforcesStrictToolSchemas: true,
                                token: token))
                 yield return content;
 

app/MindWork AI Studio/Provider/ProviderToolAdapters.cs

@@ -10,33 +10,47 @@ namespace AIStudio.Provider;
 /// <remarks>
 /// The definitions state a tool once, in plain JSON Schema. What differs per API is not only the
 /// field names but how an optional argument is expressed, which is why the OpenAI shapes convert
-/// the schema while Anthropic takes it as written.
+/// the schema while Anthropic takes it as written.<br/><br/>
+/// Strict mode is a promise of the host, not of the definition: only a host which binds the
+/// model's output to the schema keeps it. Everywhere else the model merely reads a schema that
+/// calls every argument required, and then either invents a value for an argument it meant to
+/// leave out, or the host rejects the call for lacking one. That is why the Chat Completions
+/// shape, which reaches every OpenAI-compatible host, only goes strict where the host says so.
 /// </remarks>
 public static class ProviderToolAdapters
 {
     /// <summary>
     /// Builds the nested function tool shape used by Chat Completions compatible APIs.
     /// </summary>
-    public static object ToChatCompletionTool(ToolDefinition definition) => new
+    /// <param name="definition">The tool to describe.</param>
+    /// <param name="hostEnforcesStrict">Whether the host binds the model's tool calls to a strict schema. Only then is the tool sent in strict mode.</param>
+    public static object ToChatCompletionTool(ToolDefinition definition, bool hostEnforcesStrict)
     {
-        type = "function",
-        function = new
+        var isStrict = definition.Function.Strict && hostEnforcesStrict;
+        return new
         {
-            name = definition.Function.Name,
-            description = definition.Function.DescriptionForLLM,
-            parameters = ToOpenAIParameters(definition),
-            strict = definition.Function.Strict,
-        }
-    };
+            type = "function",
+            function = new
+            {
+                name = definition.Function.Name,
+                description = definition.Function.DescriptionForLLM,
+                parameters = ToOpenAIParameters(definition, isStrict),
+                strict = isStrict,
+            }
+        };
+    }
 
     /// <summary>
     /// Builds the flat function tool shape used by the OpenAI Responses API.
     /// </summary>
+    /// <remarks>
+    /// Only OpenAI speaks this API, and it enforces strict mode, so the definition alone decides.
+    /// </remarks>
     public static ResponsesFunctionTool ToResponsesTool(ToolDefinition definition) => new()
     {
         Name = definition.Function.Name,
         Description = definition.Function.DescriptionForLLM,
-        Parameters = ToOpenAIParameters(definition),
+        Parameters = ToOpenAIParameters(definition, definition.Function.Strict),
         Strict = definition.Function.Strict,
     };
 
@@ -59,7 +73,7 @@ public static class ProviderToolAdapters
     /// <summary>
     /// The parameter schema for the OpenAI APIs, converted only when strict mode asks for it.
     /// </summary>
-    private static System.Text.Json.JsonElement ToOpenAIParameters(ToolDefinition definition) => definition.Function.Strict
+    private static System.Text.Json.JsonElement ToOpenAIParameters(ToolDefinition definition, bool isStrict) => isStrict
         ? OpenAIStrictToolSchema.FromToolParameters(definition.Function.Parameters)
         : definition.Function.Parameters;
 }

app/MindWork AI Studio/Tools/ToolCallingSystem/ToolCallingImplementations/WebSearch/WebSearchTool.cs

@@ -94,9 +94,28 @@ public sealed class WebSearchTool(IEnumerable<IWebSearchBackend> backends, WebPa
     private const string LIMIT_ARGUMENT = "limit";
 
     private const string TIME_RANGE_DAY = "day";
+    private const string TIME_RANGE_WEEK = "week";
     private const string TIME_RANGE_MONTH = "month";
     private const string TIME_RANGE_YEAR = "year";
 
+    /// <summary>
+    /// The time ranges a search can be restricted to.
+    /// </summary>
+    /// <remarks>
+    /// Those which both services with a time filter, SearXNG and Tavily, understand and take as
+    /// they are. Tavily documents all four. SearXNG's API documentation names no week, but its code accepts
+    /// one -- read on 2026-09-24 in parse_time_range of searx/webadapter.py. A model asked about
+    /// "this week" wants exactly that, and without it, it asks for a week again and again.<br/><br/>
+    /// The schema offers exactly these and the reader checks against them, so the two cannot drift
+    /// apart.
+    /// </remarks>
+    private static readonly string[] TIME_RANGES = [TIME_RANGE_DAY, TIME_RANGE_WEEK, TIME_RANGE_MONTH, TIME_RANGE_YEAR];
+
+    /// <summary>
+    /// How much of a wrongly passed argument an error message repeats back to the model.
+    /// </summary>
+    private const int MAX_ARGUMENT_ECHO_LENGTH = 40;
+
     public string ImplementationKey => ToolSelectionRules.WEB_SEARCH_TOOL_ID;
 
     /// <inheritdoc />
@@ -118,7 +137,7 @@ public sealed class WebSearchTool(IEnumerable<IWebSearchBackend> backends, WebPa
             Parameters = ToolParameterSchemaBuilder.Create()
                 .RequiredString(QUERY_ARGUMENT, "The search query.")
                 .OptionalString(LANGUAGE_ARGUMENT, "Optional IETF language tag restricting the search to one language, such as 'de-DE', 'en-US', or 'all' for no restriction. Leave it out to search in the language configured for this tool. Do not pass a language name such as 'German': search engines expect the tag and silently return nothing for anything else.")
-                .OptionalEnum(TIME_RANGE_ARGUMENT, "Optional time range filter for the search.", TIME_RANGE_DAY, TIME_RANGE_MONTH, TIME_RANGE_YEAR)
+                .OptionalEnum(TIME_RANGE_ARGUMENT, "Optional time range filter for the search.", TIME_RANGES)
                 .OptionalInteger(PAGE_ARGUMENT, "Optional search result page number starting at 1.")
                 .OptionalInteger(LIMIT_ARGUMENT, $"Optional maximum number of ranked result pages to retrieve and return. The hard maximum is {MAX_RESULTS}.")
                 .Build(),
@@ -482,14 +501,11 @@ public sealed class WebSearchTool(IEnumerable<IWebSearchBackend> backends, WebPa
 
     public async Task<ToolExecutionResult> ExecuteAsync(JsonElement arguments, ToolExecutionContext context, CancellationToken token = default)
     {
-        var query = ReadRequiredString(arguments, QUERY_ARGUMENT);
-        var language = ReadOptionalString(arguments, LANGUAGE_ARGUMENT);
-        var timeRange = ReadOptionalString(arguments, TIME_RANGE_ARGUMENT);
-        var page = ReadOptionalPositiveInt(arguments, PAGE_ARGUMENT);
-        var requestedLimit = ReadOptionalPositiveInt(arguments, LIMIT_ARGUMENT);
-
-        if (timeRange is not null && timeRange is not (TIME_RANGE_DAY or TIME_RANGE_MONTH or TIME_RANGE_YEAR))
-            throw new ArgumentException($"Invalid time_range '{timeRange}'.");
+        var query = ReadQuery(arguments);
+        var language = ReadLanguage(arguments);
+        var timeRange = ReadTimeRange(arguments);
+        var page = ReadPage(arguments);
+        var requestedLimit = ReadLimit(arguments);
 
         language = string.IsNullOrWhiteSpace(language) ? context.SettingsValues.GetValueOrDefault(DEFAULT_LANGUAGE_SETTING) : language;
         var safeSearch = ReadSafeSearchPolicy(context.SettingsValues);
@@ -807,42 +823,99 @@ public sealed class WebSearchTool(IEnumerable<IWebSearchBackend> backends, WebPa
         return result;
     }
 
-    private static string ReadRequiredString(JsonElement arguments, string propertyName)
+    /// <summary>
+    /// Reads the search query, the one argument the model always has to pass.
+    /// </summary>
+    internal static string ReadQuery(JsonElement arguments)
     {
-        var value = ReadOptionalString(arguments, propertyName);
-        if (string.IsNullOrWhiteSpace(value))
-            throw new ArgumentException($"Missing required argument '{propertyName}'.");
+        var query = ReadOptionalString(arguments, QUERY_ARGUMENT, whenLeftOut: null);
+        if (string.IsNullOrWhiteSpace(query))
+            throw new ArgumentException($"Missing required argument '{QUERY_ARGUMENT}'.");
 
-        return value;
+        return query;
     }
 
-    private static string? ReadOptionalString(JsonElement arguments, string propertyName)
+    /// <summary>
+    /// Reads the language tag the model asked for, or null for the configured language.
+    /// </summary>
+    internal static string? ReadLanguage(JsonElement arguments) => ReadOptionalString(arguments, LANGUAGE_ARGUMENT, "to use the configured language");
+
+    /// <summary>
+    /// Reads the time range the model asked for, or null for no restriction.
+    /// </summary>
+    internal static string? ReadTimeRange(JsonElement arguments)
     {
-        if (!arguments.TryGetProperty(propertyName, out var value))
+        if (!TryGetArgument(arguments, TIME_RANGE_ARGUMENT, out var value))
             return null;
 
-        return value.ValueKind switch
-        {
-            JsonValueKind.Null => null,
-            JsonValueKind.String => value.GetString()?.Trim(),
-            _ => throw new ArgumentException($"Argument '{propertyName}' must be a string."),
-        };
+        var timeRange = value.ValueKind is JsonValueKind.String ? value.GetString()?.Trim() : null;
+        if (timeRange is null || !TIME_RANGES.Contains(timeRange, StringComparer.Ordinal))
+            throw InvalidArgument(TIME_RANGE_ARGUMENT, value, $"one of {string.Join(", ", TIME_RANGES)}", "to search without a time restriction");
+
+        return timeRange;
     }
 
-    private static int? ReadOptionalPositiveInt(JsonElement arguments, string propertyName)
+    /// <summary>
+    /// Reads the result page the model asked for, or null for the first one.
+    /// </summary>
+    internal static int? ReadPage(JsonElement arguments) => ReadOptionalPositiveInt(arguments, PAGE_ARGUMENT, "to get the first page");
+
+    /// <summary>
+    /// Reads how many results the model asked for, or null for the configured number.
+    /// </summary>
+    internal static int? ReadLimit(JsonElement arguments) => ReadOptionalPositiveInt(arguments, LIMIT_ARGUMENT, "to get as many results as configured");
+
+    /// <summary>
+    /// Looks up an argument, treating null the same as leaving it out.
+    /// </summary>
+    private static bool TryGetArgument(JsonElement arguments, string propertyName, out JsonElement value) =>
+        arguments.TryGetProperty(propertyName, out value) && value.ValueKind is not JsonValueKind.Null;
+
+    private static string? ReadOptionalString(JsonElement arguments, string propertyName, string? whenLeftOut)
     {
-        if (!arguments.TryGetProperty(propertyName, out var value))
+        if (!TryGetArgument(arguments, propertyName, out var value))
             return null;
 
-        if (value.ValueKind is JsonValueKind.Null)
+        if (value.ValueKind is not JsonValueKind.String)
+            throw InvalidArgument(propertyName, value, "a string", whenLeftOut);
+
+        return value.GetString()?.Trim();
+    }
+
+    private static int? ReadOptionalPositiveInt(JsonElement arguments, string propertyName, string whenLeftOut)
+    {
+        if (!TryGetArgument(arguments, propertyName, out var value))
             return null;
 
         if (value.ValueKind is not JsonValueKind.Number || !value.TryGetInt32(out var intValue) || intValue <= 0)
-            throw new ArgumentException($"Argument '{propertyName}' must be a positive integer.");
+            throw InvalidArgument(propertyName, value, "a positive integer", whenLeftOut);
 
         return intValue;
     }
 
+    /// <summary>
+    /// Builds the error a model gets for an argument it passed wrongly.
+    /// </summary>
+    /// <remarks>
+    /// The model reads this and tries again, so it says what arrived, what would have been right,
+    /// and, for an optional argument, that leaving it out is always an option. A model which
+    /// believes the argument has to be there otherwise keeps trying placeholders, and every attempt
+    /// costs one of the tool calls an answer may make.
+    /// </remarks>
+    /// <param name="propertyName">The argument.</param>
+    /// <param name="value">What the model passed, as it arrived.</param>
+    /// <param name="expectation">What the argument must be, completing "must be ...".</param>
+    /// <param name="whenLeftOut">What happens without the argument, completing "Leave it out ...", or null for a required one.</param>
+    private static ArgumentException InvalidArgument(string propertyName, JsonElement value, string expectation, string? whenLeftOut)
+    {
+        var receivedValue = value.GetRawText();
+        if (receivedValue.Length > MAX_ARGUMENT_ECHO_LENGTH)
+            receivedValue = $"{receivedValue[..MAX_ARGUMENT_ECHO_LENGTH]}...";
+
+        var message = $"Argument '{propertyName}' must be {expectation}, but was {receivedValue}.";
+        return new ArgumentException(whenLeftOut is null ? message : $"{message} Leave it out {whenLeftOut}.");
+    }
+
     private static string FormatQueryForLog(string query)
     {
         var singleLineQuery = query

app/MindWork AI Studio/Tools/ToolCallingSystem/ToolFunctionDefinition.cs

@@ -8,6 +8,14 @@ public sealed class ToolFunctionDefinition
 
     public string DescriptionForLLM { get; init; } = string.Empty;
 
+    /// <summary>
+    /// Whether this tool may be offered in strict mode.
+    /// </summary>
+    /// <remarks>
+    /// The host has a say as well: a tool goes strict only where the host binds the model's calls
+    /// to the schema, see ProviderToolAdapters. Setting this to false keeps a tool out of strict
+    /// mode everywhere, for a schema which strict mode cannot express.
+    /// </remarks>
     public bool Strict { get; init; } = true;
 
     public JsonElement Parameters { get; init; }

app/Tests/Provider/ToolCalling/OpenAIStrictToolSchemaTests.cs

@@ -0,0 +1,107 @@
+using System.Text.Json.Nodes;
+
+using AIStudio.Provider.OpenAI;
+using AIStudio.Tools.ToolCallingSystem;
+
+namespace AIStudio.Tests.Provider.ToolCalling;
+
+/// <summary>
+/// Checks how a tool's parameter schema is translated into the form OpenAI's strict mode requires.
+/// </summary>
+/// <remarks>
+/// Strict mode wants every argument required and says "may be left out" by allowing null instead.
+/// The translation has to keep what the schema means: an argument the tool can do without stays
+/// one the model can leave empty, and an argument the tool needs stays exactly as it was.
+/// </remarks>
+[TestFixture]
+public sealed class OpenAIStrictToolSchemaTests
+{
+    [Test]
+    public void AnOptionalArgumentMayBeNullInstead()
+    {
+        var properties = Converted(ToolParameterSchemaBuilder.Create()
+            .RequiredString("query", "The search query.")
+            .OptionalString("language", "The language.")
+            .OptionalInteger("page", "The page."))["properties"]!;
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(Types(properties["language"]!), Is.EqualTo(new[] { "string", "null" }));
+            Assert.That(Types(properties["page"]!), Is.EqualTo(new[] { "integer", "null" }));
+        });
+    }
+
+    [Test]
+    public void AnOptionalChoiceOffersNullAmongItsValues()
+    {
+        var timeRange = Converted(ToolParameterSchemaBuilder.Create()
+            .RequiredString("query", "The search query.")
+            .OptionalEnum("time_range", "The time range.", "day", "month", "year"))["properties"]!["time_range"]!;
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(Types(timeRange), Is.EqualTo(new[] { "string", "null" }));
+            Assert.That(timeRange["enum"]!.AsArray().Select(value => value?.GetValue<string>()), Is.EqualTo(new[] { null, "day", "month", "year" }));
+        });
+    }
+
+    [Test]
+    public void ARequiredArgumentStaysAsItIs()
+    {
+        var query = Converted(ToolParameterSchemaBuilder.Create()
+            .RequiredString("query", "The search query.")
+            .OptionalString("language", "The language."))["properties"]!["query"]!;
+
+        Assert.That(query["type"]!.GetValue<string>(), Is.EqualTo("string"));
+    }
+
+    [Test]
+    public void EveryArgumentIsRequiredInTheOrderOfTheProperties()
+    {
+        //
+        // The order has to be stable across requests, because prompt caching depends on it. The
+        // optional argument comes first here, so an order taken from the old required list would
+        // show.
+        //
+        var schema = Converted(ToolParameterSchemaBuilder.Create()
+            .OptionalString("language", "The language.")
+            .RequiredString("query", "The search query."));
+
+        Assert.That(schema["required"]!.AsArray().Select(name => name!.GetValue<string>()), Is.EqualTo(new[] { "language", "query" }));
+    }
+
+    [Test]
+    public void ExtraArgumentsStayRefused()
+    {
+        var schema = Converted(ToolParameterSchemaBuilder.Create()
+            .RequiredString("query", "The search query.")
+            .OptionalString("language", "The language."));
+
+        Assert.That(schema["additionalProperties"]!.GetValue<bool>(), Is.False);
+    }
+
+    [Test]
+    public void ASchemaWithoutOptionalArgumentsIsLeftUntouched()
+    {
+        var parameters = ToolParameterSchemaBuilder.Create()
+            .RequiredString("url", "The address of the page.")
+            .Build();
+
+        var converted = OpenAIStrictToolSchema.FromToolParameters(parameters);
+        Assert.That(JsonNode.DeepEquals(JsonNode.Parse(converted.GetRawText()), JsonNode.Parse(parameters.GetRawText())), Is.True);
+    }
+
+    /// <summary>
+    /// Builds the schema and returns it the way strict mode receives it.
+    /// </summary>
+    private static JsonNode Converted(ToolParameterSchemaBuilder builder) => JsonNode.Parse(OpenAIStrictToolSchema.FromToolParameters(builder.Build()).GetRawText())!;
+
+    /// <summary>
+    /// Reads the types a property allows, whether it names one or several.
+    /// </summary>
+    private static string[] Types(JsonNode property) => property["type"] switch
+    {
+        JsonArray types => types.Select(type => type!.GetValue<string>()).ToArray(),
+        var type => [type!.GetValue<string>()],
+    };
+}

app/Tests/Provider/ToolCalling/ProviderToolAdaptersTests.cs

@@ -0,0 +1,85 @@
+using System.Text.Json;
+using System.Text.Json.Nodes;
+
+using AIStudio.Provider;
+using AIStudio.Tools.ToolCallingSystem;
+
+namespace AIStudio.Tests.Provider.ToolCalling;
+
+/// <summary>
+/// Checks when a tool reaches a Chat Completions host in strict mode, and when as written.
+/// </summary>
+/// <remarks>
+/// Strict mode only holds where the host binds the model's calls to the schema. Anywhere else, the
+/// model just reads a schema which calls every argument required: Groq then rejects each call that
+/// leaves one out, and other models fill the gap with a placeholder the tool has to refuse. Such a
+/// host therefore gets the schema the way the tool wrote it.
+/// </remarks>
+[TestFixture]
+public sealed class ProviderToolAdaptersTests
+{
+    [Test]
+    public void AHostWhichDoesNotEnforceStrictModeGetsTheSchemaAsWritten()
+    {
+        var definition = WebSearchLike();
+        var function = Sent(definition, hostEnforcesStrict: false);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(function["strict"]!.GetValue<bool>(), Is.False);
+            Assert.That(JsonNode.DeepEquals(function["parameters"], JsonNode.Parse(definition.Function.Parameters.GetRawText())), Is.True);
+        });
+    }
+
+    [Test]
+    public void AHostWhichEnforcesStrictModeGetsTheConvertedSchema()
+    {
+        var function = Sent(WebSearchLike(), hostEnforcesStrict: true);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(function["strict"]!.GetValue<bool>(), Is.True);
+            Assert.That(function["parameters"]!["required"]!.AsArray().Select(name => name!.GetValue<string>()), Is.EqualTo(new[] { "query", "page" }));
+        });
+    }
+
+    [Test]
+    public void AToolWhichOptsOutStaysOutOfStrictModeEverywhere()
+    {
+        var definition = WebSearchLike(isStrict: false);
+        var function = Sent(definition, hostEnforcesStrict: true);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(function["strict"]!.GetValue<bool>(), Is.False);
+            Assert.That(JsonNode.DeepEquals(function["parameters"], JsonNode.Parse(definition.Function.Parameters.GetRawText())), Is.True);
+        });
+    }
+
+    /// <summary>
+    /// A tool with one required and one optional argument, the shape the web search has.
+    /// </summary>
+    private static ToolDefinition WebSearchLike(bool isStrict = true) => new()
+    {
+        Id = "web_search",
+        Function = new()
+        {
+            Name = "web_search",
+            DescriptionForLLM = "Search the web.",
+            Strict = isStrict,
+            Parameters = ToolParameterSchemaBuilder.Create()
+                .RequiredString("query", "The search query.")
+                .OptionalInteger("page", "The page, starting at 1.")
+                .Build(),
+        },
+    };
+
+    /// <summary>
+    /// Returns the function object of the tool as it goes over the wire.
+    /// </summary>
+    private static JsonNode Sent(ToolDefinition definition, bool hostEnforcesStrict)
+    {
+        var tool = ProviderToolAdapters.ToChatCompletionTool(definition, hostEnforcesStrict);
+        return JsonNode.Parse(JsonSerializer.Serialize(tool, ProviderJsonOptions.OPTIONS))!["function"]!;
+    }
+}

app/Tests/Tools/ToolCalling/WebSearchToolArgumentTests.cs

@@ -0,0 +1,170 @@
+using System.Text.Json;
+
+using AIStudio.Tools.ToolCallingSystem.ToolCallingImplementations.WebSearch;
+
+namespace AIStudio.Tests.Tools.ToolCalling;
+
+/// <summary>
+/// Checks how the web search reads the arguments a model passes, and what it says about wrong ones.
+/// </summary>
+/// <remarks>
+/// A wrong argument is refused rather than guessed at: a placeholder such as 0 is not a page, and
+/// quietly reading it as "no page" would do something the model did not ask for. What makes the
+/// refusal work is its message. The model reads it and tries again, so it has to say what arrived,
+/// what would have been right, and that an optional argument may simply be left out. A model
+/// which believes it has to pass one otherwise keeps trying placeholders, and every attempt costs
+/// one of the tool calls an answer may make.
+/// </remarks>
+[TestFixture]
+public sealed class WebSearchToolArgumentTests
+{
+    [Test]
+    public void AnArgumentLeftOutIsNotSet()
+    {
+        var arguments = Arguments("""{"query":"weather"}""");
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(WebSearchTool.ReadLanguage(arguments), Is.Null);
+            Assert.That(WebSearchTool.ReadTimeRange(arguments), Is.Null);
+            Assert.That(WebSearchTool.ReadPage(arguments), Is.Null);
+            Assert.That(WebSearchTool.ReadLimit(arguments), Is.Null);
+        });
+    }
+
+    [Test]
+    public void ANullArgumentIsTheSameAsOneLeftOut()
+    {
+        var arguments = Arguments("""{"query":"weather","language":null,"time_range":null,"page":null,"limit":null}""");
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(WebSearchTool.ReadLanguage(arguments), Is.Null);
+            Assert.That(WebSearchTool.ReadTimeRange(arguments), Is.Null);
+            Assert.That(WebSearchTool.ReadPage(arguments), Is.Null);
+            Assert.That(WebSearchTool.ReadLimit(arguments), Is.Null);
+        });
+    }
+
+    [Test]
+    public void ValidArgumentsComeThrough()
+    {
+        var arguments = Arguments("""{"query":"  weather  ","language":"de-DE","time_range":"day","page":2,"limit":7}""");
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(WebSearchTool.ReadQuery(arguments), Is.EqualTo("weather"));
+            Assert.That(WebSearchTool.ReadLanguage(arguments), Is.EqualTo("de-DE"));
+            Assert.That(WebSearchTool.ReadTimeRange(arguments), Is.EqualTo("day"));
+            Assert.That(WebSearchTool.ReadPage(arguments), Is.EqualTo(2));
+            Assert.That(WebSearchTool.ReadLimit(arguments), Is.EqualTo(7));
+        });
+    }
+
+    [TestCase("0")]
+    [TestCase("-1")]
+    [TestCase("2.5")]
+    [TestCase("\"5\"")]
+    [TestCase("true")]
+    public void AWrongPageIsRefusedWithWhatArrived(string value)
+    {
+        var message = Refusal(() => WebSearchTool.ReadPage(Arguments($$"""{"query":"weather","page":{{value}}}""")));
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(message, Does.Contain("'page'").And.Contain("a positive integer"));
+            Assert.That(message, Does.Contain($"but was {value}."), "Without the value, the model cannot tell which of its arguments the tool means.");
+            Assert.That(message, Does.Contain("Leave it out"), "The way out a model needs when it believes the argument is required.");
+        });
+    }
+
+    [TestCase("0")]
+    [TestCase("-1")]
+    [TestCase("\"5\"")]
+    public void AWrongLimitIsRefusedWithWhatArrived(string value)
+    {
+        var message = Refusal(() => WebSearchTool.ReadLimit(Arguments($$"""{"query":"weather","limit":{{value}}}""")));
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(message, Does.Contain("'limit'").And.Contain("a positive integer"));
+            Assert.That(message, Does.Contain($"but was {value}."));
+            Assert.That(message, Does.Contain("Leave it out"));
+        });
+    }
+
+    [TestCase("day")]
+    [TestCase("week")]
+    [TestCase("month")]
+    [TestCase("year")]
+    public void EveryOfferedTimeRangeIsAccepted(string timeRange)
+    {
+        //
+        // The week is the one a model asks for when the user says "this week". Both services with
+        // a time filter understand it, and refusing it only made the model try it again and again.
+        //
+        Assert.That(WebSearchTool.ReadTimeRange(Arguments($$"""{"query":"weather","time_range":"{{timeRange}}"}""")), Is.EqualTo(timeRange));
+    }
+
+    [TestCase("\"\"")]
+    [TestCase("\"Day\"")]
+    [TestCase("\"decade\"")]
+    [TestCase("5")]
+    public void AWrongTimeRangeIsRefusedWithTheValuesThatWouldDo(string value)
+    {
+        var message = Refusal(() => WebSearchTool.ReadTimeRange(Arguments($$"""{"query":"weather","time_range":{{value}}}""")));
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(message, Does.Contain("'time_range'").And.Contain("one of day, week, month, year"));
+            Assert.That(message, Does.Contain($"but was {value}."));
+            Assert.That(message, Does.Contain("Leave it out"));
+        });
+    }
+
+    [Test]
+    public void ALanguageWhichIsNoStringIsRefused()
+    {
+        var message = Refusal(() => WebSearchTool.ReadLanguage(Arguments("""{"query":"weather","language":5}""")));
+        Assert.That(message, Does.Contain("'language'").And.Contain("but was 5.").And.Contain("Leave it out"));
+    }
+
+    [Test]
+    public void AMissingQueryIsRefused()
+    {
+        var message = Refusal(() => WebSearchTool.ReadQuery(Arguments("""{"page":1}""")));
+        Assert.That(message, Does.Contain("Missing required argument 'query'"));
+    }
+
+    [Test]
+    public void AQueryWhichIsNoStringIsRefusedWithoutOfferingToLeaveItOut()
+    {
+        var message = Refusal(() => WebSearchTool.ReadQuery(Arguments("""{"query":42}""")));
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(message, Does.Contain("'query'").And.Contain("but was 42."));
+            Assert.That(message, Does.Not.Contain("Leave it out"), "The query is required, so leaving it out is no way out.");
+        });
+    }
+
+    [Test]
+    public void ALongValueIsShortenedInTheMessage()
+    {
+        var longValue = new string('x', 500);
+        var message = Refusal(() => WebSearchTool.ReadTimeRange(Arguments($$"""{"query":"weather","time_range":"{{longValue}}"}""")));
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(message, Does.Not.Contain(longValue), "The model sent the value itself; repeating all of it back only costs tokens.");
+            Assert.That(message, Does.Contain("..."));
+        });
+    }
+
+    private static JsonElement Arguments(string json) => JsonSerializer.Deserialize<JsonElement>(json);
+
+    /// <summary>
+    /// Runs a reader which has to refuse its argument and returns what it said.
+    /// </summary>
+    private static string Refusal(TestDelegate read) => Assert.Throws<ArgumentException>(read)!.Message;
+}