[BUG] McpToolFilter.Serialization.cs does not deserialize MCP tool allowed_tools of type array

[sakoll]

Describe the bug

Based on OpenAI API Reference for Responses API here, the allowed_tools can be an array or object. However the SDK is not deserializing array type and ending up with this error

System.InvalidOperationException: The requested operation requires an element of type 'Object', but the target element has type 'Array'.
at System.Text.Json.ThrowHelper.ThrowJsonElementWrongTypeException(JsonTokenType expectedType, JsonTokenType actualType)
at System.Text.Json.JsonElement.EnumerateObject()
at OpenAI.Responses.McpToolFilter.DeserializeMcpToolFilter(JsonElement element, ModelReaderWriterOptions options)
at OpenAI.Responses.McpTool.DeserializeMcpTool(JsonElement element, ModelReaderWriterOptions options)
at OpenAI.Responses.ResponseTool.DeserializeResponseTool(JsonElement element, ModelReaderWriterOptions options)
at OpenAI.Responses.InternalUnknownTool.PersistableModelCreateCore(BinaryData data, ModelReaderWriterOptions options)
at OpenAI.Responses.InternalUnknownTool.System.ClientModel.Primitives.IPersistableModel<OpenAI.Responses.ResponseTool>.Create(BinaryData data, ModelReaderWriterOptions options)

Steps to reproduce

As described in description, create a model response with MCP tool allowed_tools of array type and use SDK to retrieve it

Code snippets

OS

Windows

.NET version

8

Library version

2.5

[joseharriaga]

Thank you for reaching out, @sakoll ! The allowed_tools property is a union between an object and array of strings:

Because the object representation is a superset of the array of strings, in the .NET library we converged to using the object representation. From my own testing, if you create a Response using the object representation, then when you retrieve that Response, you will get back the same object representation. However, if you're seeing an array of strings, I can think of two possible reasons:

1. You're using a different service (e.g., Azure OpenAI), and maybe that service is exhibiting different behavior.
2. You're retrieving a Response that was created by means other than the .NET library (e.g., using the Python library or the direct REST API) and it was creating with an array of strings.

Could you corroborate for us which one of these apply to your case? Or please let us know if there is another reason I haven't considered.

CC @christothes , @KrzysztofCwalina , @jsquire : With our introduction of protocol models, I'm getting the feeling that it might not be appropriate anymore for us to continue applying the design pattern of converging unions into the superset component where possible. In other words, I'm thinking we might have to preserve all unions.

[sakoll]

@joseharriaga, we are experiencing this issue with Azure OpenAI (case 1)

[jsquire]

Hi @sakoll. Thank you for the additional context. Please be aware that Azure OpenAI is a separate product and not something that the maintainers of the OpenAI library can offer support for.

Unfortunately, because this is a service-related behavior we are unable to transfer this on your behalf. The Azure service teams do not monitor issues here, nor do they offer support from the Azure GitHub repositories. To ensure that the right team has visibility and can help, your best path forward for would be to open an Azure support request or inquire on the Microsoft Q&A site.

[sakoll]

Hi @jsquire, I still think that this a SDK bug as it is not aligned with API spec irrespective of what service we use underneath

[jsquire]

@sakoll: Thank you for your feedback and the continued discussion. As Jose indicated, in this scenario, the OpenAI service behavior has an invariant where the format of the tools in the response will always match the format that was used in the request. While you're correct in that the spec is loosely defined and does not have a way to communicate that constraint, it is part of the OpenAI service contract.

Azure OpenAI appears to not be following this, which is the source of the failure. Please be aware that the goal of this project is to support the OpenAI service. While we do not intentionally block client use with other services/LLMs, we also do not add implementations specific to non-OpenAI operations, nor do we offer support for other services or models.

As a result, we will take the discrepancy into account and discuss whether or not revising the client expectation makes sense but cannot commit to changes. Your best path forward is to let the Azure AI service folks know so that they can adjust. In the meantime, using the protocol overloads would allow you work around the issue on the client side.