File tools

Tools for reading, writing, and editing files. Claude uses these on every task that touches code or text.

Claude Code provides four file tools: FileReadTool for reading any file type, FileWriteTool for creating or overwriting files, FileEditTool for targeted in-place edits, and NotebookEditTool for Jupyter notebooks.

All file tools require the file path to be absolute. Relative paths are automatically expanded to absolute paths using the current working directory.

FileReadTool

Reads the content of a file and returns it to Claude. Supports text files, images, PDFs, and Jupyter notebooks (.ipynb).

Parameters

file_path · string · required

Absolute path to the file to read.

offset · number

Line number to start reading from (1-indexed). Use this when a file is too large to read in one call. Defaults to 1.

limit · number

Number of lines to read. Use together with offset to read a specific range. If omitted, reads to the end of the file (up to the token limit).

pages · string

Page range for PDF files, e.g. "1-5", "3", or "10-20". Only applicable to PDF files. Maximum 20 pages per request.

Supported file types

Type	Behavior
Text files (.ts, .py, .md, etc.)	Returns content with line numbers. Lines are prefixed N: content.
Images (.png, .jpg, .gif, .webp)	Returns base64-encoded image data sent as a vision block. Automatically resized to fit the token budget.
PDFs (.pdf)	Sent as a document block. Use pages to read a specific range for large PDFs.
Jupyter notebooks (.ipynb)	Cells are parsed and returned as structured content.

Large file handling

For files larger than the token limit, the tool returns an error suggesting you use offset and limit to read the file in sections. You can also use GrepTool or BashTool to search for specific content without reading the whole file.

Example

User: What does the `buildTool` function do?

Claude: I'll read the Tool.ts file to find it.
[FileReadTool: { "file_path": "/project/src/Tool.ts", "offset": 1, "limit": 80 }]

FileWriteTool

Creates a new file or overwrites an existing file with the provided content. The entire content is written in a single operation.

FileWriteTool overwrites the file completely. If you only want to change a few lines, use FileEditTool instead — it is more efficient and less likely to introduce unintended changes.

Parameters

file_path · string · required

Absolute path to the file to write. Parent directories are created automatically if they do not exist.

content · string · required

The full content to write to the file.

Behavior

• If the file does not exist, it is created along with any missing parent directories.
• If the file exists, it is overwritten. Claude must have read the file before writing to it — the tool validates that the file has not been modified since it was last read.
• The tool preserves the original file encoding (UTF-8 or UTF-16 LE).

Example

User: Create a new utility file for formatting dates.

Claude: I'll create the file now.
[FileWriteTool: {
  "file_path": "/project/src/utils/dateFormat.ts",
  "content": "export function formatDate(date: Date): string {\n  return date.toISOString().split('T')[0]\n}\n"
}]

FileEditTool

Makes a targeted edit to an existing file by replacing one specific string with another. This is the preferred tool for small, focused changes because it sends only the changed portion rather than the entire file.

Parameters

file_path · string · required

Absolute path to the file to edit.

old_string · string · required

The exact string to find and replace. Must match the file content character-for-character, including whitespace and indentation. Must appear exactly once in the file unless replace_all is set to true.

new_string · string · required

The string to replace old_string with. Can be empty to delete the matched text.

replace_all · boolean

When true, replaces every occurrence of old_string in the file. Defaults to false. If false and old_string appears more than once, the tool returns an error.

How it works

1. Claude reads the file first to get the current content.
2. The tool searches for an exact match of old_string in the file.
3. If exactly one match is found (or replace_all is true), the match is replaced with new_string.
4. The updated file is written back to disk.

Error conditions

Error	Cause
String to replace not found in file	old_string does not appear in the file. Check whitespace, indentation, and line endings.
Found N matches… replace_all is false	old_string appears multiple times. Add more surrounding context to make it unique, or set replace_all: true.
File has not been read yet	FileReadTool must be called before FileEditTool.
File has been modified since read	The file changed after the last read. Call FileReadTool again to refresh the state.

Example

User: Change the function name from `formatDate` to `toISODate`.

Claude: I'll make that change.
[FileEditTool: {
  "file_path": "/project/src/utils/dateFormat.ts",
  "old_string": "export function formatDate(date: Date): string {",
  "new_string": "export function toISODate(date: Date): string {"
}]

When old_string is not unique enough, include the surrounding lines to provide context. More context makes the match unique and prevents accidental replacements elsewhere in the file.

NotebookEditTool

Edits individual cells in a Jupyter notebook (.ipynb file). Unlike FileEditTool, which works on raw text, NotebookEditTool understands notebook structure and operates on cells by index.

How it differs from FileEditTool

FileEditTool cannot be used on .ipynb files — it will return an error directing you to use NotebookEditTool instead. Jupyter notebooks store cell content as JSON arrays, so character-level string matching would be unreliable. NotebookEditTool operates at the cell level and preserves notebook metadata.

Use cases

• Update the source code of a specific code cell.
• Change the text of a markdown cell.
• Insert or replace cells in a notebook without corrupting the JSON structure.

Example

User: Fix the import in the first code cell of the analysis notebook.

Claude: I'll read the notebook first, then update the cell.
[FileReadTool: { "file_path": "/project/analysis.ipynb" }]
[NotebookEditTool: {
  "file_path": "/project/analysis.ipynb",
  "cell_index": 0,
  "new_source": "import pandas as pd\nimport numpy as np\n"
}]