_dereference_schema fails with KeyError 'definitions' on JSON Schema draft-07 tools — violates MCP spec

[rrazvd]

🔴 Required Information

Describe the Bug:

When using McpToolset with an MCP server that returns tool inputSchema using JSON Schema draft-07 (i.e., definitions + $ref: "#/definitions/..." instead of $defs), the ADK crashes with KeyError: 'definitions'.

This is a spec-compliance bug: the MCP specification (2025-11-25), section 5.3.2 explicitly supports JSON Schema draft-07 in tool definitions — meaning any MCP server sending "$schema": "http://json-schema.org/draft-07/schema#" is fully spec-compliant and ADK must handle it.

This was previously reported in #3685 and closed as stale without a fix.

Steps to Reproduce:

1. Install google-adk (any recent version)
2. Connect McpToolset to any MCP server whose tools use draft-07 schemas with definitions (e.g., Apollo MCP Server)
3. Run the agent and send a message that triggers a call to one of those tools
4. Observe the crash with the stacktrace below

Expected Behavior:

ADK should handle both $defs (draft 2019+/2020-12) and definitions (draft-07) when dereferencing schemas, since both are valid per the MCP spec.

Observed Behavior:

File ".../google/adk/tools/mcp_tool/mcp_tool.py", line 119, in _get_declaration
    parameters = _to_gemini_schema(input_schema)
  File ".../google/adk/tools/_gemini_schema_util.py", line 207, in _to_gemini_schema
    return Schema.from_json_schema(
  File ".../google/genai/types.py", line 2720, in from_json_schema
    return convert_json_schema(...)
  File ".../google/genai/types.py", line 2492, in _resolve_ref
    current = current[part]
KeyError: 'definitions'

Root cause: _dereference_schema in _gemini_schema_util.py only reads $defs:

defs = schema.get("$defs", {})  # ignores `definitions` entirely

_sanitize_schema_formats_for_gemini then silently strips the definitions block, leaving dangling $ref pointers that crash Schema.from_json_schema.

Model Information:

• Are you using LiteLLM: No
• Which model is being used: gemini-2.5-flash

---

🟡 Optional Information

Regression:

Unknown — definitions support was likely never implemented, as the bug appears to be a missing code path rather than a regression.

Logs:

File ".../google/adk/flows/llm_flows/base_llm_flow.py", line 579, in _preprocess_async
    await tool.process_llm_request(
        tool_context=tool_context, llm_request=llm_request
    )
  File ".../google/adk/tools/base_tool.py", line 129, in process_llm_request
    llm_request.append_tools([self])
  File ".../google/adk/models/llm_request.py", line 255, in append_tools
    declaration = tool._get_declaration()
  File ".../google/adk/tools/mcp_tool/mcp_tool.py", line 119, in _get_declaration
    parameters = _to_gemini_schema(input_schema)
  File ".../google/adk/tools/_gemini_schema_util.py", line 207, in _to_gemini_schema
    return Schema.from_json_schema(
  File ".../google/genai/types.py", line 2492, in _resolve_ref
    current = current[part]
KeyError: 'definitions'

Additional Context:

The MCP spec section 5.3.2 explicitly provides a "Tool with explicit draft-07 schema" example, and states:

"Defaults to 2020-12 if no $schema field is present"

This means draft-07 is a first-class citizen of the spec. The previous issue #3685 was closed suggesting the problem was on the server side, but that is incorrect — the server is spec-compliant.

Proposed fix — a one-line change in _dereference_schema:

# Before
defs = schema.get("$defs", {})

# After
defs = schema.get("$defs") or schema.get("definitions") or {}

Minimal Reproduction Code:

from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.agents.llm_agent import LlmAgent

# Any MCP server that returns draft-07 schemas with `definitions`
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="http://your-draft07-mcp-server/mcp"
    )
)

agent = LlmAgent(
    model="gemini-2.5-flash",
    name="TestAgent",
    instruction="Use the available tools.",
    tools=[toolset]
)
# Invoking any tool from this server will crash with KeyError: 'definitions'

References:

• Closed issue (no fix applied): JSON Schema Compatibility Issue #3685
• MCP Spec — Tools, section 5.3.2: https://modelcontextprotocol.io/specification/2025-11-25/server/tools#schema-examples

How often has this issue occurred?

• Always (100%)

[rrazvd]

While waiting for an official fix, I'm working around this issue by monkey-patching _to_gemini_schema at application startup to normalize definitions → $defs before ADK processes the schema:

from google.adk.tools.mcp_tool import mcp_tool as _mcp_tool_module
from google.adk.tools import _gemini_schema_util as _gemini_schema_util_module

_original_to_gemini_schema = _gemini_schema_util_module._to_gemini_schema

def _normalize_schema_defs(schema):
    if isinstance(schema, dict):
        result = {k: _normalize_schema_defs(v) for k, v in schema.items()}
        if "definitions" in result and "$defs" not in result:
            result["$defs"] = result.pop("definitions")
        return result
    if isinstance(schema, list):
        return [_normalize_schema_defs(item) for item in schema]
    return schema

def _patched_to_gemini_schema(openapi_schema):
    return _original_to_gemini_schema(_normalize_schema_defs(openapi_schema))

_mcp_tool_module._to_gemini_schema = _patched_to_gemini_schema

This must be applied before any McpToolset or LlmAgent is instantiated. It works, but it's obviously fragile — it breaks if ADK refactors the internal module structure and shouldn't be necessary given the MCP spec explicitly supports draft-07.