Description

The OpenAI Realtime API flattens tool arguments incorrectly, ignoring the provided JSON schema for nested objects. This causes tool calls to fail because the arguments don't match the expected structure.

When using MCP tools with nested object parameters through the OpenAI Realtime API, the LLM ignores the schema structure and flattens arguments that should be nested within object properties.

Expected Behavior

Given the schema for SetProperties:

{
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "description": "The name of the target on which we will set the properties."
    },
    "keysAndValues": {
      "type": "object",
      "description": "The properties keys and their values to change, formatted as json key/value pairs"
    }
  },
  "required": ["target", "keysAndValues"]
}

The LLM should call the tool with properly nested arguments:

{
  "target": "MyTarget",
  "keysAndValues": {
    "visible": false
  }
}

Actual Behavior

The LLM flattens the arguments incorrectly:

{
  "target": "MyTarget",
  "visible": false
}

Investigation Results

Investigation revealed:

1. Schema Definition is Correct: The MCP server correctly defines and serves the schema with proper nested structure
2. Schema Conversion is Working: Debug logs confirm the schema is properly converted from MCP format to OpenAI function tool format with strict mode enabled
3. Schema Transmission is Successful: The final schema sent to the LLM includes the correct keysAndValues object structure
4. LLM is Ignoring Schema: Despite receiving the correct schema, the LLM flattens arguments instead of following the nested structure

Debug Evidence

Added debug logging to agents/mcp/util.py in the to_function_tool() and invoke_mcp_tool() methods:

[SCHEMA DEBUG] Final schema for tool 'SetProperties' being sent to LLM:
  params_json_schema: {
    "type": "object",
    "properties": {
      "target": {
        "type": "string",
        "description": "The name of the target..."
      },
      "keysAndValues": {
        "type": "object",
        "description": "The properties keys and their values...",
        "additionalProperties": false
      }
    },
    "required": ["target", "keysAndValues"],
    "additionalProperties": false
  }
  strict_json_schema: True

This confirms the schema is correctly structured and sent with strict mode enabled.

Debug information

• Agents SDK version: v0.2.9
• Python version: 3.11