Improve file editing tool use for notebook #260233
Description
- ❓ for GPT models, we use apply_patch
- Waiting to review the failures
- ✅ for Claude models
- use string_replace (or the new MultiEdit tool) (Claude Code used to have system instructions to nudge model to use Notebook* tools) https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/text-editor-tool
- ✅ Claude Code ships Read Notebook and Edit Notebook tools
- Based on telemetry Edit notebook tool works just fine, no need to tweak this.
- Notebook summary updated to include line numbers for cells
- I.e. no need of a dedicated readnotebook tool.
- ✅ Edit Notebook Tool uses
insert/delete/replacewith cell id
Show Claude Tools
-
Claude Read Tool (for notebooks)
Purpose: Reads Jupyter notebook files (.ipynb) and returns all cells with their outputs, combining code, text, and visualizations.Required Arguments:
- file_path (string): The absolute path to the notebook file to read
Optional Arguments:
- limit (number): The number of lines to read (only provide if file is too large)
- offset (number): The line number to start reading from (only provide if file is too large)
Key Features:
- Processes Jupyter notebooks (.ipynb files) specially
- Returns all cells with their outputs
- Combines code, text, and visualizations for analysis
- Uses cat -n format with line numbers starting at 1
- Can handle large notebooks with limit/offset parameters
-
NotebookEdit Tool
Purpose: Completely replaces the contents of a specific cell in a Jupyter notebook (.ipynb file) with new source.
Required Arguments:
- notebook_path (string): The absolute path to the Jupyter notebook file to edit (must be absolute, not relative)
- new_source (string): The new source content for the cell
Optional Arguments:
- cell_id (string): The ID of the cell to edit. When inserting a new cell, the new cell will be inserted after the cell with this ID, or at the beginning if not specified
- cell_type (enum): The type of the cell - either "code" or "markdown". Defaults to current cell type if not specified. Required when using edit_mode=insert
- edit_mode (enum): The type of edit operation:
- "replace" (default): Replace the contents of an existing cell
- "insert": Add a new cell at the specified position
- "delete": Delete the cell at the specified index
Key Features:
- Works with Jupyter notebooks (.ipynb files) which combine code, text, and visualizations
- Supports both code and markdown cells
- Can replace, insert, or delete cells
- Uses cell IDs for precise targeting
- Designed for interactive documents commonly used in data analysis and scientific computing
The tool is specifically designed for programmatic manipulation of Jupyter notebook cells without requiring manual editing of the JSON structure.
- ❌ for Gemini (use string_replace?) https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/file-system.md
See below notes (not going to give preference to string replace tools) - ✅ always have fallback for notebook edit tool, also in the error message for the builtin tools
- ❌ Create more stests and run against the test data
Given Notebook Edit tool has > 98.5% success rate, i don't think we'd learn anything new here.
NOTE
- No need to explicitly ask model to use string_replace or apply_patch, as Model can decide.
- Also notebook edit tool will not perform any speculative decoding, hence in theory notebook edit and string replace/apply patch are equally performant.
- Notebook has a higher success rate > 98.5%
- 🏃 We do however tell model to use Notebook Edit took, given the fact that this has > 98.5% success rate, we might end up deciding to leave this as is, as Notebook Edit is significantly better.