fix: Push tool calls to absolute paths (#1055) (#1057)

Make several changes to guide the model to request absolute paths,
reducing frequent accidental relative path tool call failures.

- Switch the parameter name: path --> absolute_path.
- Update the tool definition to strongly require an absolute path.
- Update the system prompt to indicate absolute paths are required.
- Update the system prompt tool use examples to use absolute paths.

Test case:

Open GC in GC: "Locate the primary file calling genai"
- Expected: Model opens files with absolute path, successfully.
- Actual (pre-patch): Failure, attempts to read with relative path.
- Actual (post-patch): Success, attempts to read with absolute path.

2 files changed, 31 insertions, 27 deletions

diff --git a/packages/core/src/tools/read-file.test.ts b/packages/core/src/tools/read-file.test.ts
index 987b451c..bfb08a6c 100644
--- a/packages/core/src/tools/read-file.test.ts
+++ b/packages/core/src/tools/read-file.test.ts
@@ -57,14 +57,14 @@ describe('ReadFileTool', () => {
   describe('validateToolParams', () => {
     it('should return null for valid params (absolute path within root)', () => {
       const params: ReadFileToolParams = {
-        path: path.join(tempRootDir, 'test.txt'),
+        absolute_path: path.join(tempRootDir, 'test.txt'),
       };
       expect(tool.validateToolParams(params)).toBeNull();
     });
 
     it('should return null for valid params with offset and limit', () => {
       const params: ReadFileToolParams = {
-        path: path.join(tempRootDir, 'test.txt'),
+        absolute_path: path.join(tempRootDir, 'test.txt'),
         offset: 0,
         limit: 10,
       };
@@ -72,7 +72,7 @@ describe('ReadFileTool', () => {
     });
 
     it('should return error for relative path', () => {
-      const params: ReadFileToolParams = { path: 'test.txt' };
+      const params: ReadFileToolParams = { absolute_path: 'test.txt' };
       expect(tool.validateToolParams(params)).toMatch(
         /File path must be absolute/,
       );
@@ -80,7 +80,7 @@ describe('ReadFileTool', () => {
 
     it('should return error for path outside root', () => {
       const outsidePath = path.resolve(os.tmpdir(), 'outside-root.txt');
-      const params: ReadFileToolParams = { path: outsidePath };
+      const params: ReadFileToolParams = { absolute_path: outsidePath };
       expect(tool.validateToolParams(params)).toMatch(
         /File path must be within the root directory/,
       );
@@ -88,7 +88,7 @@ describe('ReadFileTool', () => {
 
     it('should return error for negative offset', () => {
       const params: ReadFileToolParams = {
-        path: path.join(tempRootDir, 'test.txt'),
+        absolute_path: path.join(tempRootDir, 'test.txt'),
         offset: -1,
         limit: 10,
       };
@@ -99,7 +99,7 @@ describe('ReadFileTool', () => {
 
     it('should return error for non-positive limit', () => {
       const paramsZero: ReadFileToolParams = {
-        path: path.join(tempRootDir, 'test.txt'),
+        absolute_path: path.join(tempRootDir, 'test.txt'),
         offset: 0,
         limit: 0,
       };
@@ -107,7 +107,7 @@ describe('ReadFileTool', () => {
         'Limit must be a positive number',
       );
       const paramsNegative: ReadFileToolParams = {
-        path: path.join(tempRootDir, 'test.txt'),
+        absolute_path: path.join(tempRootDir, 'test.txt'),
         offset: 0,
         limit: -5,
       };
@@ -127,21 +127,21 @@ describe('ReadFileTool', () => {
   describe('getDescription', () => {
     it('should return a shortened, relative path', () => {
       const filePath = path.join(tempRootDir, 'sub', 'dir', 'file.txt');
-      const params: ReadFileToolParams = { path: filePath };
+      const params: ReadFileToolParams = { absolute_path: filePath };
       // Assuming tempRootDir is something like /tmp/read-file-tool-root-XXXXXX
       // The relative path would be sub/dir/file.txt
       expect(tool.getDescription(params)).toBe('sub/dir/file.txt');
     });
 
     it('should return . if path is the root directory', () => {
-      const params: ReadFileToolParams = { path: tempRootDir };
+      const params: ReadFileToolParams = { absolute_path: tempRootDir };
       expect(tool.getDescription(params)).toBe('.');
     });
   });
 
   describe('execute', () => {
     it('should return validation error if params are invalid', async () => {
-      const params: ReadFileToolParams = { path: 'relative/path.txt' };
+      const params: ReadFileToolParams = { absolute_path: 'relative/path.txt' };
       const result = await tool.execute(params, abortSignal);
       expect(result.llmContent).toMatch(/Error: Invalid parameters provided/);
       expect(result.returnDisplay).toMatch(/File path must be absolute/);
@@ -149,7 +149,7 @@ describe('ReadFileTool', () => {
 
     it('should return error from processSingleFileContent if it fails', async () => {
       const filePath = path.join(tempRootDir, 'error.txt');
-      const params: ReadFileToolParams = { path: filePath };
+      const params: ReadFileToolParams = { absolute_path: filePath };
       const errorMessage = 'Simulated read error';
       mockProcessSingleFileContent.mockResolvedValue({
         llmContent: `Error reading file ${filePath}: ${errorMessage}`,
@@ -171,7 +171,7 @@ describe('ReadFileTool', () => {
     it('should return success result for a text file', async () => {
       const filePath = path.join(tempRootDir, 'textfile.txt');
       const fileContent = 'This is a test file.';
-      const params: ReadFileToolParams = { path: filePath };
+      const params: ReadFileToolParams = { absolute_path: filePath };
       mockProcessSingleFileContent.mockResolvedValue({
         llmContent: fileContent,
         returnDisplay: `Read text file: ${path.basename(filePath)}`,
@@ -195,7 +195,7 @@ describe('ReadFileTool', () => {
       const imageData = {
         inlineData: { mimeType: 'image/png', data: 'base64...' },
       };
-      const params: ReadFileToolParams = { path: filePath };
+      const params: ReadFileToolParams = { absolute_path: filePath };
       mockProcessSingleFileContent.mockResolvedValue({
         llmContent: imageData,
         returnDisplay: `Read image file: ${path.basename(filePath)}`,
@@ -217,7 +217,7 @@ describe('ReadFileTool', () => {
     it('should pass offset and limit to processSingleFileContent', async () => {
       const filePath = path.join(tempRootDir, 'paginated.txt');
       const params: ReadFileToolParams = {
-        path: filePath,
+        absolute_path: filePath,
         offset: 10,
         limit: 5,
       };
@@ -237,7 +237,7 @@ describe('ReadFileTool', () => {
 
     it('should return error if path is ignored by a .geminiignore pattern', async () => {
       const params: ReadFileToolParams = {
-        path: path.join(tempRootDir, 'foo.bar'),
+        absolute_path: path.join(tempRootDir, 'foo.bar'),
       };
       const result = await tool.execute(params, abortSignal);
       expect(result.returnDisplay).toContain('foo.bar');
diff --git a/packages/core/src/tools/read-file.ts b/packages/core/src/tools/read-file.ts
index bed95746..586a7123 100644
--- a/packages/core/src/tools/read-file.ts
+++ b/packages/core/src/tools/read-file.ts
@@ -18,7 +18,7 @@ export interface ReadFileToolParams {
   /**
    * The absolute path to the file to read
    */
-  path: string;
+  absolute_path: string;
 
   /**
    * The line number to start reading from (optional)
@@ -47,10 +47,11 @@ export class ReadFileTool extends BaseTool<ReadFileToolParams, ToolResult> {
       'Reads and returns the content of a specified file from the local filesystem. Handles text, images (PNG, JPG, GIF, WEBP, SVG, BMP), and PDF files. For text files, it can read specific line ranges.',
       {
         properties: {
-          path: {
+          absolute_path: {
             description:
-              "The absolute path to the file to read (e.g., '/home/user/project/file.txt'). Relative paths are not supported.",
+              "The absolute path to the file to read (e.g., '/home/user/project/file.txt'). Relative paths are not supported. You must provide an absolute path.",
             type: 'string',
+            pattern: '^/',
           },
           offset: {
             description:
@@ -63,7 +64,7 @@ export class ReadFileTool extends BaseTool<ReadFileToolParams, ToolResult> {
             type: 'number',
           },
         },
-        required: ['path'],
+        required: ['absolute_path'],
         type: 'object',
       },
     );
@@ -80,9 +81,9 @@ export class ReadFileTool extends BaseTool<ReadFileToolParams, ToolResult> {
     ) {
       return 'Parameters failed schema validation.';
     }
-    const filePath = params.path;
+    const filePath = params.absolute_path;
     if (!path.isAbsolute(filePath)) {
-      return `File path must be absolute: ${filePath}`;
+      return `File path must be absolute, but was relative: ${filePath}. You must provide an absolute path.`;
     }
     if (!isWithinRoot(filePath, this.rootDirectory)) {
       return `File path must be within the root directory (${this.rootDirectory}): ${filePath}`;
@@ -95,8 +96,11 @@ export class ReadFileTool extends BaseTool<ReadFileToolParams, ToolResult> {
     }
 
     const fileService = this.config.getFileService();
-    if (fileService.shouldGeminiIgnoreFile(params.path)) {
-      const relativePath = makeRelative(params.path, this.rootDirectory);
+    if (fileService.shouldGeminiIgnoreFile(params.absolute_path)) {
+      const relativePath = makeRelative(
+        params.absolute_path,
+        this.rootDirectory,
+      );
       return `File path '${shortenPath(relativePath)}' is ignored by .geminiignore pattern(s).`;
     }
 
@@ -106,12 +110,12 @@ export class ReadFileTool extends BaseTool<ReadFileToolParams, ToolResult> {
   getDescription(params: ReadFileToolParams): string {
     if (
       !params ||
-      typeof params.path !== 'string' ||
-      params.path.trim() === ''
+      typeof params.absolute_path !== 'string' ||
+      params.absolute_path.trim() === ''
     ) {
       return `Path unavailable`;
     }
-    const relativePath = makeRelative(params.path, this.rootDirectory);
+    const relativePath = makeRelative(params.absolute_path, this.rootDirectory);
     return shortenPath(relativePath);
   }
 
@@ -128,7 +132,7 @@ export class ReadFileTool extends BaseTool<ReadFileToolParams, ToolResult> {
     }
 
     const result = await processSingleFileContent(
-      params.path,
+      params.absolute_path,
       this.rootDirectory,
       params.offset,
       params.limit,