fix(core): strip $schema from MCP tool parameters for API compatibility

[achaljhawar]

Summary

This PR fixes an issue where MCP tools using Draft 2020-12 JSON schemas (containing the $schema property) caused intermittent failures in the Gemini CLI. It ensures compatibility with the Gemini API's strict function declaration requirements while preserving full local validation support.

Details

• API Compatibility: Strips the $schema property from parametersJsonSchema in DiscoveredMCPTool.getSchema(). This prevents the Gemini model from receiving the metadata keyword, which it often rejects or handles inconsistently.
• Local Validation Integrity: Overrides validateToolParams to use the original parameterSchema (with $schema intact). This allows SchemaValidator to correctly identify the schema as Draft 2020-12 and use the appropriate ajv2020 validator.
• Architectural Alignment: Follows the BaseDeclarativeTool pattern by ensuring local validation still checks for custom parameter values.

Related Issues

Fixes #17235

How to Validate

1. Unit Tests: Run the updated MCP tool tests: npm test -w @google/gemini-cli-core --src/tools/mcp-tool.test.ts
2. Manual Verification (with a Draft 2020-12 MCP Server):
   • Connect an MCP server that provides a tool with $schema: "https://json-schema.org/draft/2020-12/schema" in its definition.
   • Verify the tool can be called without receiving the "no schema with key or ref" error.
   • Verify that invalid parameters still trigger a local validation error.

Pre-Merge Checklist

• Updated relevant documentation and README (N/A)
• Added/updated tests (if needed)
• Noted breaking changes (none)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses an issue where MCP tools utilizing Draft 2020-12 JSON schemas caused intermittent failures in the Gemini CLI due to the "$schema" property. The changes ensure seamless integration with the Gemini API by removing the "$schema" keyword from the schema presented to the API, while simultaneously preserving full local validation capabilities for tool parameters.

Highlights

• API Compatibility: Ensured Gemini API compatibility by stripping the "$schema" property from "parametersJsonSchema" when retrieving a tool's schema.
• Local Validation: Maintained robust local validation by overriding "validateToolParams" to use the original "parameterSchema", allowing "SchemaValidator" to correctly interpret Draft 2020-12 schemas.
• Architectural Alignment: Aligned with "BaseDeclarativeTool" patterns by ensuring local validation checks for custom parameter values.

Changelog

• packages/core/src/tools/mcp-tool.test.ts
  • Added new test cases for the "getSchema" method to verify that the "$schema" property is correctly stripped from "parametersJsonSchema" for API compatibility.
  • Included a test to confirm that schemas without a "$schema" property are not modified.
• packages/core/src/tools/mcp-tool.ts
  • Imported "SchemaValidator" for enhanced schema validation.
  • Imported "FunctionDeclaration" type for improved type safety.
  • Overrode the "getSchema" method to remove the "$schema" property from the "parametersJsonSchema" when it is present, ensuring API compatibility.
  • Overrode the "validateToolParams" method to use "SchemaValidator" with the original "parameterSchema" for comprehensive local validation.

Activity

• Unit tests were updated and run, specifically for "mcp-tool.test.ts".
• Manual verification was performed with a Draft 2020-12 MCP Server to confirm tool call success and correct invalid parameter handling.
• The pre-merge checklist was completed, confirming documentation is not applicable, tests were added/updated, no breaking changes were introduced, and validation was performed on MacOS (npm run).

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request correctly addresses an API compatibility issue with MCP tools that use JSON Schema Draft 2020-12. The $schema property is stripped from the tool parameters sent to the Gemini API to prevent rejections. The implementation cleverly overrides getSchema for API compatibility while also overriding validateToolParams to use the original, un-stripped schema for local validation. This ensures that the correct schema validator version is used locally. The changes are well-reasoned, targeted, and accompanied by thorough unit tests. The implementation looks solid.

[achaljhawar]

/gemini review

[gemini-code-assist]

Code Review

This pull request correctly addresses an API compatibility issue by stripping the $schema property from MCP tool schemas before sending them to the Gemini API, while preserving it for local validation. The approach of overriding getSchema and validateToolParams is sound. However, I've found a critical regression in the getSchema override that causes the important wait_for_previous parameter to be dropped. My review includes a suggested fix for this issue.

[achaljhawar]

/gemini review

[gemini-code-assist]

Code Review

This pull request effectively addresses API incompatibility with MCP tools by stripping the $schema property before sending it to the Gemini API, ensuring local validation remains functional. A security review found no vulnerabilities, and the changes are well-structured, maintaining existing architectural patterns.

[achaljhawar]

cc @galz10 (tagging for better visibility)

[gemini-cli]

Hi there! Thank you for your interest in contributing to Gemini CLI.

To ensure we maintain high code quality and focus on our prioritized roadmap, we have updated our contribution policy (see Discussion #17383).

We only guarantee review and consideration of pull requests for issues that are explicitly labeled as 'help wanted'. All other community pull requests are subject to closure after 14 days if they do not align with our current focus areas. For this reason, we strongly recommend that contributors only submit pull requests against issues explicitly labeled as 'help-wanted'.

This pull request is being closed as it has been open for 14 days without a 'help wanted' designation. We encourage you to find and contribute to existing 'help wanted' issues in our backlog! Thank you for your understanding and for being part of our community!

[cocosheng-g]

@achaljhawar, apologies for the bot closing this PR! We have reopened it. Please sync your branch to the latest main and we will have someone review it shortly.

[achaljhawar]

@cocosheng-g I have resolved the merge conflicts

[cocosheng-g]

/gemini review

[gemini-code-assist]

Code Review

This pull request updates the DiscoveredMCPTool class to improve API compatibility and parameter validation. The getSchema method now strips the $schema property from the tool's parameter schema to ensure compatibility with the Gemini API. Additionally, validateToolParams has been overridden to correctly handle the internal wait_for_previous parameter during validation. New unit tests have been added to verify these changes. I have no feedback to provide.

[github-actions]

✅ 64 tests passed successfully on gemini-3-flash-preview.

🧠 Model Steering Guidance

This PR modifies files that affect the model's behavior (prompts, tools, or instructions).

• ⚠️ Consider adding Evals: No behavioral evaluations (evals/*.eval.ts) were added or updated in this PR. Consider adding a test case to verify the new behavior and prevent regressions.

---

This is an automated guidance message triggered by steering logic signatures.

[github-actions]

🛑 Action Required: Evaluation Approval

Steering changes have been detected in this PR. To prevent regressions, a maintainer must approve the evaluation run before this PR can be merged.

Maintainers:

1. Go to the Workflow Run Summary.
2. Click the yellow 'Review deployments' button.
3. Select the 'eval-gate' environment and click 'Approve'.

Once approved, the evaluation results will be posted here automatically.