Box tools for agents

Seventeen tools let an agent work directly against Box: search and read content, change it, and collaborate on it. They are separate from the Box pipeline source, which ingests Box content into a corpus — these tools act in Box at conversation time.

Every tool name carries the _20260723 version suffix, and the suffix is part of the identifier you configure. The bare family name (box_search) does not resolve to a tool.

Authentication

The Box tools take their credentials as arguments the agent never sees. There are two ways to authenticate:

• Developer or bearer token — set box_developer_token.
• Client Credentials Grant (CCG) — set all four of box_client_id, box_client_secret, box_subject_type (enterprise for the app's service account, or user), and box_subject_id (the enterprise id or managed user id to authenticate as).

box_developer_token takes precedence: when it is set, the client credentials are ignored. If neither a developer token nor all four CCG fields are present, the tool call fails asking for them. CCG tokens are minted and cached per credential set rather than re-minted on every call.

Optionally, box_as_user_id impersonates a managed user through Box's as-user header.

Set the credential wiring explicitly

All seventeen tools ship the same default argument_override, which points all six credential arguments at fixed locations on the agent:

Argument	Default reference
box_developer_token	agent.secrets.box_developer_token
box_client_secret	agent.secrets.box_client_secret
box_client_id	agent.metadata.box_client_id
box_subject_type	agent.metadata.box_subject_type
box_subject_id	agent.metadata.box_subject_id
box_as_user_id	agent.metadata.box_as_user_id

caution

None of these six references carries a fallback value, and every one of them must resolve before the session starts. Filling in only the arguments for the mode you use is not enough: the references for the other mode are still there, still unresolved, and the session fails with Failed to resolve eager references.

The two authentication modes are alternatives, so an agent should not need to provide all six values. The shipped defaults nevertheless require every reference to resolve. Override them with only the arguments needed by the selected mode. Set argument_override on each Box tool you attach and name only the arguments your chosen mode needs. A user-supplied argument_override replaces the shipped defaults wholesale rather than key by key, so the references you leave out are dropped rather than merged over — which is what you want here.

Developer or bearer token. Store the token as an agent secret named box_developer_token, then set:

{
  "box_developer_token": { "$ref": "agent.secrets.box_developer_token" }
}

Client Credentials Grant. Store the client secret as an agent secret named box_client_secret, put the rest in agent metadata, then set:

{
  "box_client_id": { "$ref": "agent.metadata.box_client_id" },
  "box_client_secret": { "$ref": "agent.secrets.box_client_secret" },
  "box_subject_type": { "$ref": "agent.metadata.box_subject_type" },
  "box_subject_id": { "$ref": "agent.metadata.box_subject_id" }
}

Add "box_as_user_id": { "$ref": "agent.metadata.box_as_user_id" } only if you impersonate a managed user — leaving it out is what keeps it optional. The non-sensitive values can be written as literals instead of references if you would rather not keep them in agent metadata. Keep the client secret and the developer token in agent secrets either way, so they are encrypted at rest and masked in API responses and session events.

The same rule applies when your credentials live somewhere else, such as a session secret holding a per-caller token. Whatever you set replaces all six defaults, so restate every credential argument you still need.

Finding and reading content

box_search_20260723

Searches files, folders, and web links. query is required and is free text matched against names, descriptions, file content, comments, and tags. Words combine with an implicit OR, uppercase AND, OR, and NOT act as operators, and double quotes match an exact phrase.

Narrow with type (file, folder, or web_link), file_extensions (for example "pdf,docx"), ancestor_folder_id (that folder and its subfolders), content_types (which fields to match: name, description, file_content, comments, tags), and created_at_range / updated_at_range, each an RFC 3339 "from,to" pair where either side may be empty.

limit defaults to 30 (maximum 200) and offset pages through results up to 9800. Each result carries id, type, name, size_bytes, modified_at, path, and parent_folder_id; web_link results also carry url. When next_offset is returned there are more results.

Box's search index lags brand-new uploads by a minute or two, so a file uploaded moments earlier may not appear yet.

box_list_folder_20260723

Lists the files and subfolders directly inside a folder. folder_id defaults to "0", the account root. limit defaults to 100 (maximum 1000). Paging is marker-based: when the response carries next_marker, repeat the call with marker set to it.

Each entry has id, type (file, folder, or web_link), name, size_bytes, and modified_at; web_link entries also carry url. Prefer box_search_20260723 when you know what you are looking for and this tool when exploring structure.

box_get_item_info_20260723

Returns a file's or folder's metadata: size_bytes, description, tags, path, parent_folder_id, created_at, modified_at, owner_login, and shared_link_url. Requires item_type (file or folder) and item_id.

Files additionally return sha1, version_number, and comment_count; folders return item_count. The sha1 lets you detect whether a file's content changed without downloading it.

box_read_file_20260723

Reads a document's text without downloading the raw file, requesting Box's markdown representation first and falling back to plain text. This is the preferred way to read a document: Office files, PDFs, Google formats, and text and code files all work. Images, media, and other binary files return an error — use box_get_file_20260723 for those.

file_id is required. Long documents are windowed: max_chars defaults to 50000 (maximum 1000000), and when has_more is true, call again with offset set to the returned next_offset.

box_get_file_20260723

Downloads a file's raw bytes into a session artifact, so it requires that artifact tools are available to the agent. Use it when you need the original bytes — images, binaries, exact copies, or re-uploading elsewhere.

file_id is required. Pass a version_id from box_list_file_versions_20260723 to download an older version, and filename to override the stored artifact's name. Returns artifact_id plus the file's name, mime type, size, and sha1.

box_list_file_versions_20260723

Lists a file's saved versions, newest first. limit defaults to 50 (maximum 1000), with offset paging. Each version carries id, version_number, sha1, size_bytes, modified_at, and the user who created it. Comparing version sha1s shows whether content actually changed between versions.

Version history requires a paid Box plan.

Changing content

box_upload_file_20260723

Uploads either text passed as content or the bytes of a session artifact named by artifact_id — provide one, not both. Use the artifact form for binary files or files generated earlier in the session.

Creates a new file named filename in parent_folder_id (default "0"), or, when file_id is set, uploads a new version of that existing file, preserving its id and version history. filename is required when creating a new file and optional when uploading a version.

If a file of the same name already exists in the folder, the error names the existing file's id — pass it as file_id to update that file instead. Returns the file's id, sha1, and version number.

box_create_folder_20260723

Creates a folder named name inside parent_folder_id (default "0"). Returns the new folder's id, name, and full path. If a folder of the same name already exists in the parent, the error names the existing folder's id so it can be reused rather than recreated.

box_update_item_20260723

Renames, moves, re-describes, or re-tags a file or folder in one call. Requires item_type and item_id plus at least one of new_name, new_parent_folder_id ("0" is the account root), description, and tags.

tags replaces the item's entire tag set. To add a tag, read the current tags with box_get_item_info_20260723 and pass them back along with the new one. A rename or move that collides with an existing item returns an error naming the conflicting item's id.

box_copy_item_20260723

Copies a file, or a folder with its entire subtree, into destination_folder_id ("0" for the account root). new_name renames the copy; without it the copy keeps the original name and Box rejects the call with item_name_in_use if the destination already holds that name. Large folder copies can take a while.

box_delete_item_20260723

Moves a file or folder to the Box trash. This is not a permanent deletion — box_restore_item_20260723 puts it back while it is still in the trash, subject to the enterprise's trash retention policy.

Trashing a folder that still has contents requires recursive set to true; without it Box rejects the call with folder_not_empty. Returns status trashed.

box_restore_item_20260723

Restores a trashed file or folder, using the same id it had before. It returns to where it was trashed from unless you redirect it: pass new_name when an item of that name now occupies the original location, and new_parent_folder_id when the folder it came from is gone. Restoring a folder restores everything inside it.

Once the enterprise's trash retention period expires the item is gone for good and the tool reports not_found.

Collaborating

box_add_collaboration_20260723

Invites a user or group to collaborate on a file or folder. Requires item_type, item_id, and role — one of editor, viewer, previewer, uploader, previewer uploader, viewer uploader, or co-owner.

Identify the invitee with exactly one of login (an email address; external users outside the enterprise are allowed), user_id, or group_id. send_notification defaults to false; set it true to have Box email the invitee. Returns the collaboration id, its status (accepted, or pending when the invitee must accept first), and the granted role.

box_shared_link_20260723

Creates, inspects, or removes a shared link. action is create, get, or remove.

On create, access is open (anyone with the link), company (people in the enterprise), or collaborators (only the item's collaborators), defaulting to the enterprise's default. password is valid only with open access, and can_download controls whether recipients can download the content. On get, the status is exists with the link fields or none when the item has no link. On remove, the status is removed.

Check effective_access before sharing a URL externally: enterprise policy can make it more restrictive than the access you requested.

box_add_comment_20260723

Posts a comment on a file's discussion. message is required, along with exactly one of file_id (a new top-level comment) or reply_to_comment_id (a reply to an existing comment, whose id comes from box_list_comments_20260723). Returns the new comment's id and creation time.

box_list_comments_20260723

Lists a file's comments with each comment's id, message, author_name, author_login, created_at, and is_reply. limit defaults to 100 (maximum 200), with offset paging — repeat the call with offset advanced by limit while total_count exceeds what you have read.

box_create_task_20260723

Creates a review or approval task on a file, optionally assigning it in the same call. file_id and message are required. action is review (the assignee approves or rejects) or complete (the assignee marks it done), defaulting to review.

Assign with at most one of assignee_login (email) or assignee_user_id; without either, the task is created unassigned. due_at is an RFC 3339 timestamp, and completion_rule is all_assignees or any_assignee. Returns the task id, plus the assignment id when an assignee was given.