Box

Cloud files. List, search, upload, and organize files and folders, share links, manage collaborators, and read or set metadata.

Measured routing accuracy

54 golden cases replayed through the router over the whole index: measured over corpus ea4f12ad2948 (65 toolkits, 2283 tools indexed and 13 declared uncallable), 34 cases written by hand and 20 cases from the paraphrase pass. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all.

2 of the 36 action tools listed above are declared uncallable, so they are indexed nowhere and answer none of these cases. The counts here are scored over the other 34.

The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. just eval-live measures the same cases through the live reranker.

Authentication

Connect an entity with ConnectionsService.InitiateConnection, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only.

oauth2

Tools

36 action tools. The catalog-wide slug is box.<tool>, which is what search_tools returns and call_tool takes.

box.get_file

Get one Box file's own details by id: name, size, and when it last changed. Use when the user names a specific file. For its actual content, use download_file. For a file's structured fields instead of these basics, use get_metadata.

Class read (reads only). Scopes root_readonly. Calls GET /files/{{params.file_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "how big is this", "when was this last touched", "check the details on this item", "what are the basics on this document".

box.download_file

Download the raw content of a Box file by id. Use when the user wants to fetch, save, or read what's inside a file already in Box. For a quick visual preview instead of the full file, use get_thumbnail.

Class read (reads only). Scopes root_readonly. Calls GET /files/{{params.file_id}}/content.

Arguments:

Also retrieved by: "grab a copy of this", "save this to my computer", "fetch the actual bytes", "pull this down locally".

box.get_thumbnail

Get a small preview image for a Box file, when one can be rendered (photos, images, and many document types). Use when the user wants to see what a file looks like without downloading or opening it.

Class read (reads only). Scopes root_readonly. Calls GET /files/{{params.file_id}}/thumbnail.{{params.format}}.

Arguments:

Also retrieved by: "show me a small preview of this picture", "what does this image look like", "give me a quick look at this photo", "preview this without opening it".

box.upload_file

Create a new file in Box with the given content, inside a folder. Use when the user wants to add, save, or upload a document or note to Box. Content is base64-encoded. Fails if a file with that name already exists there; to add a version on top of one, use upload_new_version.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls POST /files/content.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "stash this note in my account", "put this text into a new document", "add a fresh item with this content", "save this write-up online".

box.upload_new_version

Upload new content for a file that already exists in Box, keeping its name and location and adding a new version. Use when the user wants to overwrite, update, or replace what's inside an existing Box file. Content is base64-encoded. Recover an older version with restore_file_version.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls POST /files/{{params.file_id}}/content.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "overwrite what's inside this", "replace the content in that document", "swap out what's currently there with a fresh copy", "add a new version on top of what's there".

box.rename_file

Rename a Box file, keeping its content and location. Use when the user wants to retitle or relabel a file already in Box. For putting it in a different folder instead, use move_file.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls PUT /files/{{params.file_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "retitle this document", "give this a better name", "this is labeled wrong, fix the name", "change what this is called".

box.move_file

Move a Box file into a different folder, keeping its name. Use when the user wants to relocate, file away, or reorganize something already in Box. For giving it a new name in place, use rename_file.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls PUT /files/{{params.file_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "relocate this somewhere else", "put this in a different location", "this is in the wrong place", "file this away properly".

box.copy_file

Duplicate a Box file into a folder, leaving the original in place. Use when the user wants their own copy or a template to build from. Optionally give the copy a new name.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls POST /files/{{params.file_id}}/copy.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "I want my own version of this", "duplicate this so I can edit it", "make a template from this", "clone this document".

box.delete_file

Move a Box file to the trash. Use when the user wants to remove or get rid of a file in Box. It stays recoverable there until someone empties it; bring it back with restore_trashed_file, or use permanently_delete_file to skip the trash for good.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes root_readwrite. Calls DELETE /files/{{params.file_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "get rid of this for good", "remove this, I don't need it anymore", "toss this old draft", "trash this item".

box.list_file_versions

List a Box file's past versions: each version id, size, and when it was saved. Use when the user asks about earlier versions or wants to recover something they changed. Bring one back with restore_file_version.

Class read (reads only). Scopes root_readonly. Calls GET /files/{{params.file_id}}/versions.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "show me the version history", "what did this look like before", "who edited this and when", "see the earlier saves of this".

box.restore_file_version

Make an older version of a Box file the current one. Use when the user wants to undo a change or bring back a version they lost. Requires the version id from list_file_versions.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls POST /files/{{params.file_id}}/versions/current.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "bring back an earlier version", "undo the last change to this", "I need the version from before", "roll this back to how it was".

box.restore_trashed_file

Bring a trashed Box file back to where it was. Use when the user wants to undelete or recover a file they, or someone else, moved to the trash. Optionally give it a new name or folder if the original spot is taken.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls POST /files/{{params.file_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "undelete this, I made a mistake", "bring this back from the trash", "I need that thing I just removed", "recover the item I trashed earlier".

box.permanently_delete_file

Erase a file from the Box trash for good, skipping the recovery window. Use when the user wants to permanently delete, purge, or empty out a file that is already in the trash. Cannot be undone.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes root_readwrite. Calls DELETE /files/{{params.file_id}}/trash.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "wipe this out for real, don't just trash it", "empty this out of the recycle bin", "purge this item completely", "I want this gone, no recovering it".

box.list_folder_items

List the files and folders directly inside a Box folder. Use for what's in this folder or browsing a known location. For finding something by name or keyword anywhere in the account, use search.

Class read (reads only). Scopes root_readonly. Calls GET /folders/{{params.folder_id}}/items.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what's in this folder", "browse this directory", "show me what's inside here", "what's stored in this location".

box.get_folder

Get one Box folder's own details by id: name, size, when it last changed, and how many items it holds. Use when the user names a specific folder. For what's inside it, use list_folder_items.

Class read (reads only). Scopes root_readonly. Calls GET /folders/{{params.folder_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "how many things are in this folder", "check the details on this directory", "when did this folder last change".

box.create_folder

Create a new folder in Box inside a parent folder. Use when the user wants to organize files into a new folder or directory in Box.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls POST /folders.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "make a new directory for this", "set up a place to keep these organized", "I need somewhere to put all this".

box.rename_folder

Rename a Box folder, keeping its contents and location. Use when the user wants to retitle or relabel a folder already in Box. For putting it inside a different folder instead, use move_folder.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls PUT /folders/{{params.folder_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "retitle this directory", "give this folder a better name", "relabel this collection".

box.move_folder

Move a Box folder into a different parent folder, keeping its name and contents. Use when the user wants to relocate or reorganize a folder already in Box. For giving it a new name in place, use rename_folder.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls PUT /folders/{{params.folder_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "relocate this whole directory", "put this folder somewhere else", "reorganize where this lives".

box.copy_folder

Duplicate a Box folder and everything in it into another folder, leaving the original in place. Use when the user wants their own copy of a whole folder structure to build from.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls POST /folders/{{params.folder_id}}/copy.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "I want my own version of this whole directory", "duplicate this folder structure", "clone everything in this collection".

box.delete_folder

Move a Box folder to the trash, along with everything in it. Use when the user wants to remove or get rid of a folder in Box. It stays recoverable there until someone empties it; erase it for good with permanently_delete_folder.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes root_readwrite. Calls DELETE /folders/{{params.folder_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "get rid of this whole directory", "remove this folder and everything in it", "trash this collection".

box.permanently_delete_folder

Erase a folder from the Box trash for good, skipping the recovery window. Use when the user wants to permanently delete, purge, or empty out a folder that is already in the trash. Cannot be undone.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes root_readwrite. Calls DELETE /folders/{{params.folder_id}}/trash.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "wipe this directory out for real", "empty this folder out of the recycle bin", "purge this collection completely".

box.search

Search the whole Box account by keyword, across files and folders. Use when the user wants to find or locate something by name or content rather than browse a folder they already know. Optionally scope the search to one folder or one item type.

Class read (reads only). Scopes root_readonly. Calls GET /search.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "find something by keyword", "look up an old document", "dig up anything mentioning the budget", "where did I save that".

box.create_shared_link_file

Create a link to a Box file that people outside Box, or without access, can open. Use when the user wants to share, send, or get a link for a file. Optionally protect it with a password or an expiry date. For a folder instead, use create_shared_link_folder.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls PUT /files/{{params.file_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "give me a link anyone can open", "I want a URL for this I can send someone", "generate a public link to this document".

box.create_shared_link_folder

Create a link to a Box folder that people outside Box, or without access, can open. Use when the user wants to share, send, or get a link for a whole folder. Optionally protect it with a password or an expiry date. For a single file instead, use create_shared_link_file.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls PUT /folders/{{params.folder_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "give me a link to this whole directory", "I want a URL for this folder I can send someone", "generate a public link to this collection".

box.get_shared_item

Open a Box shared link to see the file or folder it points to, without needing to already have access. Use when the user has a Box link someone sent them and wants to know what it is before opening it in Box.

Class read (reads only). Scopes root_readonly. Calls GET /shared_items.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what is this link someone sent me", "check what's behind this URL before I open it", "see what this shared link points to".

box.remove_shared_link_file

Disable the shared link on a Box file so it stops working. Use when the user wants to unshare, revoke, or kill a file's link, without touching the file itself. For a folder's link instead, use remove_shared_link_folder.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes root_readwrite. Calls PUT /files/{{params.file_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "kill that link I sent for this document", "shut off access through that URL", "stop that document's link from working".

box.remove_shared_link_folder

Disable the shared link on a Box folder so it stops working. Use when the user wants to unshare, revoke, or kill a folder's link, without touching the folder itself. For a file's link instead, use remove_shared_link_file.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes root_readwrite. Calls PUT /folders/{{params.folder_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "kill that link I sent for this folder", "shut off access through that directory's URL", "stop that folder's link from working".

box.add_collaboration

Invite a person by email to a Box file or folder, as a viewer, editor, or another Box role. Use when the user wants to add, invite, or give someone access to something in Box.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls POST /collaborations.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "invite someone to work on this with me", "give a new person access to this", "let this person in on the shared work".

box.list_folder_collaborations

List who has access to a Box folder and their role. Use when the user wants to see who can view or edit a shared folder, before changing its membership.

Class read (reads only). Scopes root_readonly. Calls GET /folders/{{params.folder_id}}/collaborations.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "who's on this shared space", "see everyone with access here", "check the roster for this shared area".

box.update_collaboration_role

Change the role an existing Box collaborator has on a file or folder, e.g. from viewer to editor. Use when the user wants to promote, demote, or change someone's permission level. Requires the collaboration id from list_folder_collaborations.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls PUT /collaborations/{{params.collaboration_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "bump this person up to editor", "change what this collaborator is allowed to do", "downgrade their permission level".

box.remove_collaboration

Revoke a person's collaboration on a Box file or folder. Use when the user wants to remove, kick out, or stop someone from accessing something they were added to. Requires the collaboration id from list_folder_collaborations.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes root_readwrite. Calls DELETE /collaborations/{{params.collaboration_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "take this person off the shared space", "kick them out of this collaborative area", "cut their access to this".

box.get_metadata

Read the structured metadata fields set on a Box file under one metadata template, e.g. status, priority, or category values a workflow tracks. Use when the user asks about a file's tags, custom fields, or classification rather than its name or size.

Class read (reads only). Scopes root_readonly. Calls GET /files/{{params.file_id}}/metadata/{{params.scope}}/{{params.template_key}}.

Arguments:

Also retrieved by: "what tags does this have", "check the custom fields on this document", "what status or category is set on this".

box.set_metadata

Attach structured metadata to a Box file for the first time under one template, e.g. tagging it with a status or category. Use when the user wants to classify, tag, or set custom fields on a file that doesn't have that template's metadata yet. To change values it already has, use update_metadata instead.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls POST /files/{{params.file_id}}/metadata/{{params.scope}}/{{params.template_key}}.

Arguments:

Also retrieved by: "tag this with a status", "classify this document", "add custom fields to this for the first time".

box.update_metadata

Change specific field values in a Box file's existing metadata under one template. Use when the user wants to update, correct, or change a tag or custom field a file already carries. To attach that template's metadata for the first time, use set_metadata instead.

Class write (writes, no confirmation needed). Scopes root_readwrite. Calls PUT /files/{{params.file_id}}/metadata/{{params.scope}}/{{params.template_key}}.

Arguments:

Also retrieved by: "change the status tag on this", "correct one of the custom fields on this", "update what this document is tagged with".

box.delete_metadata

Remove a whole metadata template's fields from a Box file. Use when the user wants to clear, strip, or remove the tags or custom fields a template added, not just change one value.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes root_readwrite. Calls DELETE /files/{{params.file_id}}/metadata/{{params.scope}}/{{params.template_key}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "strip the tags off this document", "clear the custom fields on this", "remove that classification entirely".

box.get_current_user

Get the signed-in Box account's name, login email, and storage usage. Use when the user asks who they're signed in as or wants their own account details.

Class read (reads only). Scopes root_readonly. Calls GET /users/me.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "who am I signed in as", "show my own profile details", "what account is this".

Triggers

Triggers are app-initiated. They are not retrievable as tools and cannot be called; subscribe with TriggersService.CreateSubscription and events arrive as signed deliveries.

file_uploaded

Fires when a new file is uploaded into a Box folder this project is subscribed to. Carries the uploaded file's id and name; call get_file or download_file afterward for its full details or content.

Payload fields (anything the schema does not declare never reaches a subscriber):

collaboration_created

Fires when someone is added as a collaborator on a Box file or folder this project is subscribed to. Carries the new collaboration's id and role; call list_folder_collaborations afterward to see the full membership.

Payload fields (anything the schema does not declare never reaches a subscriber):

Inbound webhooks

Providers post to /webhooks/box. Posts that fail verification are rejected before anything is stored, and the ingest path refuses every post while the secret variable is unset.

Mappings are tried in order and the first match wins.