docs(TSP-1110): add file operations tool step documentation

build/tools/tool-steps.mdx

@@ -26,7 +26,7 @@
 
 <Columns cols={2}>
   <Card title="Firecrawl" href="/build/tools/tool-steps/firecrawl">
     Use Firecrawl to turn websites into LLM-ready data
   </Card>
 
   <Card title="Extract Website Content" href="/build/tools/tool-steps/extract-website-content">
@@ -58,7 +58,7 @@
 
 <Columns cols={2}>
   <Card title="Convert spreadsheet to JSON" href="/build/tools/tool-steps/convert-spreadsheet-to-json">
     Use a Tool step to convert CSVs and XLSXs into JSON
   </Card>
 
   <Card title="Convert a file to text" href="/build/tools/tool-steps/file-to-text">
@@ -68,7 +68,7 @@
 
 <Columns cols={2}>
   <Card title="Convert PDF to text" href="/build/tools/tool-steps/convert-pdf-to-text">
     Use a Tool step to convert PDFs into text for LLMs to read
   </Card>
 
   <Card title="Convert audio/video to text" href="/build/tools/tool-steps/convert-audio-video-to-text">
@@ -76,6 +76,26 @@
   </Card>
 </Columns>
 
+## File operation tool steps
+
+<CardGroup cols={3}>
+  <Card title="Read file" icon="file-lines" href="/build/tools/tool-steps/file-operations/read-file">
+    Read the contents of a file from the filesystem mount
+  </Card>
+  <Card title="Write file" icon="file-pen" href="/build/tools/tool-steps/file-operations/write-file">
+    Create or overwrite a file in the filesystem mount
+  </Card>
+  <Card title="Edit file" icon="pen-to-square" href="/build/tools/tool-steps/file-operations/edit-file">
+    Replace a specific string within a file
+  </Card>
+  <Card title="List files" icon="folder-open" href="/build/tools/tool-steps/file-operations/list-files">
+    List files and directories at a given path
+  </Card>
+  <Card title="Delete file" icon="trash" href="/build/tools/tool-steps/file-operations/delete-file">
+    Permanently remove a file from the filesystem mount
+  </Card>
+</CardGroup>
+
 ## Knowledge Tool steps
 
 <Snippet file="components/integrations/knowledge-tool-steps.mdx" />
@@ -112,5 +132,5 @@
 
 <Snippet file="components/integrations/slack-tool-steps.mdx" />
 
 ### Trello
 

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.
+
+<Warning>
+Deletion is permanent. Verify the file path carefully before running the step, as there is no way to recover a deleted file.
+</Warning>
+
+## Parameters
+
+<ParamField path="file_path" type="string" required>
+  The path to the file to delete, relative to the filesystem mount root. For example: `temp/staging.txt` or `logs/old_run.log`.
+</ParamField>
+
+## Examples
+
+<AccordionGroup>
+  <Accordion title="Cleaning up a temporary file after processing">
+    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.
+  </Accordion>
+
+  <Accordion title="Removing a stale report before generating a new one">
+    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.
+  </Accordion>
+</AccordionGroup>
+
+## 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)
+
+<AccordionGroup>
+  <Accordion title="What happens if the file does not exist?">
+    The step returns an error. No changes are made to the filesystem mount.
+  </Accordion>
+  <Accordion title="Can I delete a directory with Delete file?">
+    No. Delete file only removes individual files. Use a Python code step to remove directories.
+  </Accordion>
+  <Accordion title="Is there a way to recover a deleted file?">
+    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.
+  </Accordion>
+</AccordionGroup>

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
+
+<ParamField path="file_path" type="string" required>
+  The path to the file to edit, relative to the filesystem mount root. For example: `reports/summary.txt` or `data/config.json`.
+</ParamField>
+
+<ParamField path="target" type="string" required>
+  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`.
+</ParamField>
+
+<ParamField path="replacement" type="string" required>
+  The string to insert in place of `target`. Use an empty string to delete the target text without inserting anything.
+</ParamField>
+
+<ParamField path="replace_all" type="boolean">
+  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.
+</ParamField>
+
+## 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
+
+<AccordionGroup>
+  <Accordion title="Replacing a status value in a text file">
+    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
+    ```
+  </Accordion>
+
+  <Accordion title="Updating a value in a JSON config file">
+    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
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="Replacing all occurrences of a string">
+    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.
+    ```
+  </Accordion>
+
+  <Accordion title="Error: target string not found">
+    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.
+  </Accordion>
+
+  <Accordion title="Error: ambiguous match">
+    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.
+  </Accordion>
+</AccordionGroup>
+
+## 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)
+
+<AccordionGroup>
+  <Accordion title="What happens if the file does not exist?">
+    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.
+  </Accordion>
+  <Accordion title="Can I use Edit file to delete a line?">
+    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.
+  </Accordion>
+  <Accordion title="Does Edit file support regex patterns?">
+    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.
+  </Accordion>
+  <Accordion title="Can Edit file handle binary files?">
+    No. Edit file works on text files only. Attempting to edit a binary file will return an error.
+  </Accordion>
+  <Accordion title="Is the match case-sensitive?">
+    Yes. The `target` string is matched exactly as entered, including capitalization.
+  </Accordion>
+</AccordionGroup>

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
+
+<CardGroup cols={2}>
+  <Card title="Read file" icon="file-lines" href="/build/tools/tool-steps/file-operations/read-file">
+    Read the contents of a file from the filesystem mount.
+  </Card>
+  <Card title="Write file" icon="file-pen" href="/build/tools/tool-steps/file-operations/write-file">
+    Create a new file or overwrite an existing file with new content.
+  </Card>
+  <Card title="Edit file" icon="pen-to-square" href="/build/tools/tool-steps/file-operations/edit-file">
+    Replace a specific string within a file without rewriting the whole file.
+  </Card>
+  <Card title="List files" icon="folder-open" href="/build/tools/tool-steps/file-operations/list-files">
+    List the files and directories at a given path in the filesystem mount.
+  </Card>
+  <Card title="Delete file" icon="trash" href="/build/tools/tool-steps/file-operations/delete-file">
+    Permanently remove a file from the filesystem mount.
+  </Card>
+</CardGroup>
+
+## 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 |
+
+<Note>
+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.
+</Note>