refactor(core): modularize tool definitions by model family

[aishaneeshah]

Summary

Modularizes core tool definitions to support model-family specific optimizations (e.g., Gemini 3 vs Legacy). This refactor moves from a "base + override" model to a "discrete set" model, ensuring that model capabilities are intentionally managed.

Details

• Model Family Mapping: Centralized in ModelFamilyService.ts to map model IDs to families (Legacy, Gemini 3).
• Explicit Manifests: Created default-legacy.ts and gemini-3.ts which contain the full description and schema for every core tool.
• Architectural Separation: Organized into base-declarations (Identity registry) and dynamic-declaration-helpers (Logic) to prevent circular dependencies.
• Improved Readability: Tool descriptions and schemas are inlined in the family set files, allowing developers to see the exact interface a model "sees" in one place.
• Parity Verified: Strict functional parity confirmed via snapshots and 700+ tool unit tests.

Related Issues

Fixes #17958

How to Validate

1. Run snapshot tests:

   npm test -w @google/gemini-cli-core -- src/tools/definitions/coreToolsModelSnapshots.test.ts

2. Run tool unit tests:

   npm test -w @google/gemini-cli-core -- src/tools/

3. Verify build and typecheck pass:

   npm run build

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any) - No breaking changes.
• Validated on required platforms/methods:
  • MacOS
  • Windows
  • Linux
    • npm run

[gemini-cli]

Hi there! Thank you for your contribution to Gemini CLI.

To improve our contribution process and better track changes, we now require all pull requests to be associated with an existing issue, as announced in our recent discussion and as detailed in our CONTRIBUTING.md.

This pull request is being closed because it is not currently linked to an issue. Once you have updated the description of this PR to link an issue (e.g., by adding Fixes #123 or Related to #123), it will be automatically reopened.

How to link an issue:
Add a keyword followed by the issue number (e.g., Fixes #123) in the description of your pull request. For more details on supported keywords and how linking works, please refer to the GitHub Documentation on linking pull requests to issues.

Thank you for your understanding and for being a part of our community!

[gemini-cli]

Hi @aishaneeshah, thank you so much for your contribution to Gemini CLI! We really appreciate the time and effort you've put into this.

We're making some updates to our contribution process to improve how we track and review changes. Please take a moment to review our recent discussion post: Improving Our Contribution Process & Introducing New Guidelines.

Key Update: Starting January 26, 2026, the Gemini CLI project will require all pull requests to be associated with an existing issue. Any pull requests not linked to an issue by that date will be automatically closed.

Thank you for your understanding and for being a part of our community!

[gemini-code-assist]

Summary of Changes

Hello @aishaneeshah, 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 significantly refactors how core tool definitions are managed, transitioning to a modular system that supports model-family specific optimizations. The change enables more precise control over tool capabilities for different models, such as Gemini 3, by providing distinct, explicit toolsets rather than relying on a base-and-override mechanism. This architectural improvement enhances maintainability, readability, and future extensibility of the tool definitions.

Highlights

• Modularized Tool Definitions: Core tool definitions are now organized by model family, moving from a "base + override" approach to a "discrete set" model for managing tool capabilities.
• Model Family Mapping: A new ModelFamilyService.ts was introduced to centralize the mapping of model IDs to specific tool families, such as Legacy and Gemini 3.
• Explicit Tool Manifests: Dedicated files (default-legacy.ts, gemini-3.ts) were created to contain the full descriptions and schemas for each core tool within their respective model families.
• Architectural Separation: Logic for dynamic tool declarations was separated into dynamic-declaration-helpers.ts to prevent circular dependencies and improve code organization.
• Improved Readability: Tool descriptions and schemas are now inlined within the family set files, providing a clearer view of the exact interface a model "sees" in one place.
• Functional Parity Verified: Strict functional parity of the tool definitions was confirmed through comprehensive snapshot tests and over 700 tool unit tests.

Changelog

• packages/core/src/tools/definitions/base-declarations.ts
  • Added a new file to define constant names for all core tools, serving as an identity registry.
• packages/core/src/tools/definitions/coreTools.ts
  • Refactored the file to orchestrate tool definitions, importing tool names from base-declarations.ts, tool sets from model-family-specific files, and using ModelFamilyService for resolution.
• packages/core/src/tools/definitions/dynamic-declaration-helpers.ts
  • Added a new file to encapsulate reusable logic for generating runtime-dependent tool declarations.
• packages/core/src/tools/definitions/model-family-sets/default-legacy.ts
  • Added a new file to define the complete set of tool declarations for legacy models.
• packages/core/src/tools/definitions/model-family-sets/gemini-3.ts
  • Added a new file to define the complete set of tool declarations for Gemini 3 models.
• packages/core/src/tools/definitions/modelFamilyService.ts
  • Added a new file to provide a centralized service for mapping model IDs to tool families.
• packages/core/src/tools/definitions/types.ts
  • Updated the file to introduce ToolFamily type and CoreToolSet interface for explicit tool mappings.

Activity

• The author confirmed that relevant documentation and READMEs were updated if needed.
• The author confirmed that tests were added/updated if needed.
• The author confirmed that there are no breaking changes.
• The author validated the changes on Linux using npm run.
• Snapshot tests (npm test -w @google/gemini-cli-core -- src/tools/definitions/coreToolsModelSnapshots.test.ts) were run.
• Tool unit tests (npm test -w @google/gemini-cli-core -- src/tools/) were run.
• Build and typecheck (npm run build) passed.

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 introduces a significant and well-executed refactoring of the core tool definitions. By modularizing the definitions into discrete sets for different model families (default-legacy and gemini-3), the changes greatly improve the structure and prepare the codebase for future model-specific optimizations. The introduction of base-declarations.ts for tool names, dynamic-declaration-helpers.ts for state-dependent logic, and modelFamilyService.ts for resolving tool families creates a clean and maintainable architecture. The legacy exports in coreTools.ts provide a solid backward-compatibility layer. The code is consistent, and the new structure is explicit, which will make it easier to manage and audit tool capabilities for different models. I did not find any issues of high or critical severity.

[gemini-cli]

Thank you for linking an issue! This pull request has been automatically reopened.

[github-actions]

Size Change: +36.7 kB (+0.15%)

Total Size: 24.5 MB

Filename	Size	Change
./bundle/gemini.js	24.5 MB	+36.7 kB (+0.15%)

ℹ️ View Unchanged

Filename	Size
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB
./bundle/sandbox-macos-strict-open.sb	4.82 kB
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB

_{compressed-size-action}

[gundermanc]

nit: 2026

[gundermanc]

file name nit: consider naming the file based on its content. e.g.: "tool-descriptions.ts"

[gundermanc]

2026

[gundermanc]

filename nit: can we name the file based on content? Maybe gemini-3-tool-schemas.ts?