Reference for the files default tool: read_file, read_file_lines, write_file, list_directory, file_info, delete_file, create_directory, copy_file, move_file.

Files Tool

Script: powers/files.py Dependencies: pydantic

Read, write, copy, move, and delete files and directories. Includes line-number display for code files and efficient partial file reading.

read_file

Read the entire contents of a file, optionally with line numbers.

Input

Field	Type	Default	Description
`path`	`str`	required	Path to the file to read
`encoding`	`str`	`"utf-8"`	File encoding
`include_line_numbers`	`bool`	`true`	Prefix each line with its 1-based line number

Output

Field	Type	Description
`ok`	`bool`	`true` if file was read successfully
`content`	`str`	File contents (with line numbers if enabled)
`size`	`int`	File size in bytes
`path`	`str`	Absolute path to the file
`error`	`str`	Error message on failure

Examples

// Read with line numbers (default)
{"path": "src/main.py"}
// Content: "1: import os\n2: import sys\n3: \n4: def main():\n..."

// Read without line numbers
{"path": "data.txt", "include_line_numbers": false}

// Different encoding
{"path": "legacy.txt", "encoding": "latin-1"}

Notes

Maximum file size is 50MB
Line numbers are right-justified and formatted as N: line content
Returns the absolute path of the file in the output

read_file_lines

Read a specific range of lines from a file. Much more efficient than read_file for large files.

Input

Field	Type	Default	Description
`path`	`str`	required	Path to the file to read
`start_line`	`int`	`1`	First line to read (1-based, inclusive)
`end_line`	`int`	`-1`	Last line to read (1-based, inclusive). -1 = end of file
`encoding`	`str`	`"utf-8"`	File encoding
`include_line_numbers`	`bool`	`true`	Prefix each line with its line number

Output

Field	Type	Description
`ok`	`bool`	`true` if read succeeded
`content`	`str`	Selected lines
`start_line`	`int`	Actual start line (after clamping)
`end_line`	`int`	Actual end line
`total_lines`	`int`	Total number of lines in the file
`path`	`str`	Absolute path
`error`	`str`	Error message on failure

Examples

// Read lines 1-50
{"path": "main.py", "start_line": 1, "end_line": 50}

// Read lines 100-150
{"path": "main.py", "start_line": 100, "end_line": 150}

// Read the last line
{"path": "big.log", "start_line": -1, "end_line": -1}

Notes

Line numbers format as N| line content (with pipe separator)
Negative indices work like Python: -1 = last line
Both start and end are inclusive

write_file

Write content to a file, creating parent directories if needed.

Input

Field	Type	Default	Description
`path`	`str`	required	Path to the file to write
`content`	`str`	required	Content to write
`encoding`	`str`	`"utf-8"`	File encoding
`create_dirs`	`bool`	`true`	Create parent directories if needed

Output

Field	Type	Description
`ok`	`bool`	`true` if write succeeded
`path`	`str`	Absolute path to the written file
`size`	`int`	Size of written content in bytes
`error`	`str`	Error message on failure

Examples

// Write a new file
{"path": "output.txt", "content": "Hello, world!"}

// Write to nested directory (auto-created)
{"path": "data/results/output.json", "content": "{\"status\": \"ok\"}"}

list_directory

List files and directories, optionally filtered by glob pattern.

Input

Field	Type	Default	Description
`path`	`str`	`"."`	Directory path
`pattern`	`str`	`null`	Optional glob pattern (e.g., `*.py`)
`recursive`	`bool`	`false`	List recursively

Output

Field	Type	Description
`ok`	`bool`	`true` if directory was listed
`items`	`list`	Array of `{name, path, type, size}` objects
`count`	`int`	Number of items found
`error`	`str`	Error message on failure

Examples

// List current directory
{"path": "."}

// List Python files
{"path": "src", "pattern": "*.py"}

// Recursive markdown search
{"path": ".", "pattern": "*.md", "recursive": true}

file_info

Get detailed information about a file or directory.

Input

Field	Type	Default	Description
`path`	`str`	required	Path to get info for

Output

Field	Type	Description
`ok`	`bool`	`true` if path exists
`path`	`str`	Absolute path
`name`	`str`	File/directory name
`type`	`str`	`"file"` or `"directory"`
`size`	`int`	Size in bytes
`extension`	`str`	File extension (files only)
`error`	`str`	Error message on failure

delete_file

Delete a single file (not directories).

Input

Field	Type	Default	Description
`path`	`str`	required	Path to the file to delete

Output

Field	Type	Description
`ok`	`bool`	`true` if deleted
`deleted`	`str`	Path of the deleted file
`error`	`str`	Error message on failure

Notes

Will not delete directories -- returns an error suggesting delete_directory
Returns an error if the file does not exist

create_directory

Create a directory, including parent directories.

Input

Field	Type	Default	Description
`path`	`str`	required	Directory path to create
`parents`	`bool`	`true`	Create parent directories if needed

Output

Field	Type	Description
`ok`	`bool`	`true` if created
`path`	`str`	Absolute path of the created directory
`error`	`str`	Error message on failure

copy_file

Copy a file to a new location.

Input

Field	Type	Default	Description
`source`	`str`	required	Source file path
`destination`	`str`	required	Destination path

Output

Field	Type	Description
`ok`	`bool`	`true` if copied
`source`	`str`	Source path
`destination`	`str`	Destination path
`error`	`str`	Error message on failure

Notes

Preserves file metadata (timestamps, permissions) via shutil.copy2
Automatically creates the destination directory if it doesn't exist

move_file

Move or rename a file or directory.

Input

Field	Type	Default	Description
`source`	`str`	required	Source path
`destination`	`str`	required	Destination path

Output

Field	Type	Description
`ok`	`bool`	`true` if moved
`source`	`str`	Original path
`destination`	`str`	New path
`error`	`str`	Error message on failure

Tips

All path inputs support ~ expansion (e.g., ~/Documents/file.txt)
read_file with include_line_numbers: true is ideal for code review -- the LLM can reference specific line numbers
Use read_file_lines for large files to avoid loading the entire file into memory
write_file with create_dirs: true means you never need to call create_directory separately

Files Tool

On this page