Python Google ADK has a bug while parsing JSON which has $defs and $ref

[subbuj9]

Hi ,

I am facing the issue when my MCP JSON data had $defs and $ref. Please find the below exception log and mcp json data.

Same payload is working fine with JAVA Google ADK, postman and other few agentic frameworks.

Issue log details:
2025-12-22 11:03:22,938 - INFO - envs.py:47 - Loaded .env file for my_agent at C:\D\SelfLearning\AI\adk_agent_java\my_agent.env
✓ MCP toolset initialized successfully
✓ Number of tools configured: 1

Agent initialization: tools=ENABLED
C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\adk\tools\mcp_tool\mcp_tool.py:88: UserWarning: [EXPERIMENTAL] BaseAuthenticatedTool: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
super().init(
2025-12-22 11:03:23,354 - INFO - types.py:2397 -
Note: Conversion of fields that are not included in the JSONSchema class are ignored.
Json Schema is now supported natively by both Vertex AI and Gemini API. Users
are recommended to pass/receive Json Schema directly to/from the API. For example:

1. the counter part of GenerateContentConfig.response_schema is
   GenerateContentConfig.response_json_schema, which accepts JSON
   Schema
2. the counter part of FunctionDeclaration.parameters is
   FunctionDeclaration.parameters_json_schema, which accepts JSON
   Schema
3. the counter part of FunctionDeclaration.response is
   FunctionDeclaration.response_json_schema, which accepts JSON
   Schema

2025-12-22 11:03:23,362 - ERROR - adk_web_server.py:1543 - Error in event_generator: 'NoneType' object is not subscriptable
Traceback (most recent call last):
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\adk\cli\adk_web_server.py", line 1533, in event_generator
async for event in agen:
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\adk\runners.py", line 506, in run_async
async for event in agen:
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\adk\runners.py", line 494, in _run_with_trace
async for event in agen:
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\adk\runners.py", line 723, in _exec_with_plugin
async for event in agen:
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\adk\runners.py", line 483, in execute
async for event in agen:
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\adk\agents\base_agent.py", line 294, in run_async
async for event in agen:
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\adk\agents\llm_agent.py", line 460, in _run_async_impl
async for event in agen:
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\adk\flows\llm_flows\base_llm_flow.py", line 370, in run_async
async for event in agen:
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\adk\flows\llm_flows\base_llm_flow.py", line 389, in _run_one_step_async
async for event in agen:
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\adk\flows\llm_flows\base_llm_flow.py", line 507, in _preprocess_async
await tool.process_llm_request(
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\adk\tools\base_tool.py", line 129, in process_llm_request
llm_request.append_tools([self])
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\adk\models\llm_request.py", line 255, in append_tools
declaration = tool._get_declaration()
^^^^^^^^^^^^^^^^^^^^^^^
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\adk\tools\mcp_tool\mcp_tool.py", line 119, in _get_declaration
parameters = _to_gemini_schema(input_schema)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\adk\tools_gemini_schema_util.py", line 236, in _to_gemini_schema
return Schema.from_json_schema(
^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\genai\types.py", line 2692, in from_json_schema
return convert_json_schema(
^^^^^^^^^^^^^^^^^^^^
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\genai\types.py", line 2639, in convert_json_schema
key: convert_json_schema(
^^^^^^^^^^^^^^^^^^^^
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\genai\types.py", line 2639, in convert_json_schema
key: convert_json_schema(
^^^^^^^^^^^^^^^^^^^^
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\genai\types.py", line 2617, in convert_json_schema
schema_field_value: 'Schema' = convert_json_schema(
^^^^^^^^^^^^^^^^^^^^
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\genai\types.py", line 2553, in convert_json_schema
json_schema_dict = _resolve_ref(
^^^^^^^^^^^^^
File "C:\D\SelfLearning\AI\adk_agent_java.venv\Lib\site-packages\google\genai\types.py", line 2464, in _resolve_ref
current = current[part]
~~~~~~~^^^^^^
TypeError: 'NoneType' object is not subscriptable

================================================
MCP JSON Payload:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": [
{
"name": "createSubscriber",
"description": "Creates a subscriber with specified properties including name, MDN, addList, and removeList.",
"inputSchema": {
"type": "object",
"properties": {
"subscriber": {
"$defs": {
"ListItem": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Item name"
},
"pkg": {
"type": "string",
"description": "Package identifier"
}
},
"required": [
"name",
"pkg"
]
}
},
"type": "object",
"properties": {
"addList": {
"description": "List of items to add",
"type": "array",
"items": {
"$ref": "#/$defs/ListItem"
}
},
"mdn": {
"type": "string",
"description": "Mobile Directory Number"
},
"name": {
"type": "string",
"description": "Subscriber name"
},
"removeList": {
"description": "List of items to remove",
"type": "array",
"items": {
"$ref": "#/$defs/ListItem"
}
}
},
"required": [
"addList",
"mdn",
"name",
"removeList"
]
}
},
"required": [
"subscriber"
],
"additionalProperties": false
}
}
]
}
}

[xuanyang15]

Could you please try enabling the JSON_SCHEMA_FOR_FUNC_DECL feature (by setting env variable ADK_ENABLE_JSON_SCHEMA_FOR_FUNC_DECL=1)? It is to deprecate the old _to_gemini_schema path and will use FunctionDeclaration.parameters_json_schema instead of FunctionDeclaration.parameters.

[wyf7107]

@wukath Seems like a minor change, could you take a look? Thanks!

[xuanyang15]

@wyf7107 @wukath If ADK_ENABLE_JSON_SCHEMA_FOR_FUNC_DECL works, we don't need additional code changes. We plan to roll out JSON_SCHEMA_FOR_FUNC_DECL (i.e. enabling it by default) in Jan.