Overview
Tool Name
Purpose
The file_manager_tools provide unified file operations across the platform. Use them to upload or register files, attach them to entities like projects or threads, preview large text safely, create download links, and streamline Git to storage workflows with a single call.Functions Available
All items below are actions of file_manager_tool.
UPLOAD_FILE: Upload a new text or binary file and optionally attach it immediately.REGISTER_EXISTING_FILE: Register a file that already exists on disk so it is tracked by the system.REGISTER_FILE_FROM_STORAGE: Register a file from a storage path and assign a friendly filename.SAVE_FROM_GIT: Copy from repo to managed storage, register, and attach in one efficient call.LIST_FILES: List files with filters such as project, data agent, thread, or index.GET_FILE_INFO: Return metadata for a file by id.GET_FILE_CONTENT: Read text content with pagination by lines or characters.GET_FILE_BY_PATH: Resolve a file record using an absolute storage path.ATTACH_FILE: Attach a registered file to a specific entity.DETACH_FILE: Remove an entity association without deleting the file.DOWNLOAD_FILE: Create a safe download link token for user delivery.DELETE_FILE: Permanently delete a file.
Key Features
Upload and Register
Add new files or register existing ones with rich metadata.
Attach to Entities
Link files to projects, todos, data agents, threads, messages, or indices for traceability.
Search and Filter
Find files quickly with scoped filters across related entities.
Read and Preview
Page through large text or code safely by lines or characters.
Save from Git
One call to save from repo, register, and attach for fast handoffs.
Share Securely
Generate expiring download links for stakeholders.
Input Parameters for Each Function
file_manager_tool
UPLOAD_FILE
| Name | Definition | Format |
|---|---|---|
| action | Must be UPLOAD_FILE. | String |
| filename | Descriptive filename. | String |
| text_content | Plain text content to store. | String |
| content | Base64 payload for binaries. | String |
| mime_type | MIME type for correct handling. | String |
| entity_type | Entity to attach on upload. | String |
| entity_id | Target entity id. | String |
Use descriptive filenames that encode purpose, owner, and date to improve discoverability in
LIST_FILES.LIST_FILES
| Name | Definition | Format |
|---|---|---|
| action | Must be LIST_FILES. | String |
| filters | Filter object. Start with {"bot": "<bot_id>"} or a project id. | Object |
GET_FILE_INFO
| Name | Definition | Format |
|---|---|---|
| action | Must be GET_FILE_INFO. | String |
| file_id | Unique file identifier. | String |
GET_FILE_CONTENT
| Name | Definition | Format |
|---|---|---|
| action | Must be GET_FILE_CONTENT. | String |
| file_id | Unique file identifier. | String |
| pagination_mode | lines, chars, or null for chunk based. | String |
| start | Zero based offset for the chosen mode. | Integer |
| count | Number of lines or chars to return. | Integer |
Prefer
pagination_mode: "lines" for code or SQL, and pagination_mode: "chars" for prose or logs to keep previews snappy.GET_FILE_BY_PATH
| Name | Definition | Format |
|---|---|---|
| action | Must be GET_FILE_BY_PATH. | String |
| file_path | Absolute storage path to resolve. | String |
REGISTER_FILE_FROM_STORAGE
| Name | Definition | Format |
|---|---|---|
| action | Must be REGISTER_FILE_FROM_STORAGE. | String |
| filename | Friendly filename to display. | String |
| file_path | Path to file in storage. | String |
REGISTER_EXISTING_FILE
| Name | Definition | Format |
|---|---|---|
| action | Must be REGISTER_EXISTING_FILE. | String |
| file_path | Absolute path to existing file. | String |
| filename | Descriptive filename. | String |
ATTACH_FILE
| Name | Definition | Format |
|---|---|---|
| action | Must be ATTACH_FILE. | String |
| file_id | File to attach. | String |
| entity_type | One of project todo asset bot thread message index. | String |
| entity_id | Target id for the attachment. | String |
DETACH_FILE
| Name | Definition | Format |
|---|---|---|
| action | Must be DETACH_FILE. | String |
| file_id | File to detach. | String |
| entity_type | Entity type to remove. | String |
| entity_id | Target id to remove from. | String |
DOWNLOAD_FILE
| Name | Definition | Format |
|---|---|---|
| action | Must be DOWNLOAD_FILE. | String |
| file_id | File to create a download link for. | String |
DELETE_FILE
| Name | Definition | Format |
|---|---|---|
| action | Must be DELETE_FILE. | String |
| file_id | File to remove permanently. | String |
SAVE_FROM_GIT
| Name | Definition | Format |
|---|---|---|
| action | Must be SAVE_FROM_GIT. | String |
| source_path | Absolute path to the repo file. | String |
| target_path | Destination directory in managed storage. | String |
| target_filename | Optional new filename. | String |
| commit_message | Optional provenance message. | String |
| entity_type | Entity to auto attach. | String |
| entity_id | Target entity id. | String |
**Deletion is permanent. **Confirm backups or retention requirements before calling
DELETE_FILE.Use Cases
- Project evidence
- Attach specs and extracts to a project for review and sign off.
- Repo handoff
- Save a generated PDF from repo to storage and attach it to the current thread.
- Inventory discovery
- List and filter files by project or data agent to locate the latest assets quickly.
- Large log review
- Page through big SQL logs without loading the entire file.
- Stakeholder delivery
- Generate a download link for stakeholders to retrieve a produced report.
Workflow/How It Works
- Upload or register files with
UPLOAD_FILEorREGISTER_*. - Attach to the relevant entity with
ATTACH_FILEfor context. - Explore inventory via
LIST_FILESand fetch metadata usingGET_FILE_INFO. - Preview text safely with
GET_FILE_CONTENTand pagination. - Share externally with
DOWNLOAD_FILE. - Retire artifacts with
DETACH_FILEorDELETE_FILEwhen the lifecycle is complete.
Integration Relevance
- git_action to source inputs and save binaries with
SAVE_FROM_GIT. - project_manager_tools to keep artifacts tied to missions and todos.
- document_index_tools to index stored files for search and Q&A.
- artifact_manager_tools for generated outputs that later become managed files.
- google_drive_tools to export results and then register or attach them.
Configuration Details
- Use absolute paths for registration and ensure read or write permissions.
- Base64 encode binary payloads for
UPLOAD_FILE. - Choose precise MIME types for correct rendering and preview behavior.
- Filter hierarchically when listing files to avoid noisy result sets.
- Adopt clear filename conventions that encode purpose and entity context.
Limitations or Notes
- Very large files may hit upload or storage limits depending on policy.
- Git operations require network access and repo permissions.
- Entity attachments will fail if the target id is invalid.
- Binary corruption can occur if payloads are not base64 encoded correctly.
- Concurrent writes or deletes may require coordination to avoid conflicts.
Output
- Upload and Registration: File id, metadata summary, and storage location.
- Lists and Info: Arrays of file records with names, sizes, MIME, timestamps, and relationships.
- Content Preview: Text segments plus pagination fields
start,count,actual_count,has_more. - Attachments: Confirmation of attach or detach operations.
- Git Save: Commit info, registration details, and attachment confirmation.
- Download: Download token or path reference.
- Errors: Descriptive messages with remediation guidance.