From c10be0e06ebdc631578f9d69eea6c59ea12ef584 Mon Sep 17 00:00:00 2001 From: theCyberTech Date: Sun, 28 Jun 2026 12:16:40 +0800 Subject: [PATCH 1/3] docs(file-writer): fix accuracy of FileWriterTool page The Edge MDX for FileWriterTool had several accuracy issues against the actual tool source (crewai_tools/tools/file_writer_tool/file_writer_tool.py): - Claimed 'supports UTF-8 encoding' but open() is called without an encoding= argument, so behavior follows locale.getpreferredencoding() (UTF-8 on Linux/macOS, cp1252 on stock Windows). Replaced the claim with an accurate note + PYTHONUTF8 guidance. - Did not state the tool is text-only. Added a warning that binary files (images, PDFs, archives, executables) are not supported. - The overwrite argument (overwrite: str | bool = False) was missing entirely from the Arguments list, even though it controls exclusive vs write mode and the already-exists error. Documented it. - The auto-mkdir behavior is conditional on directory being explicitly passed; the docs implied unconditional creation. Clarified. - The example used positional args against _run(self, **kwargs), which would KeyError. Switched to keyword arguments. --- .../en/tools/file-document/filewritetool.mdx | 21 ++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/docs/edge/en/tools/file-document/filewritetool.mdx b/docs/edge/en/tools/file-document/filewritetool.mdx index f8bc464cef..16c645513b 100644 --- a/docs/edge/en/tools/file-document/filewritetool.mdx +++ b/docs/edge/en/tools/file-document/filewritetool.mdx @@ -11,7 +11,13 @@ mode: "wide" The `FileWriterTool` is a component of the crewai_tools package, designed to simplify the process of writing content to files with cross-platform compatibility (Windows, Linux, macOS). It is particularly useful in scenarios such as generating reports, saving logs, creating configuration files, and more. -This tool handles path differences across operating systems, supports UTF-8 encoding, and automatically creates directories if they don't exist, making it easier to organize your output reliably across different platforms. +This tool handles path differences across operating systems, guards against path-traversal and symlink escapes, and creates parent directories (when a `directory` is explicitly provided) if they don't exist, making it easier to organize your output reliably across different platforms. + + +The tool writes `content` in **text mode** — it is intended for plain-text files only (`.txt`, `.md`, `.json`, `.yaml`, `.csv`, `.log`, `.py`, config files, generated source, reports, etc.). It is **not** suitable for binary files such as images, PDFs, archives, or executables; writing binary data through it will raise or corrupt the output. + +No explicit `encoding` is passed to `open()`, so the byte encoding follows `locale.getpreferredencoding()` — UTF-8 on Linux/macOS, but typically cp1252 on stock Windows. Set `PYTHONUTF8=1` (or otherwise configure the locale) if you need guaranteed UTF-8 on Windows. + ## Installation @@ -31,16 +37,21 @@ from crewai_tools import FileWriterTool # Initialize the tool file_writer_tool = FileWriterTool() -# Write content to a file in a specified directory -result = file_writer_tool._run('example.txt', 'This is a test content.', 'test_directory') +# Write content to a file in a specified directory (keyword arguments) +result = file_writer_tool._run( + filename='example.txt', + content='This is a test content.', + directory='test_directory', +) print(result) ``` ## Arguments - `filename`: The name of the file you want to create or overwrite. -- `content`: The content to write into the file. -- `directory` (optional): The path to the directory where the file will be created. Defaults to the current directory (`.`). If the directory does not exist, it will be created. +- `content`: The text content to write into the file (string). +- `directory` (optional): The path to the directory where the file will be created. Defaults to the current directory (`./`). Parent directories are created **only when `directory` is explicitly provided**; the default `./` does not trigger directory creation. +- `overwrite` (optional, default `False`): Whether to overwrite an existing file. Accepts a bool or a string (`"true"`/`"false"`, `"yes"`/`"no"`, `"1"`/`"0"`, etc.). When `False`, the tool opens in exclusive-create mode (`"x"`) and returns an error if the file already exists; when truthy, it opens in write mode (`"w"`) and replaces the file. ## Conclusion From c17da4e3ade6a18c009038517c8de2d7a881540e Mon Sep 17 00:00:00 2001 From: theCyberTech Date: Sun, 28 Jun 2026 13:25:15 +0800 Subject: [PATCH 2/3] docs(file-writer): use public .run() in example, not _run() _run is the internal entrypoint; the public API is .run(). Update the example so readers aren't shown calling a private method. --- docs/edge/en/tools/file-document/filewritetool.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/edge/en/tools/file-document/filewritetool.mdx b/docs/edge/en/tools/file-document/filewritetool.mdx index 16c645513b..7032f70728 100644 --- a/docs/edge/en/tools/file-document/filewritetool.mdx +++ b/docs/edge/en/tools/file-document/filewritetool.mdx @@ -37,8 +37,8 @@ from crewai_tools import FileWriterTool # Initialize the tool file_writer_tool = FileWriterTool() -# Write content to a file in a specified directory (keyword arguments) -result = file_writer_tool._run( +# Write content to a file in a specified directory +result = file_writer_tool.run( filename='example.txt', content='This is a test content.', directory='test_directory', From d11a5dfb1372707522c0fc33eb4f93ab34a19835 Mon Sep 17 00:00:00 2001 From: theCyberTech Date: Sun, 28 Jun 2026 13:26:33 +0800 Subject: [PATCH 3/3] docs(file-writer): show tool attached to an agent, not called directly Tools are meant to be handed to an Agent via tools=[...] and invoked by the agent during a task. The previous example called the tool's method directly, which is not how users should use CrewAI tools. Replace with a full agent+task+crew example mirroring the pattern used by sibling tool pages (e.g. seleniumscrapingtool). --- .../en/tools/file-document/filewritetool.mdx | 32 +++++++++++++++---- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/docs/edge/en/tools/file-document/filewritetool.mdx b/docs/edge/en/tools/file-document/filewritetool.mdx index 7032f70728..e37f0d55af 100644 --- a/docs/edge/en/tools/file-document/filewritetool.mdx +++ b/docs/edge/en/tools/file-document/filewritetool.mdx @@ -29,23 +29,41 @@ pip install 'crewai[tools]' ## Example -To get started with the `FileWriterTool`: +The `FileWriterTool` is attached to an agent and invoked by that agent during a task — you don't call it yourself. Initialize the tool, hand it to an `Agent` via `tools=[...]`, and let the crew run. ```python Code +from crewai import Agent, Crew, Task, Process from crewai_tools import FileWriterTool # Initialize the tool file_writer_tool = FileWriterTool() -# Write content to a file in a specified directory -result = file_writer_tool.run( - filename='example.txt', - content='This is a test content.', - directory='test_directory', +# Define an agent that can write files +report_writer = Agent( + role="Report Writer", + goal="Produce written reports and save them to disk", + backstory="A meticulous writer who files every report as a .md file.", + tools=[file_writer_tool], ) -print(result) + +# Task that asks the agent to write a file +write_task = Task( + description="Write a short markdown report summarizing the Q3 results to a file named q3_report.md inside the reports directory.", + expected_output="Confirmation that q3_report.md was written to the reports directory.", + agent=report_writer, +) + +crew = Crew( + agents=[report_writer], + tasks=[write_task], + process=Process.sequential, +) +result = crew.kickoff() +print(result.raw) ``` +When the agent decides to write a file, it calls the tool with `filename`, `content`, and optionally `directory` and `overwrite` (see Arguments). + ## Arguments - `filename`: The name of the file you want to create or overwrite.