> ## Documentation Index > Fetch the complete documentation index at: https://docs.bizzyco.ai/llms.txt > Use this file to discover all available pages before exploring further. # File Tools > Upload, download, search, and organize files in organization storage The Bizzy MCP server provides 8 tools for managing files and folders in organization storage. These tools are organized into two categories: files and folders. ## Files Tools for uploading, downloading, listing, searching, and deleting files. File content is exchanged as base64-encoded strings to support the MCP protocol. ### uploadFile Upload a file to organization storage with base64-encoded content. **Permission:** `files:write` **Parameters:** | Name | Type | Required | Description | | ------------- | --------------------- | -------- | ------------------------------------------------------------ | | `filename` | string | Yes | Name of the file (1-255 characters) | | `content` | string | Yes | Base64-encoded file content (max 10MB file size) | | `contentType` | string | Yes | MIME type of the file (e.g., `application/pdf`, `image/png`) | | `folderId` | string (UUID) \| null | No | Optional folder ID to place the file in | | `description` | string | No | Optional description of the file (max 5000 characters) | | `tags` | string\[] | No | Optional tags for the file (max 10) | **Returns:** Object with `success` boolean and a `file` object containing `id`, `filename`, `size`, `contentType`, and `folderId`. *** ### downloadFile Download a file from organization storage as base64-encoded content. **Permission:** `files:read` **Parameters:** | Name | Type | Required | Description | | -------- | ------------- | -------- | ------------------------------ | | `fileId` | string (UUID) | Yes | The ID of the file to download | **Returns:** Object with a `file` metadata object (`id`, `filename`, `contentType`, `size`) and a `content` string containing base64-encoded file bytes. Downloads are gated by each file's `agentAccessEnabled` flag. Files with agent access disabled return an error. *** ### listFiles List files in organization storage with optional folder filtering and pagination. **Permission:** `files:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | --------------------- | -------- | ------- | --------------------------------------------------------------- | | `folderId` | string (UUID) \| null | No | - | Filter by folder ID (`null` for root level, omit for all files) | | `limit` | number | No | 10 | Number of files to return (1-100) | | `offset` | number | No | 0 | Pagination offset | | `sortOrder` | string | No | "desc" | Sort order by creation date (`asc` or `desc`) | **Returns:** ```json theme={null} { "files": [...], "count": 23, "limit": 10, "offset": 0 } ``` *** ### searchFiles Find files by name **or content**. `searchFiles` runs a hybrid full-text search that combines two signals and fuses them so a file matching on both ranks highest: * **Metadata** — filename, description, and tags. * **Content** — the text of the file's indexed pages (for files Bizzy has finished indexing). Returns ranked **file records** (not passages). Use `searchFiles` to locate files; use [`askFiles`](#askfiles) to answer a question from their contents. **Permission:** `files:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | --------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | Yes | - | Search query matched against filename, description, tags, and file content (1-255 characters) | | `limit` | number | No | 10 | Number of results to return (1-100) | | `offset` | number | No | 0 | Pagination offset | | `folderIds` | string\[] | No | - | Optional list of folder UUIDs to restrict the search to. When provided, only files inside the listed folders match — files at the root level (no folder) are excluded | **Returns:** ```json theme={null} { "files": [...], "count": 5, "query": "invoice", "limit": 10, "offset": 0 } ``` Results are limited to files with agent access enabled. A file excluded from content indexing still appears when its **name** matches — exclusion only removes it from content matching, not from search. `count` reflects the deduplicated union of metadata and content candidates within a bounded window (up to 500 matches per side), not an exhaustive tally. For large result sets, page through with `limit` and `offset`. *** ### askFiles New Answer a natural-language question using passages retrieved from the organization's indexed files. Returns ranked **citations** — each backed by a source file, page number (when available), and an excerpt — rather than whole file records. Use this when a question may be answered by uploaded documents, and always cite the returned files when synthesizing an answer. **Permission:** `files:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | --------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | Yes | - | Natural-language question to answer from file contents (1-1000 chars) | | `limit` | number | No | 10 | Maximum number of citations to return (1-50) | | `folderIds` | string\[] | No | - | Optional list of folder UUIDs to restrict retrieval to. When provided, only files inside the listed folders match — files at the root level (no folder) are excluded | **Returns:** Object with the echoed `query` and a `citations` array. Each citation contains `fileId`, `filename`, `pageNumber` (nullable), `snippet`, `score`, and `chunkIndex`. ```json theme={null} { "query": "What is the roofing warranty term?", "citations": [ { "fileId": "f4c1…", "filename": "warranty.pdf", "pageNumber": 3, "snippet": "Roofing warranty covers material defects for 25 years…", "score": 0.0328, "chunkIndex": 7 } ] } ``` Only files with agent access enabled and a completed indexing status are searched. Newly uploaded files become answerable once indexing finishes. *** ### deleteFile Delete a file from organization storage (soft delete). **Permission:** `files:delete` **Parameters:** | Name | Type | Required | Description | | -------- | ------------- | -------- | ---------------------------- | | `fileId` | string (UUID) | Yes | The ID of the file to delete | **Returns:** Object with `success` boolean, the deleted `file` object, and a `message` string. *** ## Folders Tools for organizing files into a folder hierarchy. Folders can be nested up to 5 levels deep. ### createFolder Create a new folder in organization storage with optional parent folder (max 5 levels deep). **Permission:** `folders:write` **Parameters:** | Name | Type | Required | Description | | ---------------- | --------------------- | -------- | ------------------------------------------------- | | `name` | string | Yes | Name of the folder (1-255 characters) | | `parentFolderId` | string (UUID) \| null | No | Optional parent folder ID (`null` for root level) | **Returns:** The created folder object. *** ### listFolders List folders in organization storage with optional parent folder filtering and pagination. **Permission:** `folders:read` **Parameters:** | Name | Type | Required | Default | Description | | ---------------- | --------------------- | -------- | ------- | ------------------------------------------------------------------------ | | `parentFolderId` | string (UUID) \| null | No | - | Filter by parent folder ID (`null` for root level, omit for all folders) | | `limit` | number | No | 10 | Number of folders to return (1-100) | | `offset` | number | No | 0 | Pagination offset | | `sortOrder` | string | No | "desc" | Sort order by creation date (`asc` or `desc`) | **Returns:** ```json theme={null} { "folders": [...], "count": 6, "limit": 10, "offset": 0 } ``` *** ## Next Steps Manage contacts and their associated data Learn how MCP clients authenticate to the server