feat(tools): prefer relative paths for tool parameters

[aishaneeshah]

Summary

Updates tool descriptions, TypeScript interfaces, and documentation to prefer relative paths (relative to workspace root) for all file and directory path parameters. This improves token efficiency, environment portability, and security.

Details

• Updated grep_search, glob, list_directory, read_file, write_file, and replace descriptions in gemini-3.ts to prefer relative paths.
• Updated run_shell_command dir_path description in dynamic-declaration-helpers.ts.
• Updated TypeScript interfaces LSToolParams and WriteFileToolParams to reflect path preference.
• Updated the system prompt in packages/core/src/agents/local-executor.ts to mandate relative paths for file operations.
• Updated docs/tools/file-system.md and docs/tools/shell.md documentation to reflect these preferences.
• Updated core tool snapshots to match revised descriptions.

Related Issues

Related to #19643

How to Validate

1. Run core tests: npx vitest run packages/core
2. Specifically verify snapshots: npx vitest run packages/core/src/tools/definitions/coreToolsModelSnapshots.test.ts
3. Verify specific tool tests: npx vitest run packages/core/src/tools/ls.test.ts packages/core/src/tools/write-file.test.ts

Pre-Merge Checklist

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

[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 refines the guidance for tool usage by promoting the preference for relative paths over absolute paths for file and directory operations. This change aims to improve portability and simplify interactions with the workspace, making the tools more intuitive and robust in different environments. The updates are primarily documentation-focused, clarifying expected input for various file system and shell-related tools, and adjusting an internal agent prompt to align with this new preference.

Highlights

• Documentation Updates: Updated documentation for various file system and shell tools to explicitly state a preference for relative paths (relative to the workspace root) for dir_path and file_path parameters.
• Agent Prompt Adjustment: Modified the LocalAgentExecutor's internal prompt to guide agents to 'Prefer relative paths' for file operations, shifting from a previous instruction to 'Always use absolute paths'.
• Tool Definition Consistency: Ensured consistency across tool definitions and their snapshots by updating parameter descriptions to reflect the preference for relative paths.

Changelog

• docs/tools/file-system.md
  • Updated dir_path description for list_directory to prefer relative paths.
  • Updated file_path description for read_file to prefer relative paths.
  • Updated file_path description for write_file to prefer relative paths.
  • Updated path parameter to dir_path and its description for find_files to prefer relative paths, and removed 'absolute paths' from the return description.
  • Updated path parameter to dir_path and its description for search_files to prefer relative paths.
  • Updated file_path description for replace to prefer relative paths.
• docs/tools/shell.md
  • Updated dir_path description for the shell tool to prefer relative paths and clarify usage.
• packages/core/src/agents/local-executor.ts
  • Modified the internal prompt to prefer relative paths for file operations instead of always using absolute paths.
• packages/core/src/tools/definitions/snapshots/coreToolsModelSnapshots.test.ts.snap
  • Updated dir_path description for the shell tool snapshot to prefer relative paths.
  • Updated dir_path description for the find_files tool snapshot to prefer relative paths.
  • Updated dir_path description for the search_files tool snapshot to prefer relative paths.
  • Updated dir_path description for the grep tool snapshot to prefer relative paths.
  • Updated dir_path description for the list_directory tool snapshot to prefer relative paths.
  • Updated file_path description for the read_file tool snapshot to prefer relative paths.
  • Updated file_path description for the replace tool snapshot to prefer relative paths.
  • Updated dir_path description for the shell tool snapshot to prefer relative paths.
  • Updated file_path description for the write_file tool snapshot to prefer relative paths.
• packages/core/src/tools/definitions/dynamic-declaration-helpers.ts
  • Updated dir_path description in the shell tool declaration to prefer relative paths.
• packages/core/src/tools/definitions/model-family-sets/gemini-3.ts
  • Updated file_path description for read_file in the Gemini-3 tool set to prefer relative paths.
  • Updated file_path description for write_file in the Gemini-3 tool set to prefer relative paths.
  • Updated dir_path description for search_files in the Gemini-3 tool set to prefer relative paths.
  • Updated dir_path description for grep in the Gemini-3 tool set to prefer relative paths.
  • Updated dir_path description for find_files in the Gemini-3 tool set to prefer relative paths.
  • Updated dir_path description for list_directory in the Gemini-3 tool set to prefer relative paths.
  • Updated file_path description for replace in the Gemini-3 tool set to prefer relative paths.
• packages/core/src/tools/ls.ts
  • Updated dir_path interface description to prefer relative paths.
• packages/core/src/tools/write-file.ts
  • Updated file_path interface description to prefer relative paths.

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 consistently updates tool descriptions, documentation, and agent prompts to prefer relative paths for file and directory parameters. The changes are well-aligned with the goals of improving token efficiency, portability, and security. The modifications have been applied across documentation files, TypeScript interfaces, tool definitions, and agent system prompts, ensuring a coherent change. The underlying tool implementations appear to correctly handle both relative and absolute paths by resolving them against the workspace root, so these changes should not introduce any regressions. The updated test snapshots confirm that the new descriptions are correctly generated. Overall, this is a solid and well-executed feature enhancement.

[github-actions]

Size Change: +318 B (0%)

Total Size: 25.7 MB

ℹ️ View Unchanged

Filename	Size	Change
./bundle/gemini.js	25.2 MB	+318 B (0%)
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B	0 B
./bundle/sandbox-macos-permissive-open.sb	890 B	0 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB	0 B
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB	0 B
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB	0 B
./bundle/sandbox-macos-strict-open.sb	4.82 kB	0 B
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB	0 B

_{compressed-size-action}