[BREAKING] .NET: Fix strict skill script argument schemas

[Manjunath Janardhan (manjunathshiva)]

Motivation & Context

run_skill_script advertises JsonElement? arguments as an unconstrained schema ({"default":null}). Azure OpenAI rejects this tool with HTTP 400 invalid_function_parameters when strict mode is enabled, including when a skill has no scripts and the request disables tool calls.

Description & Review Guide

• What are the major changes? Advertise arguments as a nullable JSON-encoded string using the function schema transformation hook. Decode strings exactly once at the provider boundary, then pass the resulting JSON value to the existing script runner or marshaler. Keep direct object/array invocation, tool names, approval wrapping, service-provider forwarding, and C# script interfaces. Add regression coverage for the schema, file arrays, inline objects, legacy structured calls, null, malformed JSON, and single decoding with a custom marshaler.
• What is the impact of these changes? Strict providers receive an explicit parameter type while scripts retain flexible payloads. This changes the model-facing contract: a script expecting { "value": 42 } receives that object after the model supplies arguments: "{\"value\":42}". Custom callers or marshalers that previously used raw string arguments must now JSON-encode those strings. The outer tool schema is strictly validated; payload validation remains with the script or marshaler. Malformed JSON follows the existing IncludeDetailedErrors policy.
• What do you want reviewers to focus on? Acceptance of the JSON-string contract proposed in the issue, including its interaction with custom marshalers and .NET: [Bug]: Agent Skill throws "System.InvalidOperationException" #7989. This remains a draft for design review; maintainer assignment is not treated as approval of this contract change.

Reproduced before the fix against a live Azure OpenAI gpt-5.5 deployment using the v1 Chat Completions API, .NET SDK 10.0.303, Microsoft.Extensions.AI.OpenAI 10.9.0, and OpenAI 2.12.0. The original strict request returned HTTP 400. With the patch, strict and non-strict requests both returned HTTP 200. A further strict request generated an actual run_skill_script call with JSON-encoded arguments, and invoking it returned the expected result, 42.

Full solution build completed with zero warnings or errors. The affected core test project passed all 2,127 tests on .NET 10. The full .NET 10 unit run completed with 7,208 passed, 65 skipped, one failure in the unrelated DevUIIntegrationTests.TestServerWithDevUI_ResolvesRequestToWorkflow_ByKeyAsync test (null discovery collection). The entire DevUI project passed on an immediate isolated rerun. An earlier hosting telemetry assertion also passed on rerun. The all-tests checklist remains unchecked to reflect the full-run result. Local execution used the U.S. locale, DOTNET_HOSTBUILDER__RELOADCONFIGONCHANGE=false, and permission for the Foundry test host to create its local state directory. Formatting and style checks passed.

Related Issue

Fixes #8094

No competing open PR was found in the issue discussion or linked timeline when preparing this draft.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

🔵 Needs a closer look

The intentional model-facing breaking change and custom-marshaler implications require maintainer design approval.

Pull request overview

Fixes strict-provider schema rejection while preserving flexible script payloads.

Changes:

• Exposes script arguments as nullable JSON-encoded strings.
• Decodes encoded arguments once while retaining structured invocations.
• Adds schema, compatibility, marshaling, and error-policy tests.

File summaries

File	Description
AgentSkillsProvider.cs	Transforms the argument schema and decodes payloads.
AgentSkillsProviderTests.cs	Adds regression and compatibility coverage.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.