> ## Documentation Index
> Fetch the complete documentation index at: https://crewai-cursor-simplify-filereadtool-docs-ac84.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# File Read

> The `FileReadTool` reads files from the local file system.

## Overview

<Note>
  We are still improving tools, so behavior may change.
</Note>

The `FileReadTool` reads a local file and returns its content as text.
Use it to process text files, read config files, or load data for analysis.
It works with any text format, such as `.txt`, `.csv`, `.json`, and `.md`.
The tool always returns plain text. If you need structured data (for example, JSON), parse it in your agent or your own code.

For large files, the agent can pass `start_line` and `line_count` to read only a range of lines.
The tool stops once it has those lines, so it does not scan the rest of the file.

## Installation

```shell theme={null}
uv add 'crewai[tools]'
```

## Usage Example

```python Code theme={null}
from crewai_tools import FileReadTool

# Agent chooses the file path at runtime
tool = FileReadTool()

# OR set a default file the agent can read with no path argument
tool = FileReadTool(file_path='path/to/your/file.txt')

# OR let the agent read any file under a directory
tool = FileReadTool(base_dir='/data')
```

Give the tool to an agent. At runtime the LLM passes `file_path`, and optionally `start_line` and `line_count`.

## Arguments

The agent can pass these at runtime:

* `file_path`: (Optional) Path to the file to read. Absolute and relative paths are both valid only when they resolve inside the `base_dir` sandbox. A relative path resolves against `base_dir` when set, otherwise against the current working directory (the default sandbox). Omit it to read the default file set at construction. If there is no default, the tool returns an error saying no path was provided.
* `start_line`: (Optional) First line to read. Line numbers start at `1`. Default is `1`.
* `line_count`: (Optional) How many lines to read. If omitted, the tool reads from `start_line` to the end of the file.

You can set these when you create the tool:

* `file_path`: (Optional) Default file to read when the agent calls the tool with no path. A relative path resolves against `base_dir` when `base_dir` is provided, otherwise against the current working directory.
* `base_dir`: (Optional) Directory that runtime paths must stay inside. Default is the current working directory. The tool resolves this path when the tool is created, so a later change of working directory does not move the sandbox.
* `encoding`: (Optional) Text encoding used to decode the file. Default is `utf-8`. If decoding fails, the tool returns an error and suggests passing a different `encoding`.

Common failures (missing file, permission denied, wrong encoding, or a path outside the sandbox) return an error string. They do not raise an exception.

## Allowed paths

An LLM usually chooses the file path at runtime, so reads are limited to a sandbox:

* Runtime paths must resolve inside `base_dir` (default: the current working directory). The tool resolves `..` segments and symlinks before it checks the path, so they cannot escape the sandbox.
* A `file_path` you pass to the constructor is always allowed, even if it is outside `base_dir`. The read can still fail if the file is missing, is a directory, or cannot be accessed. That path is fixed when the tool is created, so a later change of working directory does not change which file it points to. The agent can read it by omitting `file_path`, or by using the name shown in the tool description. Declaring one file does not allow access to other files in the same folder.

To let an agent read files outside the working directory, set `base_dir` when you create the tool (see the example above).

As a last resort, set `CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true` to turn off path checks. This setting applies to every crewai-tools tool in the process, including SSRF protections on URL-fetching tools. Prefer `base_dir` instead.