Finding, organizing and cleaning up files
FileHop also supplies the file-management steps around a conversion or editing task. These operations are useful when an agent must first locate the right inputs, estimate the job, organize outputs and preserve a recovery path.
Choose the search mode
| Need | Tool | What to check |
|---|---|---|
| Know the contents of a particular directory | list_files | Name-sorted listing, optional glob and recursion, nextOffset for continuation |
| Find likely files by name across shared folders | file_search | Ranked indexed search, typo/accent handling and filters; indexComplete indicates indexing coverage |
| Find words inside documents or filenames while walking a folder | search_files | Separate name and content criteria; content search includes supported PDF, Word, PowerPoint and Excel text |
| Estimate a folder’s contents before bulk work | folder_summary | Sizes/counts by kind/extension, largest/newest files, depth, empties, skipped/truncated entries |
| Inspect selected files precisely | file_info, file_read | Metadata and format details; use format-specific tools for deeper native structure |
For file_search, supported query filters include type:pdf, type:image, type:folder, ext:md, size:>10mb, date:2026-01-01 and date:week. The filename index is built on first use and currently capped at 100,000 files per folder. Search results from an incomplete index are not proof that no other file exists.
search_files content hits are bounded snippets, not complete documents: it returns up to five matching lines per file, and max_results counts files. Its traversal normally skips hidden entries and build/dependency/version-control directories; inspect the schema and returned skip/truncation data. Image-only scans do not gain recognized text merely because the search supports PDF files.
list_files flags symbolic links and does not follow them. Folder summaries also omit links/hidden entries and stop at a bounded entry count. Do not claim a complete disk inventory when a tool reports incomplete coverage.
Find duplicate files and similar photos
find_duplicates accepts shared folders and/or explicit files. Recursive scanning defaults on and hidden entries are skipped. Results distinguish:
groups: identical-content duplicates, with a suggestedkeeppath and other copies.similarImages: visually similar images that are not byte-identical, such as resized or re-saved versions.
The keep suggestion is guidance, not proof that the other copies are unnecessary. A smaller similar photo may be a distinct edited deliverable. Review before deleting. max_groups defaults to 100 and can be raised to 500; truncated, group totals and reported reclaimable bytes may describe more matches than the visible groups. Do not act on unseen groups from a summary count.
find_empty finds zero-byte files and empty folders, with bounded results. Empty files can be intentional. Both cleanup-discovery tools are read-only; they do not remove anything automatically.
Organize and recover
create_folder creates missing parents and leaves existing directories alone. copy_files handles recursive copies, and move_files supports moves including across drives. They avoid overwriting collisions and return actual destination paths.
rename_files takes a new name, not a path. An existing destination name is refused; case-only renames are supported. Rename and move have safeguards around shared roots and FileHop workspace directories. Inspect per-item results rather than assuming the whole group moved or was renamed.
trash_files uses the OS Trash/Recycle Bin rather than permanent deletion. trash_list exposes eligible items from shared folders, and restore_files restores by original path (the newest matching trashed item). If that original path is occupied, restoration uses a unique name. Read the returned location instead of assuming an old link now points to the restored file.
Choose output locations using workspace_folder where appropriate: user-facing outputs, intermediates in scratch, and diagnostic logs have distinct purposes. Do not treat scratch previews or temporary speech files as permanent deliverables.
Resume without repeating work
Use activity_log to find earlier outputs and partial failures. Use context_read to inspect review notes and decisions associated with a file. context_write adds/replies/resolves comments without changing file bytes; this works even when the underlying file is read-only.
Content edits made by FileHop participate in supported file history. If using another editor, capture history_checkpoint before and after meaningful changes. When the user needs both versions, history_copy writes a retained earlier state to a new file instead of replacing the current one.
For a continued human/agent task, attach sources, working files and outputs to a review session and preserve the actual returned paths. A task attachment organizes work; it does not add filesystem permission or turn every external action into an audited FileHop operation.