Gemini API rejects JSON Schema containing $ref references

[high726]

Problem

Gemini API rejects schemas containing $ref alongside other fields, causing errors like:

$ref 'QuestionOption' was set alongside unsupported fields. 
If a schema node has $ref set, then only description and default can be set alongside it

This happens when MCP tools use JSON Schema with $ref references to $defs/definitions.

Expected Behavior

OpenCode should expand $ref references before sending schemas to Gemini API.

Related Issues

• Gemini API rejects MCP tool schemas with $defs references google-gemini/gemini-cli#13326 - Gemini API rejects MCP tool schemas with $defs references
• Error with Gemini models when MCP enabled #5832 - Error with Gemini models when MCP enabled
• Gemini Bad Request with Github Copilot #8417 - Gemini Bad Request with Github Copilot

Related PRs

• fix: apply schema transformation to MCP tools for Gemini compatibility #11968 - Applies schema transformation to MCP tools (complementary fix)

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Error with Gemini models when MCP enabled #5832: Error with Gemini models when MCP enabled
• Gemini Bad Request with Github Copilot #8417: Gemini Bad Request with Github Copilot (MCP tools fail with Gemini)
• [BUG] Schema.ref 'QuestionInfo' was set alongside unsupported fields in v1.1.x #7791: Schema.ref 'QuestionInfo' was set alongside unsupported fields (almost identical error message)
• "question" tool schema causes "400 Bad Request" with Gemini/Vertex AI` #11413: "question" tool schema causes "400 Bad Request" with Gemini/Vertex AI

Additionally, #11968 is a related PR that applies schema transformation to MCP tools - you may want to verify if extending that fix to handle $ref expansion would solve this issue.

Feel free to ignore if none of these address your specific case.

[github-actions]

To stay organized issues are automatically closed after 90 days of no activity. If the issue is still relevant please open a new one.