Overview

Tool Name

filesystem_tools

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

  1. read_file: Read file content with automatic format detection and optional byte limit.
  2. read_text_file: Read text files with encoding and optional line numbering.
  3. edit_file: Modify files by replacing, inserting, appending, or deleting at line level.
  4. read_media_file: Access binary media content or metadata in safe formats.
  5. read_multiple_files: Batch read many files with optional shared encoding and metadata.
  6. write_file: Create or overwrite files with optional directory creation and encoding.
  7. directory_tree: Generate a visual tree of directories with depth control.
  8. create_directory: Create folders with optional recursion and permissions.
  9. list_allowed_directories: Show the directories your environment permits you to access.
  10. list_directory_with_sizes: List directory entries and compute sizes, optionally recursive.
  11. move_file: Move or rename files and directories with optional overwrite.
  12. search_files: Search by name, content, extension, or regex across a path.
  13. get_file_info: Return metadata such as size, timestamps, and permissions.
  14. 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.

Input Parameters for Each Function

read_file

NameDefinitionFormat
file_pathAbsolute or relative path to the file.String
encodingText encoding used when decoding content.String
max_bytesMaximum bytes to read for large files.Integer
Set max_bytes when sampling logs or very large files to improve responsiveness.

read_text_file

NameDefinitionFormat
file_pathPath to the text file.String
encodingCharacter encoding, default UTF-8.String
line_numbersInclude line numbers in the returned text.Boolean

edit_file

NameDefinitionFormat
file_pathPath to the file to modify.String
line_numberLine number to target for the operation.Integer
new_contentReplacement or inserted content.String
operationOne of replace insert append delete.String
For multi-line inserts or replaces, include newline characters in new_content as needed.

read_media_file

NameDefinitionFormat
file_pathPath to the binary media file.String
return_formatOne of base64 binary metadata for safe retrieval.String

read_multiple_files

NameDefinitionFormat
file_pathsArray of file paths to read.List
encodingText encoding for all files when applicable.String
include_metadataInclude file metadata with each result.Boolean

write_file

NameDefinitionFormat
file_pathDestination path to create or overwrite.String
contentText content to write.String
encodingText encoding used for writing.String
create_directoriesCreate parent folders if they do not exist.Boolean

directory_tree

NameDefinitionFormat
directory_pathRoot directory for tree generation.String
max_depthLimit traversal depth.Integer
show_hiddenInclude hidden files and directories.Boolean

create_directory

NameDefinitionFormat
directory_pathDirectory path to create.String
recursiveCreate missing parents.Boolean
permissionsOctal 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

NameDefinitionFormat
directory_pathDirectory to list.String
recursiveInclude contents of subdirectories.Boolean
sort_byOne of name size date type.String

move_file

NameDefinitionFormat
source_pathCurrent file or folder path.String
destination_pathTarget path or new name.String
overwriteOverwrite if destination exists.Boolean

search_files

NameDefinitionFormat
search_pathDirectory to search within.String
search_patternPattern to match text, names, or extensions.String
search_typeOne of name content extension regex.String
recursiveSearch subdirectories.Boolean
case_sensitiveIf 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

NameDefinitionFormat
file_pathPath to the file.String
include_permissionsInclude permission bits in the response.Boolean
include_checksumsCompute checksums for integrity checks.Boolean

list_directory

NameDefinitionFormat
directory_pathDirectory to list.String
filter_patternWildcard or regex filter for names.String
show_hiddenInclude hidden files.Boolean
Editing or moving system files can break running processes. Validate targets and keep backups for critical paths.

Use Cases

  1. Config management
    • Update YAML or JSON settings across environments with read_text_file and edit_file.
  2. Log triage
    • Sample the last megabytes of a large log using read_file with max_bytes.
  3. Repo structuring
    • Create a new project skeleton with create_directory and verify with directory_tree.
  4. Code search
    • Find usages of a function name across a codebase with search_files search_type: "content".
  5. Governance checks
    • Pull get_file_info with checksums for release packaging or audit trails.

Workflow/How It Works

  1. Inspect or search using list_directory, list_directory_with_sizes, or search_files.
  2. Read content with read_text_file or read_file. For binaries, use read_media_file.
  3. Modify with edit_file or write new content with write_file and optional create_directories.
  4. Restructure with move_file or create_directory, then visualize using directory_tree.
  5. 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

  1. All operations respect OS permissions and may fail without proper access.
  2. Large files can consume significant memory or time to process. Use limits and sampling.
  3. Network mounted volumes may perform differently than local disks.
  4. Encoding detection is best effort and may be inaccurate for mixed content files.
  5. 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.