Responses API migration pain: RESPONSES_TOOLS can ignore structured text format and return empty `{}` tool args

[davidsmv]

• This is actually a bug report.
• [ x] I am not getting good LLM Results
• I have tried asking for help in the community on discord or discussions and have not received a response.
• I have tried searching the documentation and have not found an answer.

What Model are you using?

• [ x] gpt-5-nano

Description
Hi Instructor team, thanks for the great library.
OpenAI is recommending migration from Chat Completions to the Responses API (https://developers.openai.com/api/docs/guides/migrate-to-responses) , so we moved our production pipeline accordingly. During that migration, we found a reliability issue in RESPONSES_TOOLS mode.

Environment:

• instructor==1.14.4
• OpenAI Python SDK 1.x
• Azure OpenAI
• Python 3.11
• Model: gpt-5-nano

Context:

• With Chat Completions + Instructor, our Pydantic extraction flow was stable.
• We migrated because OpenAI guidance suggests using Responses API going forward.
• In Responses API mode, we now see intermittent empty tool arguments ({}), which causes validation failures.

What we are sending:

• mode=instructor.Mode.RESPONSES_TOOLS
• response_model=ResponseModel (Pydantic)
• text.format set to json_schema (strict true/false depending on schema compatibility)

Observed behavior:

• Response includes both:
    - forced function tool call for ResponseModel
    - text config present
• But generation often returns tool call arguments='{}'
• Instructor then fails Pydantic validation (required fields missing)
• This appears more often when reasoning tokens are low

Representative failure:

• ResponseFunctionToolCall(arguments='{}', name='ResponseModel', ...)
• Validation error similar to:
    - 1 validation error for ResponseModel
    - required top-level field missing (example: data)

Expected behavior:

• If text.format is provided, either:
    1. it is honored consistently, or
    2. Instructor rejects this combination with a clear error/warning.
• In RESPONSES_TOOLS, required schema fields should not degrade into empty {} tool args.
• Migration path from Chat Completions to Responses should preserve structured extraction reliability.

Why this matters:

• OpenAI recommends Responses API over Chat Completions, but current behavior makes migration risky for schema-driven extraction pipelines.
• We can’t reliably depend on required structured output if tool args can collapse to {}.
• The constan retries make the requests too expensive.

Request / possible improvements:

1. Add a Responses mode that uses text.format as the primary structured output path (no forced function call).
2. In RESPONSES_TOOLS, harden schema/tool argument enforcement to prevent empty {} when required fields exist.
3. Add explicit conflict handling for text.format + RESPONSES_TOOLS (document precedence and/or fail fast).
4. Add retry heuristic for empty tool args when response_model has required fields.

[ayushh0110]

Traced through the current main branch. The bug spans 3 functions in 2 files — no cross-provider impact.

1. No text config conflict detection in handle_responses_tools

utils.py#L348-393 — Sets up tools + forced tool_choice but never inspects user-provided text config. When both a forced tool call and text.format=json_schema reach the API, they create competing output paths — the model may satisfy the text format and deprioritize tool args to {}. This aligns with the reporter's observation that it worsens with lower reasoning token budgets.

2. Generic retry message doesn't help recovery

utils.py#L106-148 — The retry prompt includes the raw empty args: "fix the errors with {}". The model doesn't understand why {} was wrong, so it often repeats the same mistake across all retries.

3. No early warning for empty args in parse_responses_tools

function_calls.py#L700-726 — When arguments='{}', pydantic's ValidationError correctly triggers a retry, but there's no log output to help users diagnose the root cause (the text config conflict).

Scope & Proposed Fix

File	Function	Fix
providers/openai/utils.py	handle_responses_tools	Strip text config with json_schema format when alongside forced tool calls; emit warning
providers/openai/utils.py	reask_responses_tools	Detect empty {} args; use targeted retry: "Tool called with empty arguments — populate all required fields"
processing/function_calls.py	parse_responses_tools	Add logger.warning for empty args to help diagnosis; existing pydantic ValidationError already handles retry flow correctly

Re: request #1 (new Responses mode using text.format as primary output path without forced tool calls) — that would be a separate feature/mode addition. The fix above addresses requests #2-#4 from the issue.

opening a PR if this direction.

[davidsmv]

@ayushh0110 But is the idea to include the "text" argument in the API call? This would prevent errors in the outputs for low-reasoning models, which is the main issue. I will share the guide with you: https://developers.openai.com/api/docs/guides/migrate-to-responses?structured-outputs=responses#6-update-structured-outputs-definition

[ayushh0110]

thanks @davidsmv
instead of stripping text.format when it conflicts with forced tool calls, the fix will include text.format set to a json_schema matching the tool schema. This aligns both output paths so the model gets a single consistent schema signal, which should eliminate the {} args issue on low-reasoning models.

Per the migration guide §6, text.format is the Responses API equivalent of response_format. Setting it alongside the tool definition reinforces the structured output constraint.

I'll include:

• A targeted retry message in reask_responses_tools for the empty-args case (so the model knows why {} was wrong)
• Diagnostic logging in parse_responses_tools when empty args are detected

[ayushh0110]

Opened a PR for this: #2304

The fix aligns text.format with the tool schema so both output paths use the same json_schema, giving the model a single consistent signal. This follows the Responses API migration guide §6 where text.format is the equivalent of response_format for structured outputs.

Also included:

• Targeted retry message when empty {} args are detected (instead of the generic "fix the errors with {}")
• Diagnostic WARNING log when parse_responses_tools encounters empty arguments

Would appreciate a review