Skip to content

fix(mcp): re-nest flattened arguments for Realtime tool calls#3390

Closed
adityasingh2400 wants to merge 1 commit into
openai:mainfrom
adityasingh2400:fix/realtime-mcp-nested-params
Closed

fix(mcp): re-nest flattened arguments for Realtime tool calls#3390
adityasingh2400 wants to merge 1 commit into
openai:mainfrom
adityasingh2400:fix/realtime-mcp-nested-params

Conversation

@adityasingh2400
Copy link
Copy Markdown
Contributor

When a RealtimeAgent calls an MCP tool whose input schema declares a nested-object property, the model frequently emits that property's fields at the top level rather than as a nested object, and the MCP server then rejects the call or silently misbehaves (#1681).

As noted in the earlier triage on the issue, this is because the OpenAI Realtime API's RealtimeFunctionTool type has no strict field — "the OpenAI Realtime API doesn't support the strict parameter for function tools" (comment). The schema travels intact but the model is free to ignore the nesting. That part has to be fixed upstream, but the SDK can still recover the common case before forwarding to the MCP server.

MCPUtil.invoke_mcp_tool now applies a narrow re-nesting pass after JSON parsing. When the parsed arguments contain keys not declared at the top level of tool.inputSchema and the schema has exactly one missing object-typed property that can unambiguously absorb them, the extras are moved into that property. Open-ended objects (no declared properties) are always eligible; typed objects are eligible only when every extra is a declared inner key; objects with additionalProperties: false and no inner properties are excluded. Ambiguous schemas (two or more candidate absorbers, or extras that don't match a closed inner schema) are left untouched so structured tools are not corrupted. On the SetProperties example from the issue, {\"target\": \"MyTarget\", \"visible\": false} is forwarded as {\"target\": \"MyTarget\", \"keysAndValues\": {\"visible\": false}} and the call succeeds. Five tests in tests/mcp/test_mcp_util.py cover the issue's case plus already-nested input, ambiguous siblings, closed inner schemas, and typed inner properties.

Refs #1681

The Realtime API has no `strict` field on RealtimeFunctionTool, so models
sometimes ignore an MCP tool's nested-object property and emit its inner
fields at the top level (openai#1681). When the schema has exactly one missing
object-typed property that can unambiguously absorb the extras, restore the
nesting before forwarding to the MCP server. Ambiguous or structurally
constrained schemas are left untouched.
@seratch
Copy link
Copy Markdown
Member

seratch commented May 13, 2026

Thanks for sharing this idea, but this could affect any MCP server use cases and I don't think it is a right solution for the realtime agents as well.

@seratch seratch closed this May 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants