Box
OfficialConnect AI agents to enterprise content in Box for search, AI queries, and file operations.
Tools (21)
who_am_i
Returns detailed information about the currently authenticated Box user. This tool provides comprehensive user profile data including basic identification, contact information, role details, and account settings. No input parameters are required as it retrieves information for the authenticated user making the request. This tool is essential for understanding the current user context, verifying authentication status, and obtaining user-specific information for personalization or access control purposes. It's particularly useful when building user-aware applications or when you need to identify the current user's permissions and organizational role. The response includes core user attributes such as ID, name, email, login, role, job title, and additional account details like space usage, language preferences, and timezone settings. <examples> Get current user information: <input> {} </input> </examples>
search_folders_by_name
Searches for folders by name within Box using keyword matching. This tool helps locate specific folders by their names and can be scoped to search within a particular parent folder. Returns basic folder information including ID, type, and name for each matching folder. The search performs a keyword-based match against folder names and can be limited to search within a specific ancestor folder. This is particularly useful for navigating complex folder structures, finding project folders, or locating organizational folders by name patterns. The tool uses Box's search API with folder type filtering, ensuring only folders (not files) are returned in results. Search results are limited to preserve performance and can be paginated using the limit parameter. **Date Range Filters:** Date range filters properties of the input schema: created_at_range, updated_at_range, deleted_at_range. Use comma-separated RFC3339 timestamps. **Format:** "start_date,end_date" where: - Omit start date to search all folders before end date: ",2023-12-31T23:59:59Z" - Omit end date to search from start date to now: "2023-01-01T00:00:00Z," - Both dates for specific range: "2023-01-01T00:00:00Z,2023-12-31T23:59:59Z" **Current Time Reference:** 2026-01-27T19:08:09.352Z <examples> Basic folder search: <input> { "folder_name": "Project Documents", "limit": 30 } </input> Search within specific parent folder: <input> { "folder_name": "2024 Reports", "ancestor_folder_id": "123456789", "limit": 50 } </input> Search for folders with partial name match: <input> { "folder_name": "Finance", "limit": 20 } </input> Limited results search: <input> { "folder_name": "Marketing Campaign", "ancestor_folder_id": "987654321", "limit": 10 } </input> Search in root directory and limit results by date: <input> { "folder_name": "Shared Resources", "created_at_range": "2023-01-01T00:00:00Z,2023-12-31T23:59:59Z" } </input> </examples>
list_folder_content_by_folder_id
Lists files, folders, and web links contained in a folder. Returns a paginated list of items with at least fields. Fields (id, type, name, etag) are always returned. Use folder_id "0" for the root folder. Supported fields include: id, type, name, etag, sequence_id, sha1, content_created_at, content_modified_at, created_at, created_by, modified_at, modified_by, owned_by, parent, path_collection, size, trashed_at, item_status, description, shared_link, classification, comment_count, disposition_at, expires_at, extension, has_collaborations, is_accessible_via_shared_link, is_associated_with_app_item, is_externally_owned, is_package, lock, metadata, permissions, representations, shared_link_permission_options, tags, uploader_display_name, version_number, watermark_info, file_version. <examples> Basic folder listing: <input> { "folder_id": "0", "limit": 50 } </input> List with specific fields: <input> { "folder_id": "123456789", "fields": ["id", "name", "type", "size", "modified_at", "created_by"], "limit": 100 } </input> Paginated listing: <input> { "folder_id": "987654321", "fields": ["id", "name", "type", "path_collection"], "limit": 30, "offset": 60 } </input> </examples>
search_files_keyword
Searches for files using keywords and supports metadata filters, file extension filtering (without dots), and field selection. Maps to Box's searchForContent API with comprehensive filtering capabilities. The response always includes 4 core fields: id, name, description, and type. The 'fields' parameter allows you to request additional fields beyond these core ones. All requested fields (core + additional) will be included in the API request and returned in the response. **Available Additional Fields:** fileVersion, sha1, contentCreatedAt, contentModifiedAt, createdAt, createdBy, modifiedAt, modifiedBy, ownedBy, parent, pathCollection, purgedAt, sharedLink, size, trashedAt, classification, commentCount, dispositionAt, expiresAt, extension, hasCollaborations, isAccessibleViaSharedLink, isAssociatedWithAppItem, isExternallyOwned, isPackage, lock, metadata, permissions, representations, sharedLinkPermissionOptions, tags, uploaderDisplayName, watermarkInfo **Date Range Filters:** Date range filters properties of the input schema: created_at_range, updated_at_range, deleted_at_range. Use comma-separated RFC3339 timestamps. **Format:** "start_date,end_date" where: - Omit start date to search all items before end date: ",2023-12-31T23:59:59Z" - Omit end date to search from start date to now: "2023-01-01T00:00:00Z," - Both dates for specific range: "2023-01-01T00:00:00Z,2023-12-31T23:59:59Z" **Current Time Reference:** 2026-01-27T19:08:09.350Z <examples> Basic keyword search (returns core fields only): <input> { "query": "contract agreement", "limit": 50 } </input> Advanced search with additional fields: <input> { "query": "quarterly report", "file_extensions": ["pdf", "docx"], "ancestor_folder_id": "123456789", "fields": ["createdAt", "modifiedAt", "size", "createdBy"] } </input> Searching by date: <input> { "query": "quarterly report", "file_extensions": ["pdf", "docx"], "ancestor_folder_id": "123456789", "created_at_range”: "2023-01-01T00:00:00Z,2023-12-31T23:59:59Z", "fields": ["createdAt"] } </input> Search with metadata filters and additional fields: <input> { "query": "invoice", "file_extensions": ["pdf"], "limit": 30, "fields": ["contentCreatedAt", "pathCollection", "metadata"], "mdfilters": [ { "scope": "enterprise", "templateKey": "invoiceTemplate", "filters": { "amount": { "gt": 1000, "lt": 5000 }, "status": "approved", "department": "finance" } } ] } </input> Multi-template metadata search with custom fields: <input> { "query": "project document", "fields": ["modifiedBy", "sharedLink", "tags", "permissions"], "mdfilters": [ { "scope": "enterprise", "templateKey": "projectTemplate", "filters": { "priority": "high", "deadline": { "gt": "2024-01-01" } } }, { "scope": "global", "templateKey": "reviewTemplate", "filters": { "reviewer": "john.doe@company.com" } } ] } </input> </examples>
get_file_content
Extracts and returns file content in text format for files under 50MB. This tool processes file content to provide only the readable text, with built-in file size validation and performance optimization. If the file does not have a text representation or the representation is not available then an error will be returned. Using this tool is preferred over the ai_qa_single_file tool since it is faster and more efficient, but it only works for files with text representations such as PDFs, documents, spreadsheets, presentations, code, etc. **Key Features:** - Text representation extraction from various file formats - 50MB file size limit enforcement - Clear error messages for unsupported operations <examples> Extract text content from a file: { "file_id": "123456789", } <output> { "content": [ { "type": "text", "text": "This is the extracted text content from the file..." } ] } </output> </examples>
list_tasks
Lists all tasks associated with a specific file. This tool retrieves task information including task details, message, status, and completion rule, due date from the Box platform. Tasks in Box are used to assign work to users on files, allowing for collaboration and workflow management. This tool provides access to all tasks assigned to a particular file, helping with project management and task tracking. The response includes comprehensive task details such as task type, assignee information, due dates, completion status, and any associated comments or messages. <examples> List tasks for a file: <input> { "file_id": "1234567890" } </input> </examples>
get_file_details
Gets comprehensive file information from Box. Returns essential fields by default (id, name, extension, createdBy, modifiedBy, createdAt, modifiedAt). Use 'fields' parameter to request additional properties. **Common useful fields:** size, description, tags, metadata, permissions, shared_link, parent, path_collection, file_version, sha1, lock, classification, comment_count, has_collaborations, representations, watermark_info, uploader_display_name, content_created_at, content_modified_at, item_status, expires_at, trashed_at. <examples> Basic file info: <input>{"file_id": "123456789"}</input> File with metadata and permissions: <input> { "file_id": "987654321", "fields": ["id", "name", "size", "permissions", "tags", "metadata", "shared_link"] } </input> Detailed file analysis: <input> { "file_id": "555666777", "fields": ["id", "name", "description", "file_version", "sha1", "path_collection", "classification", "comment_count", "has_collaborations"] } </input> </examples>
get_folder_details
Retrieves comprehensive information about a folder in Box. Returns essential fields by default (id, name, createdBy, modifiedBy, createdAt, modifiedAt). Use 'fields' parameter to request additional properties. **Common useful fields:** size, description, tags, metadata, permissions, shared_link, parent, path_collection, folder_upload_email, has_collaborations, allowed_invitee_roles, can_non_owners_invite, can_non_owners_view_collaborators, is_collaboration_restricted_to_enterprise, classification, allowed_shared_link_access_levels, content_created_at, content_modified_at, item_status, sync_state, watermark_info, trashed_at. **Note:** Only request 'item_collection' when the user explicitly asks for folder contents. Use 'list_folder_content_by_folder_id' for browsing folder items instead. <examples> Basic folder info: <input>{"folder_id": "123456789"}</input> Folder with permissions and collaboration settings: <input> { "folder_id": "987654321", "fields": ["id", "name", "size", "permissions", "can_non_owners_invite", "has_collaborations"] } </input> Detailed folder analysis with settings: <input> { "folder_id": "555666777", "fields": ["id", "name", "description", "path_collection", "folder_upload_email", "allowed_invitee_roles", "classification", "shared_link", "tags"] } </input> </examples>
upload_file
Uploads a new file to Box. This tool creates a new file in Box using the provided text content. The file name including the extension must be provided and the extension must match the file content. A parent folder ID can optionally be provided to determine where the new file should be created. The metadata details of the newly uploaded file are returned in response. If a file already exists with the same name, the tool will return an error. **Key Features:** - File creation with text content - Supported file extensions: txt, md, html, svg, xml, csv, json, js, ts, py, sh - If the file extension is invalid, a .txt file will be created <examples> Upload a file to Box: { "file_name": "example.md", "file_content": "#This is my example markdown file", "parent_folder_id": "0", } <output> { "content": [ { "type": "text", "text": "{"file_link": "https://example.app.box.com/file/123456789", "file_id": "123456789", "file_name": "example.md", "size": 100, "created_at": "2025-01-01T00:00:00Z"}" } ] } </output> </examples>
upload_file_version
Upload new file version by providing the entire file contents to Box. This tool updates an existing file's version in Box using the given file ID and content. The file ID must correspond to an existing file; otherwise, an error will be returned. Upon success, the metadata details of the updated file version are returned in the response. **Key Feature:** - Update file version with text content <examples> upload a new file version in Box: { "file_id": "123", "file_content": "#This is my example markdown file", } <output> { "content": [ { "type": "text", "text": "{"file_id": "123", "file_name": "example.md", "size": 100, "created_at": "2025-01-01T00:00:00Z"}" } ] } </output> </examples>
create_folder
Creates new folders in Box. <examples> Create folder in root: <input> { "name": "Project Documents" } </input> Create folder in specific parent: <input> { "name": "Q4 Reports", "parent_folder_id": "123456789" } </input> </examples>
list_hubs
Lists all hubs accessible to the current user with pagination support. Provides an overview of available collaborative workspaces and their basic information. Hubs in Box are collaborative workspaces that organize content around specific topics, projects, or teams. This tool helps discover what hubs you have access to, making it easy to find the right collaborative space for your work. **Key Features:** - Lists all accessible hubs for the authenticated user - Supports pagination with configurable limits and markers - Returns essential hub information including ID, type, and title - Efficient retrieval with adjustable result limits (1-1000) <examples> List all accessible hubs with default settings: <input> { "limit": 50 } </input> List hubs with custom pagination: <input> { "limit": 30, "marker": "next_marker_from_previous_response" } </input> </examples>
get_hub_details
Retrieves comprehensive information about a specific hub including metadata, creation details, and administrative information. Provides complete hub context for understanding ownership, timing, and purpose. This tool is essential for understanding hub context, ownership, and management information. It provides the complete picture of a hub's properties, helping users understand when it was created, by whom, and its current status. **Key Features:** - Retrieves detailed hub information including title, description, and metadata - Provides creation and modification timestamps - Shows hub ownership and creator information - Returns complete hub context for administrative and management purposes <examples> Get detailed information about a specific hub: <input> { "hub_id": "12345" } </input> </examples>
get_hub_items
Retrieves all items within a specific hub including files, folders, and web links. Essential for exploring the contents of collaborative workspaces and understanding what resources are available in a hub. This tool provides comprehensive access to hub contents with pagination support, allowing you to browse through all materials that have been added to a collaborative workspace. Perfect for content discovery and hub content management. **Key Features:** - Retrieves all items (files, folders, web links) within a specific hub - Supports pagination for hubs with large amounts of content - Returns detailed item information including names, types, and IDs - Configurable result limits for efficient data retrieval <examples> Get items in a specific hub: <input> { "hub_id": "12345" } </input> Get hub items with pagination: <input> { "hub_id": "67890", "limit": 50, "marker": "next_marker_value" } </input> Get first 25 items from a hub: <input> { "hub_id": "11111", "limit": 25 } </input> </examples>
create_hub
Creates new collaborative hubs for organizing content around specific topics, projects, or teams. Enables the establishment of new collaborative workspaces with customizable titles and descriptions. This tool is essential for setting up new collaborative spaces where teams can organize, share, and work together on related content. Hubs serve as central gathering points for all materials related to a particular initiative or project. **Key Features:** - Creates new hubs with custom titles and optional descriptions - Establishes collaborative workspaces for team projects - Returns complete hub information upon successful creation - Supports both minimal (title-only) and detailed hub creation <examples> Create a simple hub with title only: <input> { "title": "Marketing Team Hub" } </input> </examples>
add_items_to_hub
Adds files, folders, or web links to a specific hub, enabling content organization within collaborative workspaces. Essential for building and curating hub content by adding relevant materials to the collaborative space. This tool enables the population of hubs with relevant content, making it easy to organize materials within collaborative workspaces. You can add multiple items at once, supporting efficient hub content management and organization. **Key Features:** - Adds multiple items (files, folders, web links) to hubs in a single operation - Supports batch operations for efficient content organization - Works with all Box content types: files, folders, and web links - Provides confirmation of successful additions with detailed results **Supported Item Types:** - `file`: Box files of any type - `folder`: Box folders and their contents - `web_link`: External web links and bookmarks <examples> Add a single file to a hub: <input> { "hub_id": "12345", "items": [ {"id": "98765", "type": "file"} ] } </input> Add multiple items to a hub: <input> { "hub_id": "12345", "items": [ {"id": "98765", "type": "file"}, {"id": "54321", "type": "folder"}, {"id": "11111", "type": "web_link"} ] } </input> Add resources to a team hub: <input> { "hub_id": "55555", "items": [ {"id": "111111", "type": "folder"}, {"id": "222222", "type": "web_link"}, {"id": "333333", "type": "file"} ] } </input> </examples>
create_file_comment
Creates a new comment on a specific file. This tool allows you to add comments to files for collaboration, feedback, or documentation purposes. Comments are visible to all users with access to the file and can be used for team communication and file annotation. The message can include special characters, line breaks, and Unicode characters. The tool returns complete comment information including metadata about the comment creation, author, and timestamps. <examples> Basic file comment: <input> { "file_id": "123456789", "message": "This document looks good overall. Please review the financial projections in section 3." } </input> Multi-line structured comment: <input> { "file_id": "777888999", "message": "Review Summary:\n\nContent: Excellent\nStructure: Well organized\nFormatting: Minor issues\nCitations: Missing sources\n\nOverall: Good work, please address the citations before final submission." } </input> </examples>
update_file_properties
Updates file metadata: name, description, tags, and collections. **Updatable fields:** - `name` - File name with extension (max 255 chars). **IMPORTANT: Always preserve the original file extension unless explicitly instructed to change it.** - `description` - File description (max 256 chars) - `tags` - Tags array (max 100) - `collections` - Collections array with format [{"id": "collection_id"}] <examples> Rename file: <input>{"file_id": "123456789", "name": "Q1-Report-2024.pdf"}</input> Update description and tags: <input> { "file_id": "987654321", "description": "Q1 2024 financial report", "tags": ["finance", "2024"] } </input> Multiple updates: <input> { "file_id": "444555666", "name": "Updated-Doc.docx", "tags": ["project"], "collections": [{"id": "98765"}] } </input> </examples>
update_folder_properties
Updates folder metadata: name, description, tags, and collections. **Updatable fields:** - `name` - Folder name (max 255 chars, no / \ . .. or leading/trailing spaces) - `description` - Folder description (max 256 chars) - `tags` - Tags array (max 100) - `collections` - Collections array with format [{"id": "collection_id"}] <examples> Rename folder: <input>{"folder_id": "123456789", "name": "Q1 2024 Reports"}</input> Update description and tags: <input> { "folder_id": "987654321", "description": "Q1 2024 financial reports", "tags": ["finance", "2024"] } </input> Multiple updates: <input> { "folder_id": "444555666", "name": "Project Folder", "tags": ["project"], "collections": [{"id": "98765"}] } </input> </examples>
update_hub
Updates the title or description of a specific hub. This tool allows you to modify hub settings including title and description to keep hub information current and relevant. You can update one or more properties of a hub by providing the hub ID and the fields you want to change. Only the fields you specify will be updated; others remain unchanged. <examples> Update hub title: <input> { "hub_id": "12345", "title": "Updated Marketing Team Hub" } </input> Update both title and description: <input> { "hub_id": "12345", "title": "Q4 Planning Hub", "description": "Collaborative workspace for Q4 strategic planning and resource coordination" } </input> Update only description: <input> { "hub_id": "67890", "description": "Updated project description with new requirements and objectives" } </input> </examples>
list_file_comments
Lists all comments on a specific file. Returns a paginated list of comments with configurable fields. Default fields (id, type, message, created_by, created_at) are always returned, but you can specify additional fields as needed. Supported fields include: id, type, message, created_at, created_by, modified_at, tagged_message, and any other comment-related fields supported by the Box API. Use pagination parameters (limit/offset) to handle files with many comments efficiently. <examples> Basic file comments listing: <input> { "file_id": "123456789", "limit": 50 } </input> List with specific fields: <input> { "file_id": "987654321", "fields": ["id", "message", "created_at", "created_by", "modified_at"], "limit": 100 } </input> Paginated comments listing: <input> { "file_id": "555666777", "fields": ["id", "type", "message", "tagged_message", "created_by"], "limit": 25, "offset": 50 } </input> </examples>