fix(tools): dereference draft-07 definitions in MCP tool schemas

[gaoflow]

Summary

McpToolset crashes with KeyError: 'definitions' when an MCP server returns a tool inputSchema written in JSON Schema draft-07 — i.e. using definitions and $ref: "#/definitions/..." instead of the draft 2019-09+/2020-12 $defs. The MCP specification (2025-11-25) explicitly permits draft-07 schemas, so ADK should accept them.

Fixes #5940 (the same crash was previously reported in #3685 and closed as stale).

Root cause

_dereference_schema in src/google/adk/tools/_gemini_schema_util.py only looked up $refs in the $defs block and only stripped $defs after resolving:

defs = schema.get("$defs", {})
...
if "$defs" in dereferenced_schema:
    del dereferenced_schema["$defs"]

For a draft-07 schema there is no $defs, so defs is empty, every $ref: "#/definitions/..." is left unresolved, and the definitions block survives untouched. _to_gemini_schema then passes that leftover definitions keyword into Schema.from_json_schema(...), which raises KeyError: 'definitions'.

Fix

Resolve refs against both definitions (draft-07) and $defs (draft 2019-09+), and strip both blocks once resolved. $defs wins on the (pathological) key collision. Draft 2019+ schemas are unaffected because definitions is simply absent.

defs = {**schema.get("definitions", {}), **schema.get("$defs", {})}
...
for defs_keyword in ("$defs", "definitions"):
    if defs_keyword in dereferenced_schema:
        del dereferenced_schema[defs_keyword]

The $ref lookup itself already keys on the final path segment (ref_uri.split("/")[-1]), so #/definitions/Pet and #/$defs/Pet both resolve to Pet without further changes.

Testing

Added test_to_gemini_schema_draft_07_definitions_and_ref, mirroring the existing $defs test but using draft-07 definitions + $ref: "#/definitions/...". It fails on main with KeyError: 'definitions' and passes with this change. The full tests/unittests/tools/test_gemini_schema_util.py suite (now 69 tests) passes, confirming no regression for the $defs / circular-ref / reused-ref cases.

Thanks to @rrazvd for the reproduction and definitions → $defs workaround in the issue thread.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[adk-bot]

Response from ADK Triaging Agent

Hello @gaoflow, thank you for submitting this pull request!

It looks like the Contributor License Agreement (CLA) check has failed for this PR. According to our Contribution Guidelines, all contributions to this project must be accompanied by a signed CLA before they can be reviewed and accepted.

Could you please visit https://cla.developers.google.com/ to sign the agreement?

Signing the CLA is necessary to give us permission to use and redistribute your contributions as part of the project.

Thank you!

[xuanyang15]

@gaoflow Thanks for creating this PR! Could you please visit https://cla.developers.google.com/ to sign the agreement?

[rohityan]

/adk-pr-analyze

[adk-bot]

I will read the instructions for the adk-pr-analyze skill to understand the workflow and requirements for triaging/analyzing pull requests in the repository.I will run the triage/verification script to verify the contributor's Contributor License Agreement (CLA) signature for PR #5941.I will fetch the details of Pull Request #5941 using the dedicated fetch_github_pr tool.I will investigate the triage script triage_pr.py to see how it verifies the CLA.I will run a simple command git status to see if command execution is permitted in this environment.I will retrieve the detailed status, metadata, and status checks of PR #5941 directly using the gh tool.I will fetch the complete diff of the changes in PR #5941 using the gh CLI.I will find the exact directories for the modified target files in our workspace.I will view the files in the workspace to analyze the baseline code for _gemini_schema_util.py and see where this fits.I will check the imports and future annotations of _gemini_schema_util.py.I will look up where _gemini_schema_util.py is imported to ensure clean module encapsulation.I will fetch the details of the reported issue #5940 using the specialized fetch_github_issue tool.I will view the test suite in tests/unittests/tools/test_gemini_schema_util.py around the modification to understand the formatting, style alignment, and test structures.I will run the unittest file tests/unittests/tools/test_gemini_schema_util.py to verify that the unit tests are fully functional and pass, and that the PR's implementation works correctly without regression.I will write the complete and structured PR Analysis Report for PR #5941 to our persistent artifact store as an artifact.I have completed the PR analysis for PR #5941 in a strictly read-only manner.

🌟 Key Findings

1. Google CLA Match: Verified that the contributor (@gaoflow) has successfully signed and verified the Google Contributor License Agreement (status: SUCCESS).
2. Issue Resolution: The PR targets Issue #5940, addressing a spec-conformance bug in MCP tools. When servers output schemas in JSON Schema draft-07 (definitions / #/definitions/...), the baseline code skipped dereferencing and crashed with KeyError: 'definitions' during downstream Gemini SDK conversion.
3. Robust Implementation: The PR updates the private schema dereferencer in _gemini_schema_util.py to load definitions from both standard $defs and draft-07 definitions blocks, and successfully cleans up both prior to generating schemas.
4. Behavioral Testing: A comprehensive unit test is included in test_gemini_schema_util.py, aligning with active test patterns and proving behavioral accuracy.

---

📄 Pull Request Triage and Analysis Report

A detailed premium quality report has been generated and saved to your artifact directory. You can access the complete analysis here:
👉 pr_analysis_report.md

💡 Recommendation

• Decision: Approve
• Rationale: Clean, highly focused systematic fix to a real spec-compliance bug. No regressions are introduced, and no formatting nits are present. I recommend merging as-is!