diff --git a/build/tools/tool-steps.mdx b/build/tools/tool-steps.mdx
index d847c212..af50d9ca 100644
--- a/build/tools/tool-steps.mdx
+++ b/build/tools/tool-steps.mdx
@@ -76,6 +76,26 @@ tag: "NEW"
+## File operation tool steps
+
+
+
+ Read the contents of a file from the filesystem mount
+
+
+ Create or overwrite a file in the filesystem mount
+
+
+ Replace a specific string within a file
+
+
+ List files and directories at a given path
+
+
+ Permanently remove a file from the filesystem mount
+
+
+
## Knowledge Tool steps
diff --git a/build/tools/tool-steps/file-operations/delete-file.mdx b/build/tools/tool-steps/file-operations/delete-file.mdx
new file mode 100644
index 00000000..1aa6eccf
--- /dev/null
+++ b/build/tools/tool-steps/file-operations/delete-file.mdx
@@ -0,0 +1,67 @@
+---
+title: "Delete file"
+description: "Permanently remove a file from the filesystem mount."
+---
+
+The Delete file tool step removes a file from the filesystem mount. The deletion is permanent — there is no undo or recycle bin.
+
+## Add the Delete file tool step to your tool
+
+1. Open your tool and click **+ Add step**.
+2. Search for **Delete file** and select it.
+3. Enter the **File path** — the path to the file you want to delete within the filesystem mount.
+4. Click **Run step** to test the deletion.
+
+
+Deletion is permanent. Verify the file path carefully before running the step, as there is no way to recover a deleted file.
+
+
+## Parameters
+
+
+ The path to the file to delete, relative to the filesystem mount root. For example: `temp/staging.txt` or `logs/old_run.log`.
+
+
+## Examples
+
+
+
+ An agent creates a temporary staging file during a multi-step workflow and removes it once the final output has been written:
+
+ | Parameter | Value |
+ |---|---|
+ | `file_path` | `temp/staging_data.json` |
+
+ The Delete file step runs as the last step in the tool, after the staging data has been used and is no longer needed.
+
+
+
+ Before writing a fresh report, an agent deletes the previous version to avoid confusion if the new write step fails partway through:
+
+ | Parameter | Value |
+ |---|---|
+ | `file_path` | `reports/current_report.txt` |
+
+ A Write file step then creates the new report at the same path.
+
+
+
+## Safety considerations
+
+- **Permanent deletion** — deleted files cannot be recovered from within Relevance AI. If you need a backup, copy the contents to another file using Read file and Write file before deleting.
+- **No directory deletion** — Delete file only removes individual files. To remove a directory and its contents, use a Python code step with `shutil.rmtree`.
+- **Verify the path** — double-check that the `file_path` is correct before running. A common mistake is deleting a file in production when a staging path was intended.
+
+## Frequently asked questions (FAQs)
+
+
+
+ The step returns an error. No changes are made to the filesystem mount.
+
+
+ No. Delete file only removes individual files. Use a Python code step to remove directories.
+
+
+ No. Deletion is permanent within the filesystem mount. If file recovery is important for your workflow, implement a backup strategy using Read file and Write file to copy files to a backup directory before deletion.
+
+
diff --git a/build/tools/tool-steps/file-operations/edit-file.mdx b/build/tools/tool-steps/file-operations/edit-file.mdx
new file mode 100644
index 00000000..b4a3a421
--- /dev/null
+++ b/build/tools/tool-steps/file-operations/edit-file.mdx
@@ -0,0 +1,183 @@
+---
+title: "Edit file"
+description: "Replace a specific string within a file without rewriting the whole file."
+---
+
+The Edit file tool step performs a targeted string replacement inside a file. Instead of reading the entire file, generating new content, and writing it back, an agent can make a precise change to exactly the text that needs updating.
+
+## Add the Edit file tool step to your tool
+
+1. Open your tool and click **+ Add step**.
+2. Search for **Edit file** and select it.
+3. Enter the **File path** — the path to the file you want to edit within the filesystem mount.
+4. Enter the **Target** string — the exact text you want to replace.
+5. Enter the **Replacement** string — the text to insert in place of the target.
+6. Optionally, enable **Replace all** if the target string appears multiple times and you want every occurrence replaced.
+7. Click **Run step** to test the edit.
+
+## Parameters
+
+
+ The path to the file to edit, relative to the filesystem mount root. For example: `reports/summary.txt` or `data/config.json`.
+
+
+
+ The exact string to find in the file. The edit fails if this string is not found, or if it appears more than once and `replace_all` is not set to `true`.
+
+
+
+ The string to insert in place of `target`. Use an empty string to delete the target text without inserting anything.
+
+
+
+ When `true`, every occurrence of `target` in the file is replaced. When `false` or omitted, the step fails if `target` appears more than once — this protects against unintended edits when the target string is not unique.
+
+
+## Safety behavior
+
+Edit file is designed to fail explicitly rather than silently make a wrong change:
+
+- **Target not found** — the step returns an error and the file is left unchanged.
+- **Multiple matches, `replace_all` not set** — the step returns an error describing the ambiguity and the file is left unchanged.
+- **Multiple matches, `replace_all: true`** — all occurrences are replaced.
+
+This means an agent can check the step output for errors and decide how to proceed, rather than discovering a corrupted file later.
+
+## Examples
+
+
+
+ A file `jobs/status.txt` contains:
+
+ ```
+ Job ID: 1042
+ Status: pending
+ Assigned to: Alice
+ ```
+
+ To update the status:
+
+ | Parameter | Value |
+ |---|---|
+ | `file_path` | `jobs/status.txt` |
+ | `target` | `Status: pending` |
+ | `replacement` | `Status: complete` |
+
+ Result:
+
+ ```
+ Job ID: 1042
+ Status: complete
+ Assigned to: Alice
+ ```
+
+
+
+ A file `config/settings.json` contains:
+
+ ```json
+ {
+ "environment": "staging",
+ "debug": false,
+ "max_retries": 3
+ }
+ ```
+
+ To promote the environment to production:
+
+ | Parameter | Value |
+ |---|---|
+ | `file_path` | `config/settings.json` |
+ | `target` | `"environment": "staging"` |
+ | `replacement` | `"environment": "production"` |
+
+ Result:
+
+ ```json
+ {
+ "environment": "production",
+ "debug": false,
+ "max_retries": 3
+ }
+ ```
+
+
+
+ A report file `output/report.txt` contains multiple references to a former project name:
+
+ ```
+ Project Phoenix update: Phase 1 complete.
+ Phoenix milestones are on track.
+ Next review for Phoenix is Friday.
+ ```
+
+ To rename the project throughout the file:
+
+ | Parameter | Value |
+ |---|---|
+ | `file_path` | `output/report.txt` |
+ | `target` | `Phoenix` |
+ | `replacement` | `Aurora` |
+ | `replace_all` | `true` |
+
+ Result:
+
+ ```
+ Project Aurora update: Phase 1 complete.
+ Aurora milestones are on track.
+ Next review for Aurora is Friday.
+ ```
+
+
+
+ If the target string does not exist in the file, the step returns an error similar to:
+
+ ```
+ Error: Target string not found in file "jobs/status.txt".
+ The file has not been modified.
+ ```
+
+ The file is left unchanged. In your tool, you can route on this error to retry with a corrected target or surface the issue to the agent.
+
+
+
+ If `target` appears more than once and `replace_all` is not enabled, the step returns an error:
+
+ ```
+ Error: Target string appears 3 times in "output/report.txt".
+ Set replace_all to true to replace all occurrences, or use a more specific target string.
+ ```
+
+ The file is left unchanged.
+
+
+
+## Best practices
+
+**Make target strings specific.** The more context you include in the target, the less likely it is to match unintended text. For example, prefer `"status": "pending"` over just `pending` when editing a JSON file.
+
+**Include surrounding context.** If the value you want to change is short or generic (like a number or a common word), include the surrounding line or key-value pair as the target to ensure uniqueness.
+
+**Use `replace_all` deliberately.** Only enable `replace_all` when you intentionally want every occurrence changed. For most targeted edits, leaving it off lets the safety check catch accidental ambiguity.
+
+**Prefer Edit file over Write file for partial updates.** Reading a large file, modifying it in an LLM prompt, and writing it back risks introducing unintended changes to untouched sections. Edit file touches only the specified text.
+
+## Frequently asked questions (FAQs)
+
+
+
+ The step returns an error and does not create the file. Use the Write file step to create a new file, then use Edit file for subsequent modifications.
+
+
+ Yes. Set `replacement` to an empty string to remove the target text. To remove a full line including its newline character, include the newline in the `target` string.
+
+
+ No. The `target` is matched as a literal string. For pattern-based replacements, use the Python code tool step with a script that performs regex substitution.
+
+
+ No. Edit file works on text files only. Attempting to edit a binary file will return an error.
+
+
+ Yes. The `target` string is matched exactly as entered, including capitalization.
+
+
diff --git a/build/tools/tool-steps/file-operations/index.mdx b/build/tools/tool-steps/file-operations/index.mdx
new file mode 100644
index 00000000..e6153cc6
--- /dev/null
+++ b/build/tools/tool-steps/file-operations/index.mdx
@@ -0,0 +1,58 @@
+---
+title: "File operations"
+sidebarTitle: "Overview"
+description: "Read, write, edit, list, and delete files in your agent's filesystem mount."
+---
+
+File operation tool steps give agents direct access to files stored in a filesystem mount. Agents can read file contents, create new files, make targeted edits, list directory contents, and delete files — all without leaving the Relevance AI platform.
+
+## Available file operations
+
+
+
+ Read the contents of a file from the filesystem mount.
+
+
+ Create a new file or overwrite an existing file with new content.
+
+
+ Replace a specific string within a file without rewriting the whole file.
+
+
+ List the files and directories at a given path in the filesystem mount.
+
+
+ Permanently remove a file from the filesystem mount.
+
+
+
+## How file operations work
+
+File operations work with filesystem mounts attached to an agent's environment. A filesystem mount is a persistent storage volume that exists across agent runs. Files written in one run are available in subsequent runs, making it possible for agents to maintain state, accumulate data, and collaborate on shared files.
+
+File operations are built-in tool steps — they do not require an external integration or API credentials.
+
+## File operations vs. file inputs
+
+File inputs (uploaded through the agent conversation) are read-only references to files provided by a user. File operations, by contrast, work with files stored in the agent's filesystem mount. Use file operations when:
+
+- The agent needs to create or modify files as part of its work
+- Files need to persist between agent runs
+- The agent is processing, transforming, or building up a file over multiple steps
+
+Use file inputs when a user needs to hand a file to the agent for one-time processing.
+
+## Choosing the right operation
+
+| Goal | Operation |
+|---|---|
+| Read the full contents of a file | Read file |
+| Create a new file | Write file |
+| Overwrite a file with entirely new content | Write file |
+| Change a specific part of a file | Edit file |
+| See what files exist in a directory | List files |
+| Remove a file | Delete file |
+
+
+All file operations fail safely with a clear error message if the target file or path does not exist, so agents can handle errors explicitly rather than silently producing bad output.
+
diff --git a/build/tools/tool-steps/file-operations/list-files.mdx b/build/tools/tool-steps/file-operations/list-files.mdx
new file mode 100644
index 00000000..7af774a6
--- /dev/null
+++ b/build/tools/tool-steps/file-operations/list-files.mdx
@@ -0,0 +1,86 @@
+---
+title: "List files"
+description: "List the files and directories at a given path in the filesystem mount."
+---
+
+The List files tool step returns the names of all files and subdirectories located at a specified path in the filesystem mount. Use it to discover what files are available before reading, editing, or deleting them.
+
+## Add the List files tool step to your tool
+
+1. Open your tool and click **+ Add step**.
+2. Search for **List files** and select it.
+3. Enter the **Directory path** — the path to the directory you want to list within the filesystem mount.
+4. Click **Run step** to test the listing and review the output.
+
+## Parameters
+
+
+ The path to the directory to list, relative to the filesystem mount root. For example: `reports/` or `data/exports`. Use `/` or an empty string to list the root of the filesystem mount.
+
+
+## Output
+
+The step returns a list of file and directory names found at the specified path. The output includes both files and subdirectories, but does not recurse into subdirectories — only the immediate contents are returned.
+
+## Examples
+
+
+
+ An agent checks what report files have accumulated in the `reports/` directory:
+
+ | Parameter | Value |
+ |---|---|
+ | `directory_path` | `reports/` |
+
+ Example output:
+
+ ```
+ ["daily_2026-03-25.txt", "daily_2026-03-26.txt", "weekly_summary.txt"]
+ ```
+
+
+
+ An agent lists all top-level directories and files to understand the overall structure:
+
+ | Parameter | Value |
+ |---|---|
+ | `directory_path` | `/` |
+
+ Example output:
+
+ ```
+ ["config", "data", "logs", "reports"]
+ ```
+
+
+
+ An agent uses List files to get all filenames in `data/incoming/`, then iterates over the list in a Python code step to process each file individually using Read file steps.
+
+ | Parameter | Value |
+ |---|---|
+ | `directory_path` | `data/incoming/` |
+
+ The output list is passed to a Python code step that loops through each filename and constructs the full path for subsequent Read file calls.
+
+
+
+## When to use List files
+
+- Before reading or editing a file, to confirm it exists at the expected path
+- To iterate over a directory of files for batch processing
+- To check whether a file has been created by a previous step or agent run
+- To audit what files an agent has produced over multiple runs
+
+## Frequently asked questions (FAQs)
+
+
+
+ The step returns an error. The directory must exist in the filesystem mount before it can be listed.
+
+
+ No. List files returns only the immediate contents of the specified directory. To list files recursively, use a Python code step with `os.walk`.
+
+
+ The output includes only the file and directory names, not the full paths. Prepend the directory path in a subsequent step if you need the full path to pass to Read file, Edit file, or Delete file.
+
+
diff --git a/build/tools/tool-steps/file-operations/read-file.mdx b/build/tools/tool-steps/file-operations/read-file.mdx
new file mode 100644
index 00000000..918f77ce
--- /dev/null
+++ b/build/tools/tool-steps/file-operations/read-file.mdx
@@ -0,0 +1,71 @@
+---
+title: "Read file"
+description: "Read the contents of a file from the filesystem mount."
+---
+
+The Read file tool step retrieves the full text contents of a file stored in the filesystem mount and makes it available as output for the next step in your tool.
+
+## Add the Read file tool step to your tool
+
+1. Open your tool and click **+ Add step**.
+2. Search for **Read file** and select it.
+3. Enter the **File path** — the path to the file you want to read within the filesystem mount.
+4. Click **Run step** to test the read and confirm the file contents appear in the output.
+
+## Parameters
+
+
+ The path to the file to read, relative to the filesystem mount root. For example: `reports/summary.txt` or `data/records.json`.
+
+
+## Output
+
+The step returns the full text content of the file as a string. You can reference this output in subsequent steps using the step output variable.
+
+## Examples
+
+
+
+ An agent needs to summarize a daily report. The report is saved to `reports/daily.txt` by a previous step.
+
+ | Parameter | Value |
+ |---|---|
+ | `file_path` | `reports/daily.txt` |
+
+ The step output (the file contents) is then passed to an LLM tool step with a prompt like: `Summarize the following report: {{read_file.output}}`.
+
+
+
+ An agent reads its own configuration before starting a task:
+
+ | Parameter | Value |
+ |---|---|
+ | `file_path` | `config/agent_settings.json` |
+
+ The output is a JSON string that can be parsed in a subsequent Python code step or passed directly to an LLM.
+
+
+
+## When to use Read file
+
+- Before editing a file, to check its current contents
+- To pass file contents to an LLM tool step for analysis or summarization
+- To retrieve data written by a previous agent run (because files in filesystem mounts persist between runs)
+- To load configuration or state that was saved in an earlier step
+
+## Frequently asked questions (FAQs)
+
+
+
+ The step returns an error and produces no output. Subsequent steps that depend on the output will not run unless your tool handles the error explicitly.
+
+
+ Very large files may exceed the context limits of downstream LLM tool steps. For large files, consider using the Python code step to extract only the relevant section before passing it to an LLM.
+
+
+ No. Read file is designed for text files. For binary files such as PDFs or images, use the Convert PDF to text or File to text tool steps instead.
+
+
+ Yes. Read file only works with files stored in the agent's filesystem mount. It cannot read files from external URLs or storage services directly.
+
+
diff --git a/build/tools/tool-steps/file-operations/write-file.mdx b/build/tools/tool-steps/file-operations/write-file.mdx
new file mode 100644
index 00000000..08cf973e
--- /dev/null
+++ b/build/tools/tool-steps/file-operations/write-file.mdx
@@ -0,0 +1,86 @@
+---
+title: "Write file"
+description: "Create a new file or overwrite an existing file with new content."
+---
+
+The Write file tool step writes a string of text to a specified path in the filesystem mount. If the file already exists, it is overwritten completely. If it does not exist, it is created.
+
+## Add the Write file tool step to your tool
+
+1. Open your tool and click **+ Add step**.
+2. Search for **Write file** and select it.
+3. Enter the **File path** — the path where the file should be written within the filesystem mount.
+4. Enter the **Content** — the text to write to the file.
+5. Click **Run step** to test the write and confirm the file was created.
+
+## Parameters
+
+
+ The path where the file should be written, relative to the filesystem mount root. For example: `reports/output.txt` or `data/result.json`. If intermediate directories in the path do not exist, the step will return an error.
+
+
+
+ The text content to write to the file. The file will contain exactly this string — no formatting or encoding is applied automatically.
+
+
+## Examples
+
+
+
+ An agent generates a report using an LLM step and saves it for later retrieval:
+
+ | Parameter | Value |
+ |---|---|
+ | `file_path` | `reports/weekly_summary.txt` |
+ | `content` | `{{llm_step.output}}` |
+
+ The file is written to the filesystem mount and persists for future agent runs.
+
+
+
+ An agent writes structured data output to a JSON file:
+
+ | Parameter | Value |
+ |---|---|
+ | `file_path` | `data/results.json` |
+ | `content` | `{{python_step.output}}` |
+
+ The Python code step produces a JSON string, which Write file saves to the specified path.
+
+
+
+ An agent creates a new configuration file with default values at the start of a workflow:
+
+ | Parameter | Value |
+ |---|---|
+ | `file_path` | `config/run_config.json` |
+ | `content` | `{"status": "pending", "retries": 0, "last_run": null}` |
+
+
+
+## Write file vs. Edit file
+
+| Use case | Recommended step |
+|---|---|
+| Creating a new file | Write file |
+| Replacing the full contents of a file | Write file |
+| Changing a specific part of a file | [Edit file](/build/tools/tool-steps/file-operations/edit-file) |
+
+Use Edit file when only a small portion of the file needs to change. Rewriting an entire file with Write file when only one line needs updating risks introducing errors in the untouched sections, especially when the new content is generated by an LLM.
+
+## Frequently asked questions (FAQs)
+
+
+
+ The existing file is overwritten entirely. There is no merge — the new content completely replaces the old content. If you need to preserve existing content, read the file first and incorporate its contents into the new content string.
+
+
+ No. If the directories in the file path do not already exist, the step returns an error. Create any necessary directories before using Write file, or use a Python code step with `os.makedirs` to create the directory structure.
+
+
+ Write file always overwrites. To append, use a Read file step to get the current contents, concatenate the new content in a subsequent step, then write the combined result back with Write file.
+
+
+ There is no hard limit imposed by the Write file step itself, but very large content strings may be constrained by tool step input limits or filesystem mount capacity.
+
+
diff --git a/docs.json b/docs.json
index 6c23cead..243b399a 100644
--- a/docs.json
+++ b/docs.json
@@ -298,6 +298,17 @@
"build/tools/tool-steps/python-code/code-python-helper-functions"
]
},
+ {
+ "group": "File Operations",
+ "pages": [
+ "build/tools/tool-steps/file-operations/index",
+ "build/tools/tool-steps/file-operations/read-file",
+ "build/tools/tool-steps/file-operations/write-file",
+ "build/tools/tool-steps/file-operations/edit-file",
+ "build/tools/tool-steps/file-operations/list-files",
+ "build/tools/tool-steps/file-operations/delete-file"
+ ]
+ },
"build/tools/tool-steps/firecrawl",
"build/tools/tool-steps/extract-website-content",
"build/tools/tool-steps/api",