Overview
Purpose
The filesystem_tools provide a comprehensive interface for local file and directory operations. Use them to read and write content, edit files by line, manage folders, search by name or content, visualize trees, and retrieve rich metadata for governance and troubleshooting.
Functions Available
read_file: Read file content with automatic format detection and optional byte limit.read_text_file: Read text files with encoding and optional line numbering.edit_file: Modify files by replacing, inserting, appending, or deleting at line level.read_media_file: Access binary media content or metadata in safe formats.read_multiple_files: Batch read many files with optional shared encoding and metadata.write_file: Create or overwrite files with optional directory creation and encoding.directory_tree: Generate a visual tree of directories with depth control.create_directory: Create folders with optional recursion and permissions.list_allowed_directories: Show the directories your environment permits you to access.list_directory_with_sizes: List directory entries and compute sizes, optionally recursive.move_file: Move or rename files and directories with optional overwrite.search_files: Search by name, content, extension, or regex across a path.get_file_info: Return metadata such as size, timestamps, and permissions.list_directory: Basic listing of directory contents with optional filters.
Key Features
Read and Write
Reliable text and binary I/O with encoding control and safe byte limits.
Edit in Place
Line-level edits for quick fixes and scripted refactors.
Organize Folders
Create, move, and visualize directory structures.
Search at Scale
Find by name, content, or regex across nested trees.
Know Your Files
Retrieve permissions, timestamps, sizes, and checksums when needed.
read_file
| Name | Definition | Format |
|---|
| file_path | Absolute or relative path to the file. | String |
| encoding | Text encoding used when decoding content. | String |
| max_bytes | Maximum bytes to read for large files. | Integer |
Set max_bytes when sampling logs or very large files to improve responsiveness.
read_text_file
| Name | Definition | Format |
|---|
| file_path | Path to the text file. | String |
| encoding | Character encoding, default UTF-8. | String |
| line_numbers | Include line numbers in the returned text. | Boolean |
edit_file
| Name | Definition | Format |
|---|
| file_path | Path to the file to modify. | String |
| line_number | Line number to target for the operation. | Integer |
| new_content | Replacement or inserted content. | String |
| operation | One of replace insert append delete. | String |
For multi-line inserts or replaces, include newline characters in new_content as needed.
| Name | Definition | Format |
|---|
| file_path | Path to the binary media file. | String |
| return_format | One of base64 binary metadata for safe retrieval. | String |
read_multiple_files
| Name | Definition | Format |
|---|
| file_paths | Array of file paths to read. | List |
| encoding | Text encoding for all files when applicable. | String |
| include_metadata | Include file metadata with each result. | Boolean |
write_file
| Name | Definition | Format |
|---|
| file_path | Destination path to create or overwrite. | String |
| content | Text content to write. | String |
| encoding | Text encoding used for writing. | String |
| create_directories | Create parent folders if they do not exist. | Boolean |
directory_tree
| Name | Definition | Format |
|---|
| directory_path | Root directory for tree generation. | String |
| max_depth | Limit traversal depth. | Integer |
| show_hidden | Include hidden files and directories. | Boolean |
create_directory
| Name | Definition | Format |
|---|
| directory_path | Directory path to create. | String |
| recursive | Create missing parents. | Boolean |
| permissions | Octal permission string like 755. | String |
list_allowed_directories
This function does not require parameters. It returns the set of directories that are safe to traverse in your environment.
list_directory_with_sizes
| Name | Definition | Format |
|---|
| directory_path | Directory to list. | String |
| recursive | Include contents of subdirectories. | Boolean |
| sort_by | One of name size date type. | String |
move_file
| Name | Definition | Format |
|---|
| source_path | Current file or folder path. | String |
| destination_path | Target path or new name. | String |
| overwrite | Overwrite if destination exists. | Boolean |
search_files
| Name | Definition | Format |
|---|
| search_path | Directory to search within. | String |
| search_pattern | Pattern to match text, names, or extensions. | String |
| search_type | One of name content extension regex. | String |
| recursive | Search subdirectories. | Boolean |
| case_sensitive | If true, matches are case sensitive. | Boolean |
Use search_type: "regex" with care. Anchor your patterns to reduce false positives and improve performance.
get_file_info
| Name | Definition | Format |
|---|
| file_path | Path to the file. | String |
| include_permissions | Include permission bits in the response. | Boolean |
| include_checksums | Compute checksums for integrity checks. | Boolean |
list_directory
| Name | Definition | Format |
|---|
| directory_path | Directory to list. | String |
| filter_pattern | Wildcard or regex filter for names. | String |
| show_hidden | Include hidden files. | Boolean |
Editing or moving system files can break running processes. Validate targets and keep backups for critical paths.
Use Cases
- Config management
- Update YAML or JSON settings across environments with
read_text_file and edit_file.
- Log triage
- Sample the last megabytes of a large log using
read_file with max_bytes.
- Repo structuring
- Create a new project skeleton with
create_directory and verify with directory_tree.
- Code search
- Find usages of a function name across a codebase with
search_files search_type: "content".
- Governance checks
- Pull
get_file_info with checksums for release packaging or audit trails.
Workflow/How It Works
- Inspect or search using
list_directory, list_directory_with_sizes, or search_files.
- Read content with
read_text_file or read_file. For binaries, use read_media_file.
- Modify with
edit_file or write new content with write_file and optional create_directories.
- Restructure with
move_file or create_directory, then visualize using directory_tree.
- Collect metadata using
get_file_info for validation and documentation.
Integration Relevance
- file_manager_tools to register and attach files once created or modified.
- git_action for versioning changes that originate on the filesystem.
- document_index_tools to index folders after writing or reorganizing content.
- project_manager_tools to tie filesystem operations to tasks or milestones.
- artifact_manager_tools to track generated outputs and link them back to runs.
Configuration Details
- Use platform appropriate path separators and avoid trailing spaces in paths.
- Default encoding is UTF-8. Specify encodings explicitly when working with legacy files.
- For permission fields, use standard octal strings such as
755 or 644.
- Recursive operations can be expensive on large trees. Apply
max_depth and filters.
Limitations or Notes
- All operations respect OS permissions and may fail without proper access.
- Large files can consume significant memory or time to process. Use limits and sampling.
- Network mounted volumes may perform differently than local disks.
- Encoding detection is best effort and may be inaccurate for mixed content files.
- Concurrent writers can cause conflicts. Coordinate long running edits and moves.
Output
- Reads: File content plus encoding info and optional metadata.
- Writes and Edits: Confirmation with file details and sizes.
- Listings: Entries with names, sizes, dates, and optional recursion summaries.
- Trees: A compact visual structure of folders and files.
- Search: Array of matches with paths and match context.
- Metadata: Permissions, timestamps, and checksums when requested.
