Dropbox

Poll an async move, copy, delete, or restore_folder operation

REQUEST CONTRACT:

• operation_id (required): the opaque token returned by move, copy, delete, or restore_folder.
• wait_ms (optional): wait budget in milliseconds. Omitted or 0 performs one immediate status check. Positive values ask the server to wait briefly for completion. Maximum 30000ms; values >30000 or negative are rejected with INVALID_WAIT_MS.

RESPONSE CONTRACT:

• status: "completed" or "in_progress".
• operation_id: echoed when status="in_progress". Pass it back unchanged for the next poll.
• recommended_poll_after_ms: suggested delay before the next poll.
• When status="completed", result_type and the populated result field are:
• result_type="move" with move_result.
• result_type="copy" with copy_result.
• result_type="delete" with delete_result.
• result_type="restore_folder" with restore_folder_result.
• Successful move, copy, and delete result entries include an object with modified_time, which is the server-side modification time in ISO 8601 format when available.

ASSISTANT POLICY:

• Use this tool only when move, copy, delete, or restore_folder returns an operation_id.
• Do not assume every async Fileverse MCP tool uses check_job_status. Follow the submission tool's polling instructions.
• Pass operation_id back verbatim. Do not alter, truncate, or encode/decode it.
• Respect recommended_poll_after_ms; do not poll in a tight loop.
• When status becomes "completed", read result_type and use the matching result field listed above.
• Follow the submission tool's instructions for operation-specific results, errors, retries, and user-facing guidance.

EXAMPLES:

{"operation_id": "<token from previous in_progress response>"} {"operation_id": "<token>", "wait_ms": 5000}

Tool

Name: dropbox.check_upload_file_status Purpose: Poll an in-progress upload_file operation.

REQUEST CONTRACT:

• operation_id (required): Opaque token returned by upload_file when status="in_progress".
• wait_ms (optional): Wait budget in milliseconds. Omitted or 0 performs one immediate status check. Maximum 30000ms.

RESPONSE CONTRACT: When status is "in_progress":

• status: "in_progress"
• operation_id: Pass back unchanged on the next check.
• recommended_poll_after_ms: Suggested delay before polling again.

When status is "completed":

• status: "completed"
• file: Saved file metadata with name, path, modified_time, file_id, object_type, file.size, and path_display when available.
• modified_time is the server-side modification time, in ISO 8601 format when available.
• Prefer path_display when present and non-empty, both when showing the saved file to the user and in follow-on MCP calls. Otherwise use path or file_id exactly as returned.

ERRORS:

• INVALID_OPERATION_ID: operation_id is missing, malformed, expired, or belongs to a different user.
• INVALID_WAIT_MS: wait_ms is negative or greater than 30000.
• FETCH_FAILED: Dropbox could not download the source URL.
• CONTENT_HASH_MISMATCH: the completed file did not match the expected content hash and cleanup was attempted.

ASSISTANT POLICY:

• Use only with an operation_id returned by upload_file.
• Pass operation_id back verbatim. Do not alter, truncate, or encode/decode it.
• Respect recommended_poll_after_ms; do not poll in a tight loop.
• Do not claim the file was saved until status="completed".

EXAMPLES:

{"operation_id": "<token from upload_file>"} {"operation_id": "<token from upload_file>", "wait_ms": 5000}

Internal MCP app widget bridge for client logging events.

Copy one or more Dropbox files or folders to new locations; originals remain

When to use: Any time the user asks to duplicate files or folders into another location. Prefer copy over download-and-reupload.

PATHS:

• Each entry's source_path accepts fq_path, ns_path, file_id, or file_id with an appended child path such as "id:AbCd-_12/name.txt".
• destination_path accepts fq_path, ns_path, file_id, or file_id with an appended child path such as "id:AbCd-_12/name.txt"; Dropbox resolves lookup, conflicts, and destination semantics.
• file_id: a Dropbox-issued file id (format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-"; example: "id:AbCd-_12"). It can identify a file or folder.
• Dropbox shared/web URLs are not accepted.
• Paths must be Unicode NFC-normalized; decomposed forms are rejected.
• Dropbox may create missing destination parent folders during the copy; no need to pre-create parent folders unless the user explicitly asks.
• Paths are case-insensitive; the same entry can cross between fq_path, ns_path, and file_id forms if needed.
• Successful entries may return object.path as ns_path and object.path_display as fq_path. Prefer object.path_display when present and non-empty, both when showing paths to the user and in follow-on tool calls. If path_display is absent or empty, fall back to object.path or object.file_id exactly as returned.
• Never strip the "ns:<id>//" prefix from returned ns_path values.

REQUEST CONTRACT:

• entries (required, 1..1000): list of { source_path, destination_path } pairs.
• autorename (optional, default false): when true, Dropbox renames the destination to avoid a conflict instead of failing that entry.

RESPONSE CONTRACT (flat lifecycle fields, MIRROR of move/delete): When status is "completed":

• status: "completed"
• result_type: "copy"
• copy_result.entries[]: per-entry records in request order.
• entry_index: 0-based index into the original entries list.
• entry_status: "success" or "failed".
• object (on success): { name, file_id, object_type: "file"|"folder", path_display, file.size when file, modified_time }.

modified_time is the server-side modification time, in ISO 8601 format when available.

• failure (on failure): { error_code, message }.

When status is "in_progress":

• status: "in_progress"
• operation_id: opaque token to pass to dropbox.check_job_status.
• recommended_poll_after_ms: suggested delay before the next check_job_status call.

Job-level failures are returned as tool errors. Per-entry failures are returned in copy_result.entries[] when status is "completed".

ERRORS (job-level):

• INVALID_REQUEST: entries is empty, nil, or malformed
• INVALID_ENTRY: an entries item is missing source_path or destination_path
• INVALID_PATH: source_path is not a valid fq_path/ns_path/file_id value, or destination_path is not a valid fq_path/ns_path/file_id value
• TOO_MANY_ENTRIES: more than 1000 entries submitted in one call
• INVALID_ARGUMENT: Dropbox rejected the batch as malformed

ERRORS (per-entry error_code values):

• Source lookup failures use from_lookup/* codes, such as from_lookup/not_found, malformed paths, non-file/non-folder targets, restricted content, unsupported content type, or locked content.
• Source write failures use from_write/* codes for conflicts, malformed paths, missing write permission, space/quota issues, disallowed names, team-folder constraints, suppressed operations, too many write operations, or access restrictions.
• Destination write failures use to/* codes for destination conflicts, malformed paths, missing write permission, space/quota issues, disallowed names, team-folder constraints, suppressed operations, too many write operations, or access restrictions.
• Shared-folder, batch, permission/quota, and temporary failures include cant_copy_shared_folder, cant_nest_shared_folder, duplicated_or_nested_paths, too_many_files, cant_transfer_ownership, insufficient_quota, too_many_write_operations, and internal_error.
• unknown_error means Dropbox returned an error variant this tool does not recognize.

DUPLICATE DESTINATION QUIRK:

• For duplicate destinations in one batch, later entries may report from_write/conflict even though the practical cause is a destination collision. Report it to the user as a destination conflict.

RETRY GUIDANCE:

• If status is "in_progress", call dropbox.check_job_status with the returned operation_id.
• Do NOT retry the entire batch on per-entry failures; report the specific failures to the user.
• too_many_write_operations and internal_error are transient — retry after a short delay if appropriate.

EXAMPLES:

{"entries": [{"source_path": "/Docs/report.txt", "destination_path": "/Backup/report.txt"}]} {"entries": [{"source_path": "ns:123//A.txt", "destination_path": "ns:123//Archive/A.txt"}], "autorename": true} {"entries": [{"source_path": "id:AbCd-_12", "destination_path": "/Shared/duplicate.pdf"}]} {"entries": [{"source_path": "/Docs/source.pdf", "destination_path": "id:AbCd-_12/copy.pdf"}]}

ASSISTANT POLICY:

• Before calling this tool, the assistant MUST summarize the exact mutation plan and get explicit user confirmation in chat.
• The assistant MUST NOT claim the mutation already happened until the tool returns a successful response.
• After a successful response, the assistant MUST clearly list exactly what changed, using returned paths, file_id values, status values, and URLs when available.
• If the response represents partial success, the assistant MUST separate the succeeded and failed parts explicitly. When both shared_with and share_errors are present, report each list separately.
• After a successful response, the assistant MUST tell the user how to revert the change.
• For created files or folders, tell the user you can revert by calling dropbox.delete on the returned path_display after separate explicit confirmation.
• For deleted files or folders, tell the user they can restore deleted content and include https://help.dropbox.com/delete-restore/recover-deleted-files-folders.
• When recovering an older file version is relevant, include https://help.dropbox.com/delete-restore/recover-older-versions.
• For sharing changes, instruct the user to manage or revoke sharing from the Dropbox web UI and include https://help.dropbox.com/share/unshare-folder.
• Dropbox path handling: path_display is the preferred path. Always use path_display when it is present and non-empty, both in user-facing output and in follow-on tool calls. If path_display is absent or empty, fall back to the returned path/file_id exactly as provided.

Tool

Name: dropbox.create_file Purpose: Create a new file with text content in Dropbox. When to use: For creating text-oriented files from inline content only.

PATHS:

• Input path accepts fq_path or ns_path.
• Namespace IDs in ns_path are decimal digits and match [0-9]+.
• file_id and Dropbox shared/web URLs are not accepted.
• Paths are case-insensitive.
• Paths must be Unicode NFC-normalized; decomposed forms are rejected.
• The final path component is the filename to create.
• Output file.path is always ns_path.
• Never strip the "ns:<id>//" prefix from returned paths.
• Team root is not writable for team accounts. Personal account root is writable.
• Trailing whitespace in the final name component is stripped to match Dropbox storage normalization. The created file's actual name is returned in path_display and name — check the response if exact echo matters.
• The file extension is informational only. This tool accepts any valid Dropbox filename, but is intended for plain text; the list below shows common text-oriented formats:
• .abap
• .ada
• .adp
• .ahk
• .as
• .as3
• .asc
• .ascx
• .asm
• .asp
• .aspx
• .awk
• .bash
• .bash_login
• .bash_logout
• .bash_profile
• .bashrc
• .bat
• .bib
• .bsh
• .build
• .builder
• .c
• .c++
• .capfile
• .cc
• .cfc
• .cfm
• .cfml
• .cl
• .clj
• .cls
• .cmake
• .cmd
• .coffee
• .cpp
• .cpt
• .cpy
• .cs
• .cshtml
• .cson
• .csproj
• .css
• .csv
• .ctp
• .cxx
• .d
• .ddl
• .di
• .dif
• .diff
• .disco
• .dml
• .dtd
• .dtml
• .el
• .emakefile
• .erb
• .erl
• .f
• .f90
• .f95
• .fs
• .fsi
• .fsscript
• .fsx
• .gemfile
• .gemspec
• .gitconfig
• .go
• .groovy
• .gry
• .gvy
• .h
• .h++
• .haml
• .handlebars
• .hbs
• .hcp
• .hh
• .hpp
• .hrl
• .hs
• .htc
• .htm
• .html
• .hxx
• .idl
• .iim
• .inc
• .inf
• .ini
• .inl
• .ipp
• .irbrc
• .jade
• .jav
• .java
• .js
• .json
• .jsp
• .jsx
• .l
• .less
• .lhs
• .lisp
• .log
• .lst
• .ltx
• .lua
• .m
• .make
• .markdn
• .markdown
• .md
• .mdown
• .mkdn
• .ml
• .mli
• .mll
• .mly
• .mm
• .mud
• .nfo
• .opml
• .org
• .osascript
• .out
• .p
• .pas
• .patch
• .php
• .php2
• .php3
• .php4
• .php5
• .phtml
• .pl
• .plist
• .pm
• .pod
• .pp
• .profile
• .properties
• .ps1
• .psd1
• .psm1
• .pt
• .py
• .pyw
• .r
• .rake
• .rb
• .rbx
• .rc
• .re
• .readme
• .reg
• .rest
• .resw
• .resx
• .rhtml
• .rjs
• .rprofile
• .rpy
• .rs
• .rss
• .rst
• .rxml
• .s
• .sass
• .scala
• .scm
• .sconscript
• .sconstruct
• .script
• .scss
• .sgml
• .sh
• .shtml
• .sml
• .sql
• .sty
• .swift
• .tcl
• .tex
• .text
• .textile
• .tld
• .tli
• .tmpl
• .tpl
• .tsx
• .txt
• .vb
• .vi
• .vim
• .wsdl
• .xhtml
• .xml
• .xoml
• .xsd
• .xsl
• .xslt
• .yaml
• .yaws
• .yml
• .zsh

CONTENT CAVEATS:

• Do not use create_file for binary data or content that must preserve control bytes. The content field is a JSON string, and some clients may transform NUL/control characters before Dropbox receives them.
• Use only for plain UTF-8 text. For binary content (images, archives, executables, office files with embedded media), use a byte-preserving upload or download flow instead of this JSON-string content field.

REQUEST CONTRACT:

• path (string, REQUIRED): Full destination path including the filename.
• Parent must already exist.
• content (string, REQUIRED): UTF-8 text content. Maximum 5MB.

RESPONSE CONTRACT:

• file: object describing the created file.
• name, path, modified_time, file_id
• object_type: "file"
• file.size: File size in bytes.
• path_display: fq_path for human display when populated.
• When content is empty, the response may omit file.size instead of returning 0. Treat an omitted size as a zero-byte file.

ASSISTANT POLICY:

• Before calling this tool, the assistant MUST summarize the exact mutation plan and get explicit user confirmation in chat.
• The assistant MUST NOT claim the mutation already happened until the tool returns a successful response.
• After a successful response, the assistant MUST clearly list exactly what changed, using returned paths, file_id values, status values, and URLs when available.
• If the response represents partial success, the assistant MUST separate the succeeded and failed parts explicitly. When both shared_with and share_errors are present, report each list separately.
• After a successful response, the assistant MUST tell the user how to revert the change.
• For created files or folders, tell the user you can revert by calling dropbox.delete on the returned path_display after separate explicit confirmation.
• For deleted files or folders, tell the user they can restore deleted content and include https://help.dropbox.com/delete-restore/recover-deleted-files-folders.
• When recovering an older file version is relevant, include https://help.dropbox.com/delete-restore/recover-older-versions.
• For sharing changes, instruct the user to manage or revoke sharing from the Dropbox web UI and include https://help.dropbox.com/share/unshare-folder.
• Dropbox path handling: path_display is the preferred path. Always use path_display when it is present and non-empty, both in user-facing output and in follow-on tool calls. If path_display is absent or empty, fall back to the returned path/file_id exactly as provided.

ERRORS:

• INVALID_PATH: path is empty, missing name component, or contains \ (backslash)
• CONTENT_TOO_LARGE: content exceeds 5MB
• PARENT_NOT_FOUND: parent path doesn't exist
• PARENT_NOT_FOLDER: parent is not a folder
• ALREADY_EXISTS: file exists at target
• PERMISSION_DENIED: no write access
• TEAM_ROOT_NOT_WRITABLE: cannot create files or folders directly in team root

RETRY GUIDANCE:

• Do NOT retry on TEAM_ROOT_NOT_WRITABLE. Choose a specific folder path instead.

EXAMPLES:

{"path": "/Documents/notes.txt", "content": "Hello World"} {"path": "ns:123//Code/script.py", "content": "print('hi')"} {"path": "/readme.txt", "content": "Root level file"}

Create a URL other people can use to upload files to the user's Dropbox

Purpose: Create a Dropbox file request that lets other people upload files into a chosen Dropbox destination. When to use: Use this when the user wants a Dropbox file request, upload request, upload link, submission link, or a way for other people to upload, submit, collect, or receive files into the user's Dropbox. This creates a public upload URL for contributors to add files to the chosen destination folder; it is not for giving people view or download access to existing Dropbox content.

REQUEST CONTRACT:

• Shape: {"title": "<title>", "destination": "/Requests/Invoices", "deadline": "2026-05-04T17:00:00Z", "deadline_allow_late_uploads": "seven_days", "closed": false, "description": "...", "video_project_id": "..."}
• title (string, REQUIRED): File request title. Must be non-empty.
• destination (string, REQUIRED): Destination folder path. Accepts fq_path, ns_path, or file_id. file_id: a Dropbox-issued file id (format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-"; example: "id:AbCd-_12"). It can identify a file or folder. Dropbox shared/web URLs are not accepted. Dropbox rejects file requests at a team root, such as "/", or the user's personal root, such as "/FirstName LastName"; use a child folder under that folder, such as "/FirstName LastName/Invoices". If the destination folder does not exist and the user has write permission to the parent folder, the destination folder will be created automatically. Avoid surprising destinations; confirm the exact destination with the user before creating.
• deadline (string, optional): RFC3339 timestamp, for example "2026-05-04T17:00:00Z". If omitted, the file request has no deadline and accepts uploads indefinitely until the request is manually closed or deleted. Setting a deadline requires an eligible Dropbox plan: Professional, Essentials, Business, Business Plus, Standard, Advanced, or Enterprise. Basic, Plus, and Family accounts cannot set a deadline; Dropbox will reject the request for users on these plans.
• deadline_allow_late_uploads (string, optional): Valid only when deadline is present. Allowed values: "one_day", "two_days", "seven_days", "thirty_days", or "always".
• closed (bool, optional): Defaults to false. false creates an open request; true creates a closed request.
• description (string, optional): Optional instructions shown on the file request.
• video_project_id (string, optional): Optional Dropbox video editor project ID for associating uploads from this file request with that project. Only pass this when the user or an upstream Dropbox workflow provides the exact project ID. This tool does not verify the project before creating the file request. If the ID is invalid or inaccessible, later uploads can still succeed, but Dropbox may fail to attach the uploaded files to the video project.

RESPONSE CONTRACT:

• file_request: Created file request record.
• id: File request ID.
• url: Public upload URL.
• title: File request title.
• destination: Destination folder path.
• created: ISO 8601 creation timestamp.
• deadline: ISO 8601 deadline timestamp. Empty when unset.
• deadline_allow_late_uploads: Grace period string. Empty when unset.
• is_open: Whether the created request accepts uploads.
• file_count: Number of submitted files.
• description: Optional description. Empty when unset.
• video_project_id: Optional video editor project ID. Empty when unset.

ASSISTANT POLICY:

• Confirm with the user before calling this tool.
• Do not claim the file request was created until this tool returns a successful response.
• Return the created file request URL, title, destination, open/closed state, and deadline when present.
• Avoid creating requests in unexpected destinations without explicit user confirmation.
• If the destination is a team root or the user's personal root, ask the user to confirm a child folder under that folder. Do not silently retry with a guessed child folder.
• This tool creates metadata only. It does not update, close, delete, or submit files to a request.
• After a successful response that creates an open file request, tell the user they can close it from Dropbox and include https://help.dropbox.com/share/create-file-request.
• If the destination folder does not exist and the user has write permission to the parent folder, the destination folder will be created automatically. Do not pass guessed, placeholder, or unverified paths. If the user expects an existing folder, verify the destination before creating the request.
• You cannot reliably know the user's plan tier in advance. If the user asks for a deadline and the create call fails with a plan-tier error, do not silently retry without a deadline. Explain that deadlines require an eligible plan (Professional, Essentials, Business, Business Plus, Standard, Advanced, or Enterprise) and obtain a second explicit confirmation from the user before creating the request without a deadline.
• If the user is on Basic, Plus, or Family, or declines a deadline, proceed without one and explicitly warn that the request will remain open until they close or delete it.

EXAMPLES:

{"title": "Invoice uploads", "destination": "/Requests/Invoices"} {"title": "Invoice uploads", "destination": "id:AbCd-_12"} {"title": "Video assets", "destination": "/Projects/Launch", "deadline": "2026-05-04T17:00:00Z", "deadline_allow_late_uploads": "seven_days", "description": "Upload final cuts here."}

Create a new Dropbox folder at a path; parent folders must already exist

PATHS:

• Input path accepts fq_path (for example "/Documents/NewFolder") or ns_path (for example "ns:123//Documents/NewFolder").
• Namespace IDs in ns_path are decimal digits and match [0-9]+.
• file_id and Dropbox shared/web URLs are not accepted.
• Paths are case-insensitive.
• Paths must be Unicode NFC-normalized; decomposed forms are rejected.
• The final path component is the new folder name.
• Output folder.path is always ns_path.
• Never strip the "ns:<id>//" prefix from returned paths.
• Team root is not writable for team accounts. Personal account root is writable.
• Trailing whitespace in the final name component is stripped to match Dropbox storage normalization. The created folder's actual name is returned in path_display and name — check the response if exact echo matters.

REQUEST CONTRACT:

• path (string, REQUIRED): Full destination path including the new folder name.
• Parent must already exist. create_folder does not auto-create intermediate parents; call create_folder for each level, or use copy when missing destination parent folders should be created automatically.
• To create nested parents, call create_folder for the parents first.

RESPONSE CONTRACT:

• folder: object describing the created folder.
• name: Folder name.
• path: ns_path for follow-on MCP calls.
• modified_time: Server-side modification time in ISO 8601 when available.
• client_modified: Client-specified content modification time in ISO 8601 when available.
• file_id: Dropbox-issued file id. Can be reused exactly as returned.
• object_type: "folder".
• folder: Empty object.
• path_display: fq_path for human display when populated.

ASSISTANT POLICY:

• Before calling this tool, the assistant MUST summarize the exact mutation plan and get explicit user confirmation in chat.
• The assistant MUST NOT claim the mutation already happened until the tool returns a successful response.
• After a successful response, the assistant MUST clearly list exactly what changed, using returned paths, file_id values, status values, and URLs when available.
• If the response represents partial success, the assistant MUST separate the succeeded and failed parts explicitly. When both shared_with and share_errors are present, report each list separately.
• After a successful response, the assistant MUST tell the user how to revert the change.
• For created files or folders, tell the user you can revert by calling dropbox.delete on the returned path_display after separate explicit confirmation.
• For deleted files or folders, tell the user they can restore deleted content and include https://help.dropbox.com/delete-restore/recover-deleted-files-folders.
• When recovering an older file version is relevant, include https://help.dropbox.com/delete-restore/recover-older-versions.
• For sharing changes, instruct the user to manage or revoke sharing from the Dropbox web UI and include https://help.dropbox.com/share/unshare-folder.
• Dropbox path handling: path_display is the preferred path. Always use path_display when it is present and non-empty, both in user-facing output and in follow-on tool calls. If path_display is absent or empty, fall back to the returned path/file_id exactly as provided.

ERRORS:

• INVALID_PATH: path is empty, missing name component, or contains \ (backslash)
• PARENT_NOT_FOUND: parent path doesn't exist
• PARENT_NOT_FOLDER: parent is not a folder
• ALREADY_EXISTS: folder already exists at target path
• PERMISSION_DENIED: no write access
• TEAM_ROOT_NOT_WRITABLE: cannot create files or folders directly in team root

RETRY GUIDANCE:

• Do NOT retry on TEAM_ROOT_NOT_WRITABLE. Choose a specific folder path instead.

EXAMPLES:

{"path": "/Documents/NewFolder"} {"path": "ns:123//Projects/Archive"} {"path": "/NewFolderAtRoot"} Limitations: This tool only creates folders. It cannot rename or delete existing folders.

Create or reuse a private, view-only Dropbox link; optionally invite viewers

Capability limit: This tool cannot create public, anyone-with-link, or team-wide links. For public or team-wide links, use the Dropbox web UI or another approved surface outside this MCP tool. When to use: Only when the user explicitly asks to share, get a link, or send a file/folder to someone. Do NOT call automatically after create_file.

PATHS:

• Input path_or_file_id accepts fq_path, ns_path, or file_id.
• Namespace IDs in ns_path are decimal digits and match [0-9]+.
• file_id: a Dropbox-issued file id (format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-"; example: "id:AbCd-_12"). It can identify a file or folder.
• Dropbox shared/web URLs are not accepted.
• Paths are case-insensitive. "/Documents/File.txt" and "/documents/file.txt" resolve to the same object.
• Paths must be Unicode NFC-normalized; decomposed forms are rejected.
• Never strip the "ns:<id>//" prefix from returned paths.

REQUEST CONTRACT:

• path_or_file_id (string, REQUIRED): File or folder identifier.
• emails (string[], OPTIONAL): Viewers to add directly.
• Maximum 25 emails.
• Empty strings are filtered out before the limit is checked.
• Dropbox deduplicates duplicate emails before sharing; each unique email is invited at most once.
• Control characters (\r, \n, \t, etc.) are rejected with INVALID_EMAIL.
• audience (string, OPTIONAL): Locked to "no_one". Any other value is rejected with INVALID_AUDIENCE. Links created by this tool are usable only by people who have direct access to the file/folder, including viewers added through emails; use the Dropbox web UI to create public or team links.
• access_level (string, OPTIONAL): Locked to "view". Any other value is rejected with INVALID_ACCESS_LEVEL. Links created by this tool are view-only; use the Dropbox web UI to create editor links.
• password (string, OPTIONAL): Password protection when supported. Only applied when this call CREATES the link (created=true). Ignored when reusing an existing link (see no-mutation contract below).
• expires (string, OPTIONAL): ISO 8601 expiration when supported. Only applied on link creation; ignored on reuse.
• allow_download (bool, OPTIONAL): Whether recipients can download. Only applied on link creation; ignored on reuse.

RESPONSE CONTRACT:

• url: The shared link URL. Always present.
• created: Whether this is a newly created link (true) or a pre-existing one (false).
• warning: Only present when created=false and the existing link's settings do not match what was requested. Lists which settings differ. No changes were made to the link.
• audience: Effective audience. "no_one" for new links; existing links report their actual audience.
• access_level: Effective access level. "view" for new links; existing links report their actual level.
• password_protected: Whether the link has a password set.
• expires: Expiration timestamp (RFC 3339) or empty.
• allow_download: Whether download is enabled.
• content_type: "file" or "folder".
• path: ns_path for the shared object. Use this for follow-on MCP calls.
• path_display: Human-readable fq_path.
• The filename in url may be sanitized. Treat path and path_display as the authoritative original name.
• shared_with and share_errors: When member addition is attempted or skipped because warning is present, both fields are returned as a pair.
• shared_with: Emails successfully added as viewers (may be empty).
• share_errors: Email-specific member-add errors, or the reason member addition was skipped (may be empty).
• Link creation and member addition are separate steps, so a link may be created even when all email additions fail.

REUSE BEHAVIOR (NO MUTATION — IMPORTANT):

• This tool never modifies an existing link. If a link already exists for the path, it is returned as-is (created=false) with the link's current settings.
• password, allow_download, expires, audience, and access_level passed in the request are IGNORED on reuse. Always check the response's effective settings (password_protected, allow_download, expires, audience, access_level) against your request before telling the user a setting was applied.
• When the existing link matches the request, response carries no warning and member addition (emails) proceeds.
• When the existing link differs from the request, the warning field names the mismatched fields and member addition is skipped. Tell the user the existing settings differ and that no members were added.
• To change settings, revoke the link in the Dropbox web UI, then call create_shared_link again.

SIDE EFFECTS:

• Sharing a regular folder converts it to a shared folder (mount). Its namespace path will change in subsequent list_folder results.

ASSISTANT POLICY:

• Before calling this tool, the assistant MUST summarize the exact mutation plan and get explicit user confirmation in chat.
• The assistant MUST NOT claim the mutation already happened until the tool returns a successful response.
• After a successful response, the assistant MUST clearly list exactly what changed, using returned paths, file_id values, status values, and URLs when available.
• If the response represents partial success, the assistant MUST separate the succeeded and failed parts explicitly. When both shared_with and share_errors are present, report each list separately.
• After a successful response, the assistant MUST tell the user how to revert the change.
• For created files or folders, tell the user you can revert by calling dropbox.delete on the returned path_display after separate explicit confirmation.
• For deleted files or folders, tell the user they can restore deleted content and include https://help.dropbox.com/delete-restore/recover-deleted-files-folders.
• When recovering an older file version is relevant, include https://help.dropbox.com/delete-restore/recover-older-versions.
• For sharing changes, instruct the user to manage or revoke sharing from the Dropbox web UI and include https://help.dropbox.com/share/unshare-folder.
• Dropbox path handling: path_display is the preferred path. Always use path_display when it is present and non-empty, both in user-facing output and in follow-on tool calls. If path_display is absent or empty, fall back to the returned path/file_id exactly as provided.

ERROR CASES:

• SETTINGS_NOT_AUTHORIZED: Account or policy does not allow the requested password, expiry, or download setting
• INVALID_AUDIENCE: audience other than "no_one" specified
• INVALID_ACCESS_LEVEL: Non-view access_level specified
• INVALID_EMAIL: Email contains control characters
• TOO_MANY_EMAILS: More than 25 emails provided
• MISSING_PATH: path_or_file_id is empty
• INVALID_FILE_ID: file_id format is invalid
• FILE_NOT_FOUND: target file or folder does not exist
• INVALID_SETTINGS: target cannot be shared (e.g., root path, member folder mount)
• INVALID_EXPIRES: expires is malformed or in the past
• RATE_LIMIT_EXCEEDED: request exceeded tool rate limits

EXAMPLES:

{"path_or_file_id": "/Documents/report.pdf"} {"path_or_file_id": "ns:123//Documents/report.pdf", "emails": ["alice@example.com", "bob@example.com"]} {"path_or_file_id": "id:AbCd-_12", "emails": ["team@example.com"]}

Delete Dropbox files or folders; they remain recoverable in Deleted files

When to use: Any time the user asks to delete, remove, or trash files or folders.

DELETE SEMANTICS:

• Delete moves each entry to the user's Dropbox "Deleted files" area; it is NOT a permanent wipe. The user can restore deleted items through the Dropbox web/desktop UI.
• If the user explicitly asks for permanent deletion, this tool does NOT support that. Warn the user and stop — do not proceed.

PATHS:

• Each entry's source_path accepts fq_path, ns_path, file_id, or file_id with an appended child path such as "id:AbCd-_12/name.txt".
• file_id: a Dropbox-issued file id (format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-"; example: "id:AbCd-_12"). It can identify a file or folder.
• Dropbox shared/web URLs are not accepted.
• Paths are case-insensitive; the same entry can cross between fq_path, ns_path, and file_id forms if needed.
• Paths must be Unicode NFC-normalized; decomposed forms are rejected.
• Successful entries return object metadata captured at deletion time (not a tombstone). object.path is ns_path; object.path_display is fq_path. Prefer object.path_display when present and non-empty, both when showing paths to the user and in follow-on tool calls. If path_display is absent or empty, fall back to object.path or object.file_id exactly as returned.
• Never strip the "ns:<id>//" prefix from returned ns_path values.

REQUEST CONTRACT:

• entries (required, 1..1000): list of { source_path } entries.

RESPONSE CONTRACT (flat lifecycle fields, MIRROR of move/copy): When status is "completed":

• status: "completed"
• result_type: "delete"
• delete_result.entries[]: per-entry records in request order.
• entry_index: 0-based index into the original entries list.
• entry_status: "success" or "failed".
• object (on success): { name, file_id, object_type: "file"|"folder", path_display, file.size when file, modified_time } — metadata at deletion time.

modified_time is the server-side modification time, in ISO 8601 format when available.

• failure (on failure): { error_code, message }.

When status is "in_progress":

• status: "in_progress"
• operation_id: opaque token to pass to dropbox.check_job_status.
• recommended_poll_after_ms: suggested delay before the next check_job_status call.

Job-level failures are returned as tool errors. Per-entry failures are returned in delete_result.entries[] when status is "completed".

ERRORS (job-level):

• INVALID_REQUEST: entries is empty, nil, or malformed
• INVALID_ENTRY: an entries item is missing source_path
• INVALID_PATH: source_path is not a valid fq_path/ns_path/file_id value
• TOO_MANY_ENTRIES: more than 1000 entries submitted in one call
• INVALID_ARGUMENT: Dropbox rejected the batch as malformed
• DELETE_BATCH_FAILED: async job reported a job-level failure during polling

ERRORS (per-entry error_code values):

• Path lookup failures use path_lookup/* codes, such as path_lookup/not_found, malformed paths, non-file/non-folder targets, restricted content, unsupported content type, or locked content.
• Path write failures use path_write/* codes for conflicts, malformed paths, missing write permission, space/quota issues, disallowed names, team-folder constraints, suppressed operations, too many write operations, or access restrictions.
• Transient/batch failures include too_many_write_operations, too_many_files, and internal_error.
• unknown_error means Dropbox returned an error variant this tool does not recognize.

RETRY GUIDANCE:

• If status is "in_progress", call dropbox.check_job_status with the returned operation_id.
• Do NOT retry the entire batch on per-entry failures; report the specific failures to the user.
• too_many_write_operations and internal_error are transient — retry after a short delay if appropriate.

EXAMPLES:

{"entries": [{"source_path": "/Docs/old.txt"}]} {"entries": [{"source_path": "ns:123//Archive/A.txt"}, {"source_path": "ns:123//Archive/B.txt"}]} {"entries": [{"source_path": "id:AbCd-_12"}]}

ASSISTANT POLICY:

• Before calling this tool, the assistant MUST summarize the exact mutation plan and get explicit user confirmation in chat.
• The assistant MUST NOT claim the mutation already happened until the tool returns a successful response.
• After a successful response, the assistant MUST clearly list exactly what changed, using returned paths, file_id values, status values, and URLs when available.
• If the response represents partial success, the assistant MUST separate the succeeded and failed parts explicitly. When both shared_with and share_errors are present, report each list separately.
• After a successful response, the assistant MUST tell the user how to revert the change.
• For created files or folders, tell the user you can revert by calling dropbox.delete on the returned path_display after separate explicit confirmation.
• For deleted files or folders, tell the user they can restore deleted content and include https://help.dropbox.com/delete-restore/recover-deleted-files-folders.
• When recovering an older file version is relevant, include https://help.dropbox.com/delete-restore/recover-older-versions.
• For sharing changes, instruct the user to manage or revoke sharing from the Dropbox web UI and include https://help.dropbox.com/share/unshare-folder.
• Dropbox path handling: path_display is the preferred path. Always use path_display when it is present and non-empty, both in user-facing output and in follow-on tool calls. If path_display is absent or empty, fall back to the returned path/file_id exactly as provided.

Generate single-use temporary download URLs for one or more Dropbox files

PATHS:

• Input entries accepts fq_path, ns_path, or file_id.
• file_id: a Dropbox-issued file id (format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-"; example: "id:AbCd-_12"). It can identify a file or folder.
• Dropbox shared/web URLs are not accepted.
• Paths must be Unicode NFC-normalized; decomposed forms are rejected.
• Never strip the "ns:<id>//" prefix from values returned by other tools before passing them here.
• Entries must refer to files. Folders are not downloadable through this tool.

REQUEST CONTRACT:

• entries (string[], REQUIRED): One or more file identifiers. Maximum 25 entries per request.
• Path formats: fq_path such as "/Documents/report.pdf" or ns_path such as "ns:123//Documents/report.pdf".
• file_id format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-"; example: "id:AbCd-_12".
• expiration_in_sec (uint32, optional): Link lifetime in seconds. Defaults to 600 when omitted or 0. Valid values are 0 (use default) or 60-900.

BATCH SEMANTICS:

• If any entry is invalid or cannot be linked, the entire call fails with a tool error. The response does not include per-entry success/failure records.
• For mixed-quality batches, verify inputs first with get_file_metadata or list_folder, or split the call into per-entry requests.

RESPONSE CONTRACT:

• entries[]: Temporary download link records, in request order. Only populated when all requested entries resolve successfully.
• download_url: Single-use temporary URL for file content.
• expiration_in_sec: Link lifetime in seconds.
• path: ns_path for follow-on MCP calls.
• path_display: fq_path for human display when populated.
• name, id, size, content_hash, mime_type: File metadata for the linked file.

SINGLE-USE URL:

• The URL is consumed by the first HTTP request of any method, including HEAD and Range requests. Do not preview, unfurl, scan, or preflight it; request a new link if it is consumed or expires.
• Anyone with the URL can fetch the user's file content with an unauthenticated HTTP GET. Treat download_url as sensitive and short-lived. Do not present it as a durable shared link.

ASSISTANT POLICY:

• Use this when the user needs an actual file download URL, not extracted text. For text inspection, prefer a different tool.
• If a download fails, expires, or has already been consumed, request a new temporary link.
• Do not use this for folders, CloudDocs, or Paper docs; they are not supported by temporary direct-download URLs.
• Do not call create_shared_link automatically after this tool unless the user explicitly asks for a shareable Dropbox link.
• When showing file identity to the user, MUST use path_display if present. Otherwise use path or id exactly as returned.

EXAMPLES:

{"entries": ["/Documents/report.pdf"]} {"entries": ["ns:123//Projects/image.png", "id:AbCd-_12"], "expiration_in_sec": 900}

Prepare an exact file download or bounded export in the selected root. Recheck both the current account root and stable file identity. Return a provider-issued temporary URL for downloadable files, or a bounded export for non-downloadable files such as Paper. Never switch roots on failure.

Return a bounded provider-generated JPEG for trusted internal image previews. Resolve this exact file in the linked account's current home or team namespace. This action never downloads the original file or accepts caller-chosen roots.

Read a stable item ID in its authenticated home or Team Space root. Unlike path resolution, this supports accessible shared items without mounted paths. Pass the returned root to subsequent private content reads.

Browse one Dropbox folder page with typed file and folder metadata. Use the empty path for the connected account's home root. To browse a previously discovered folder, pass its path_display, path_lower, or stable id:<folder-id>. Mounted folders are included by default. Repeat optional object-type filters when continuing the provider cursor because filtering is applied locally. Programmatic team-root callers must first resolve a stable folder ID and pass its returned root unchanged.

Continue exactly one Dropbox folder page while preserving caller-side filters. Use a folder-list cursor only, repeat the original file/folder filter when present, and pass prior stable IDs to suppress duplicates across pages. Repeat the root returned by dropbox_resolve_item_path for team-root listings.

Return files observed in a bounded, recursively scanned Dropbox home. Recency always means Dropbox server modification time, never file-access or view history. Observed files are sorted newest first, while folders and duplicate IDs are excluded. A continuation means the home-folder scan remains incomplete: the page is not guaranteed to contain the globally newest files. Resume with the returned cursor, its prior items, its continuation signature, and the same result limit so earlier verified files remain in the ranking. Each call reads one provider page and returns its accumulated ranking before another page is requested, preserving progress across caller deadlines.

Resolve a stable Dropbox item ID to its current authenticated scope. Use this private action before authorizing a mounted Library folder or file. It derives account roots from Dropbox, prefers the connected home namespace, falls back to the provider-owned team root only when the ID is absent from home, and re-reads every current folder ancestor. Missing, malformed, incomplete, or inconsistent ancestry fails closed. Pass a previously resolved root to keep subsequent item reads in that namespace; explicit roots are revalidated and never fall back to another namespace.

Continue exactly one provider-native Dropbox Search v2 result page. Pass only a search cursor, not a folder-list cursor. Repeat the initial file-only and modification-range filters because Dropbox cursors do not encode connector-side filtering. Pass prior stable item IDs to suppress duplicates across pages. Repeat the initial search's root when present.

Search Dropbox with provider-native Search v2 filters and stable item metadata. Filename-only, stable folder ID or path scope, categories, extensions, and sort order are passed directly to Dropbox. File-only and modification-range filters are applied to each provider page; repeat them for its continuation. Unscoped searches include shared files, which have no path when unmounted. Explicit root selection requires a stable folder ID in path. Repeat the same root when continuing the search or resolving its matching item paths. Account-root search instead derives the current root from the linked credential, without accepting a caller-selected namespace or folder.

Upload file bytes into an exact Dropbox folder, failing on name conflicts. This private action requires write consent on the existing public app link. It never replaces an existing file or creates a different destination folder.

Fetch full text content for a Dropbox file by id or path.

REQUEST:

• id: File identifier or Dropbox path (required string; accepts file_id, fq_path, or ns_path)

INPUT SHAPES:

• Namespace IDs in ns_path are decimal digits and match [0-9]+.
• file_id: a Dropbox-issued file id (format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-"; example: "id:AbCd-_12"). It can identify a file or folder.

RESPONSE:

• id: Same id-or-path token used for the request
• title: Human-readable file title
• text: Full extracted text content
• url: Openable Dropbox URL for the file
• metadata: Optional string fields such as path_display and server_modified

NOTES:

• Use the id returned by search directly with this tool, or pass an existing Dropbox path.
• Shared/web URLs are not accepted; callers must pass a Dropbox path, namespace path, or file_id.
• Use this tool when the user wants extracted text content from the file, such as reading, quoting, or summarizing the file's text.
• Dropbox Paper documents are supported. For Paper, text is Markdown that includes the document title and supported structure such as headings, tables, links, lists, and code blocks.
• For preview-oriented asks such as preview, show, open, inspect visually, or get a thumbnail/open-in-Dropbox experience, prefer file_preview instead.
• This tool uses Dropbox's existing content extraction backends.
• url prefers GetFileContent.content_link and falls back to GetFileMetadata.file.url when needed.
• Max file size: 5 MiB.
• If extraction fails, the tool returns an error instead of a partial success payload.

EXAMPLES: {"id": "/Documents/report.pdf"} {"id": "ns:123//Documents/report.pdf"} {"id": "id:AbCd-_12"}

Preview Dropbox files visually with thumbnails and Open in Dropbox links

USAGE: Provide a list of file paths, and the tool will return a list of FilePreviewData objects. Prefer this tool for preview-oriented asks such as preview, show, open, inspect visually, or get a thumbnail/open-in-Dropbox experience for a file. Use fetch instead only when the user explicitly wants extracted text content from the file.

ASSISTANT POLICY:

• Use the file preview widget result as the preview surface.
• Do not render thumbnail_url as a Markdown image embed. thumbnail_url is widget preview data and is not guaranteed to be a public or chat-renderable image URL.
• When useful, include open_in_dropbox_url as an "Open in Dropbox" link.

PATHS (VERY VERY IMPORTANT FOR TEAM ACCOUNTS):

• fq_path (aka path_display/path_lower/fq_path): FullyQualified path from user root, e.g. "/RootFolder/folder1/file2"
• ns_path (aka namespace path): Includes a namespace ID, e.g. "ns:123//RootFolder/folder1/file2"
• Input path_or_file_id: accepts BOTH fq_path and ns_path, plus file_id.
• Namespace IDs in ns_path are decimal digits and match [0-9]+.
• file_id: a Dropbox-issued file id (format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-"; example: "id:AbCd-_12"). It can identify a file or folder.
• ALWAYS prefer file_id when available.
• If file_id is not available, use ns_path.
• Use fq_path/path_display only as a last resort when neither file_id nor ns_path is available.
• Team/shared-space mounted display paths like "/Rahul Monga/App Testing/dbxlogo.png" can fail even when the same file works via file_id or ns_path.
• NEVER truncate/convert an ns_path to an fq_path by removing the "ns:<id>//" prefix (this will be wrong!)

REQUEST:

• file_paths: The file paths to the files for the desired preview (required array of strings)

RESPONSE: Returns a response with:

• In structuredContent
• results: An array of FilePreviewData objects, each containing:
• thumbnail_url: The thumbnail url of a given file.
• file_type: The file type of the given file.
• open_in_dropbox_url: A URL to open the file in Dropbox.
• copy_link_url: A URL to copy a share link for the file.
• file_name: The name of the file.
• message: A description of the content if possible.

EXAMPLES:

• Input: {"file_paths": ["id:AbCd-_12"]} → "{ results: [{ thumbnail_url: "www.dropbox.com/example-thumb.pdf", file_type: "pdf", open_in_dropbox_url: "www.dropbox.com/home/example.pdf", copy_link_url: "www.dropbox.com/scl/abc123", message: "some content description", file_name: "example.pdf"} ] }"
• Input: {"file_paths": ["ns:123//Team Space/example.csv"]} → "{ results: [{ thumbnail_url: "www.dropbox.com/example-thumb.csv", file_type: "csv", open_in_dropbox_url: "www.dropbox.com/home/example.csv", copy_link_url: "www.dropbox.com/scl/def456", message: "some content description", file_name: "example.csv"} ] }"
• Input: {"file_paths": ["/Documents/example.txt"]} → "{ results: [{ thumbnail_url: "www.dropbox.com/example-thumb.txt", file_type: "txt", open_in_dropbox_url: "www.dropbox.com/home/example.txt", copy_link_url: "www.dropbox.com/scl/ghi789", message: "some content description", file_name: "example.txt"} ] }"

Private shared link requirement: This tool always generates a private shared link. Once you share the link you will need to approve their access from inside dropbox.

Get metadata, sharing details, and permissions for a Dropbox file or folder

PATHS:

• Input path_or_file_id accepts fq_path, ns_path, or file_id.
• Namespace IDs in ns_path are decimal digits and match [0-9]+.
• file_id: a Dropbox-issued file id (format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-"; example: "id:AbCd-_12"). It can identify a file or folder.
• Dropbox shared/web URLs are not accepted.
• Paths must be Unicode NFC-normalized; decomposed forms are rejected.
• Output nested metadata uses fq_path fields such as path_display and path_lower.
• Never strip the "ns:<id>//" prefix from values returned by other tools before passing them here.

REQUEST CONTRACT:

• path_or_file_id (string, REQUIRED): File or folder identifier.
• Path formats: fq_path such as "/Documents/file.txt" or ns_path such as "ns:123//Documents/file.txt".
• file_id format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-"; example: "id:AbCd-_12".

RESPONSE CONTRACT:

• metadata_type: "file" | "folder". Inspect this first.
• file: Present only when metadata_type="file".
• tag, id, name, path_display, path_lower
• client_modified, server_modified
• size, size_display, is_downloadable, mime_type, rev
• size may be absent (not zero) for empty files due to proto serialization. Treat absent as zero.
• sharing_info, permissions, url, ext, has_explicit_shared_members
• folder: Present only when metadata_type="folder".
• tag, id, name, path_display, path_lower
• sharing_info, permissions, url
• descendants_count, folder_size

ASSISTANT POLICY:

• Treat the response as nested. Do not assume there is a flat top-level tag, id, or name.
• Do not assume both file and folder are present.
• When using results from list_folder or search, pass the exact returned ns_path or file_id.

EXAMPLES:

{"path_or_file_id": "/Documents/report.pdf"} {"path_or_file_id": "ns:123//Photos/image.png"} {"path_or_file_id": "id:AbCd-_12"}

Get the metadata for one Dropbox file request by its request ID

REQUEST CONTRACT:

• Shape: {"id": "<file_request_id>"}
• id (string, REQUIRED): Raw Dropbox file request ID returned by list_file_requests.file_requests[].id or create_file_request.file_request.id.
• Do not send a path, file id, URL, title, example, or guessed value. This tool accepts only the raw file request ID.

RESPONSE CONTRACT:

• file_request: File request record.
• id: File request ID.
• url: Public upload URL.
• title: File request title.
• destination: Destination folder path. Empty when the destination was removed.
• created: ISO 8601 creation timestamp.
• deadline: ISO 8601 deadline timestamp. Empty when unset.
• deadline_allow_late_uploads: Grace period string: "one_day", "two_days", "seven_days", "thirty_days", or "always". Empty when unset.
• is_open: Whether the request accepts uploads.
• file_count: Number of submitted files.
• description: Optional description. Empty when unset.
• video_project_id: Optional video project ID. Empty when unset.

ASSISTANT POLICY:

• Use this tool when the user asks about a specific Dropbox file request and you have its raw ID from list_file_requests or create_file_request.
• If you do not already have a current raw file request ID from list_file_requests or create_file_request, call list_file_requests first.
• If the user provides a URL, path, title, or other non-ID reference, call list_file_requests first to find the matching raw ID when possible; otherwise ask for the raw file request ID.
• This tool retrieves metadata only. It does not create, update, close, delete, or submit files to a request.

EXAMPLES:

{"id": "abc123"}

Inspect a Dropbox shared link's target, audience, access level, and settings

When to use: When the user has a shared link URL and wants to know what it points to, who can access it, or what permissions it has.

PARAMETERS:

• url (string, required): The shared link URL to retrieve metadata for.

RESPONSE CONTRACT:

• link: Shared link metadata object.
• url: The shared link URL.
• link_type: "file", "folder", or "other".
• name: Name of the linked file or folder.
• path_lower: Lowercased path in the user's Dropbox. May be empty if the link is not in the authenticated user's Dropbox.
• audience: Effective audience - "public", "team", or "no_one".
• access_level: "view" or "edit".
• expires: Expiration in RFC 3339 format. Empty if no expiration set.
• allow_download: Whether download is allowed via this link.
• password_protected: Whether the link requires a password.
• id: file_id for the linked file/folder, if available. file_id: a Dropbox-issued file id (format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-"; example: "id:AbCd-_12"). It can identify a file or folder.

ASSISTANT POLICY:

• Use this tool to inspect a shared link before taking action on it.
• Do NOT call create_shared_link or list_shared_links unless the user explicitly asks.

ERROR CASES:

• MISSING_URL: The url field is empty.
• NOT_FOUND: The shared link does not exist or has been revoked.
• PERMISSION_DENIED: The authenticated user cannot access this shared link.
• RATE_LIMIT_EXCEEDED: Request exceeded tool rate limits.

EXAMPLES:

{"url": "https://www.dropbox.com/s/abc123/report.pdf?dl=0"} {"url": "https://www.dropbox.com/sh/xyz789/shared-folder"}

List Dropbox file requests owned by the connected user

REQUEST MODES:

• First page: send {} or {"limit": 300}. limit is optional, defaults to 300 for this MCP tool, and must be between 0 and 1000. 0 means the default. Omit cursor for first pages.
• Pagination: send {"cursor": "..."} only with a non-empty cursor from the previous response. Do not include limit with cursor.

PARAMETERS:

• limit (uint32, optional, first call only): Maximum page size. Default 300. Maximum 1000. Prefer 300 unless the user explicitly asks for larger pages.
• cursor (string, pagination only): Opaque non-empty cursor from a previous list_file_requests response. Reuse only with list_file_requests pagination. Mutually exclusive with nonzero limit.

RESPONSE CONTRACT:

• file_requests[]: Array of file request records.
• id: File request ID.
• url: Public upload URL.
• title: File request title.
• destination: Destination folder path. Empty when the destination was removed.
• created: ISO 8601 creation timestamp.
• deadline: ISO 8601 deadline timestamp. Empty when unset.
• deadline_allow_late_uploads: Grace period string: "one_day", "two_days", "seven_days", "thirty_days", or "always". Empty when unset.
• is_open: Whether the request accepts uploads.
• file_count: Number of submitted files.
• description: Optional description. Empty when unset.
• video_project_id: Optional video editor project ID. Empty when unset.
• cursor: Opaque cursor for the next page. Empty when has_more=false.
• has_more: Whether the server has more pages to scan. has_more=true means there is more data to scan but does not guarantee additional matching file requests; a page may return zero file requests with has_more=true. has_more=false means scanning is complete. Always paginate until has_more=false; do not infer completeness from file_requests count alone.

PAGINATION:

• Treat results as partial while has_more=true or cursor is non-empty.
• Continue with cursor-only calls to enumerate additional pages.
• Do not infer completeness from file_requests length alone.
• Continue pagination to exhaustion before claiming all file requests, final counts, or no more file requests.
• Pagination is live and not snapshot-stable. New file requests created after pagination begins may appear when continuing an existing cursor. Restart listing when the user wants a fresh view after mutations.

ASSISTANT POLICY:

• Use this tool when the user asks to see, list, count, audit, or summarize their Dropbox file requests.
• If cursor is set, send cursor only and drop limit.
• Ask before scanning many additional pages for exhaustive requests.

EXAMPLES:

{} {"limit": 300} {"limit": 100} {"cursor": "cursor_from_previous_response"}

Tool

Name: dropbox.list_file_revisions Purpose: List the revision history (prior versions) of a single Dropbox file. Use only when the user asks for prior versions, version history, or revisions.

PATHS:

• path_or_file_id accepts fq_path (for example "/Documents/file.txt"), ns_path (for example "ns:123//Documents/file.txt"), or file_id.
• file_id: a Dropbox-issued file id (format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-"; example: "id:AbCd-_12"). It can identify a file or folder.
• Dropbox shared/web URLs are not accepted.
• Paths are case-insensitive and must be Unicode NFC-normalized.
• Never strip the "ns:<id>//" prefix from returned paths.
• Prefer path_display when present and non-empty, both when showing returned entries to the user and in follow-on MCP calls. If path_display is absent or empty, use ns_path or file_id exactly as returned only for tools that accept file_id.

REQUEST CONTRACT:

• path_or_file_id (string, REQUIRED): Target file identifier.
• limit (integer, OPTIONAL): Number of revisions to return. Range 1-100. Default 10.

RESPONSE CONTRACT:

• entries: Newest-first revisions; always present. Each entry includes rev, file_id, name, path_display, size, server_modified, client_modified, mime_type, and content_hash.
• rev is the opaque revision identifier for that file revision.
• is_deleted: Whether the latest revision is now deleted or moved away from the requested path.
• server_deleted: Deletion or move-away timestamp when is_deleted=true.
• has_more: Upstream has more history. before_rev pagination is not exposed; raise limit up to 100 instead.

ASSISTANT POLICY:

• This tool is read-only. Use it to inspect revision history.

ERRORS (tool-level error_code values):

• INVALID_REQUEST: request is nil or malformed.
• MISSING_PATH_OR_FILE_ID: path_or_file_id is empty.
• INVALID_PATH: path_or_file_id is a malformed fq_path/ns_path or another unsupported identifier form.
• INVALID_FILE_ID: path_or_file_id uses a malformed file_id.
• INVALID_LIMIT: limit is outside 1-100.
• FILE_NOT_FOUND: Dropbox could not locate the requested file.
• PATH_NOT_FILE: path_or_file_id resolves to something other than a file.
• RESTRICTED_CONTENT, UNSUPPORTED_CONTENT_TYPE, or FILE_LOCKED: Dropbox cannot return revisions for the target because of content restrictions, unsupported content type, or lock state.
• PERMISSION_DENIED: no read access to the target.
• RATE_LIMIT_EXCEEDED, RATE_LIMITED, RESOURCE_EXHAUSTED, DEADLINE_EXCEEDED, SERVICE_BUSY, or UNAVAILABLE: request was rate-limited, timed out, or hit a temporarily unavailable dependency.

EXAMPLES:

{"path_or_file_id": "/Documents/report.pdf"} {"path_or_file_id": "ns:123//Documents/report.pdf", "limit": 25} {"path_or_file_id": "id:AbCd-_12"}

List Dropbox folder contents; supports direct children or recursive traversal

Purpose: List files and folders in Dropbox with cursor-based pagination.

PATHS:

• Input path accepts root ("" or "/"), fq_path (for example "/Documents"), or ns_path (for example "ns:123//Documents"). Dropbox shared/web URLs are not accepted.
• Namespace IDs in ns_path are decimal digits and match [0-9]+.
• Paths are case-insensitive.
• Paths must be Unicode NFC-normalized; decomposed forms are rejected.
• Use "" or "/" for root.
• Output entries[].path is always ns_path. Use this exact value for follow-on MCP calls.
• Output entries[].file_id is Dropbox-issued metadata for the entry.
• Output entries[].path_display is the fq_path. Only populated when recursive=false (children mode). Empty for recursive mode.
• Never strip the "ns:<id>//" prefix from returned paths.

REQUEST MODES:

• First call: send {"path": "..."} with optional parameters. To list root, send {"path": ""} or {"path": "/"}. Do not include cursor.
• Pagination: send {"cursor": "..."} only. Do not include path or other parameters.
• Cursor pagination returns the listing state from when the list started, not the latest folder state. To observe renames, moves, or new children after the first page, start a new list request instead of continuing the old cursor.
• For browsing a folder, set recursive=false explicitly. Omitting recursive performs a recursive scan. Recursive mode may traverse deeply and across mounted namespaces.

PARAMETERS:

• path (string, REQUIRED, first call only): Directory to list. Accepts "" or "/" for root, fq_path, or ns_path. Do not omit path in client requests. Dropbox shared/web URLs are not accepted.
• cursor (string, pagination only): Opaque non-empty cursor from a previous list_folder response. Reuse only with list_folder pagination. Mutually exclusive with all other parameters.
• object_types (string[], optional, first call only): User-facing object type filters. Valid values: "folder", "file". Empty or omitted returns all supported entries.
• Any value other than "folder"/"file" is rejected with INVALID_OBJECT_TYPES.
• "folder" includes regular folders and shared/team folder mounts.
• "file" includes regular files and cloud docs.
• For extension/category filtering, use search with path + file_extensions/file_categories.
• recursive (bool, optional, first call only): true or omitted lists all descendants recursively. false lists immediate children only (like ls).
• max_results (uint64, optional, first call only): Maximum page size. Range 0-600. Defaults to 300 when omitted or set to 0. It may return fewer entries than requested, including zero entries, even when has_more=true.

RESPONSE CONTRACT:

• entries[]: Array of object records.
• name: Basename only.
• path: ns_path. Use this exact value for follow-on MCP calls.
• modified_time: Server-side modification time in ISO 8601 when available.
• client_modified: Client-specified content modification time in ISO 8601 when available.
• file_id: Dropbox-issued metadata for the entry.
• object_type: "file" | "folder" | "mount".
• path_display: fq_path. Populated for recursive=false only. Empty for recursive mode.
• file.size: Present when object_type="file".
• folder: Empty object when object_type="folder".
• mount: Empty object when object_type="mount".
• Shared folders may surface as object_type "mount" after sharing.
• cursor: Opaque cursor for the next page. Empty when has_more=false.
• has_more: Whether the server has more pages to scan. has_more=true means there is more data to scan but does not guarantee additional matching entries; a page may return zero entries with has_more=true. has_more=false means scanning is complete. Always paginate until has_more=false; do not infer completeness from entry count alone.

ASSISTANT POLICY:

• When showing entries to the user, MUST use path_display if path_display is present. Only fall back to path (ns_path) when path_display is absent or empty.
• For interactive folder browsing, prefer recursive=false. Use recursive=true only when the user explicitly asks to scan descendants.
• Validate modes strictly: first call uses path, pagination uses cursor only. Do not send options with cursor.
• Cursor pagination is snapshot-style: continuing a cursor returns the state from when the list started. Start a new list request when the user wants the latest folder state.
• Treat results as partial while has_more=true or cursor is non-empty.
• Ask before scanning many additional pages for exhaustive requests.
• Never claim root-level completeness until pagination is exhausted.
• For follow-on MCP calls, reuse entries[].path. Use entries[].file_id only with tools whose schema accepts file_id.

EXAMPLES:

{"path": ""} {"path": "/Documents", "recursive": false} {"path": "ns:123//Documents"} {"cursor": "base64_cursor_from_previous_response"}

Tool

Name: dropbox.list_restore_events Purpose: Retrieve the history of file and folder activity in a user's Dropbox account. When to use: When the user wants to see what happened to their files - edits, deletions, moves, renames, or restores. Useful for understanding recent changes, auditing activity, or finding files to restore.

PARAMETERS:

• path (string, optional): Folder path to scope the history to. Accepts "" or "/" for root, fq_path like "/Documents", ns_path like "ns:123//Reports", or file_id. file_id: a Dropbox-issued file id (format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-"; example: "id:AbCd-_12"). It can identify a file or folder. Dropbox shared/web URLs are not accepted. File paths are not supported and will return an error.
• timestamp (uint64, optional): Starting point in time, in seconds since epoch UTC. Default (0) represents current time when direction=PAST and beginning of time when direction=FUTURE.
• direction (string, optional): Time direction to traverse: "PAST" (default, shows recent events going backwards in time) or "FUTURE" (shows events going forward from timestamp).
• cursor (string, optional): Pagination cursor from previous response to fetch the next page of results.
• only_rewindable (bool, optional): If true, only return events that the user has permission to revert/restore.

RESPONSE CONTRACT:

• events: List of file activity events, each containing:
• actor: Information about who performed the action (display_name, photo_url, type)
• op_type: Operation type (e.g., "EDIT", "DELETE", "RESTORE", "MOVE", "ADD", "RENAME")
• timestamp: Time of event in microseconds since epoch UTC
• Event-specific metadata (only one will be populated):
• edit_metadata: For EDIT operations (containing_path_display, name)
• move_metadata: For MOVE operations (from_containing_path_display, to_containing_path_display, name, is_dir)
• move_out_metadata: For MOVE_OUT operations (from_containing_path_display, name, is_dir)
• move_in_metadata: For MOVE_IN operations (to_containing_path_display, name, is_dir)
• rename_metadata: For RENAME operations (containing_path_display, from_name, to_name, is_dir)
• single_object_metadata: For ADD, DELETE, RESTORE, and sharing operations (containing_path_display, name, is_dir)
• multi_object_metadata: For operations on multiple objects (containing_path_display, file_count, folder_count)
• rollback_metadata: For ROLLBACK operations (containing_path_display, to_timestamp, name)
• has_more: Whether there are more events to fetch
• cursor: Continuation cursor for pagination

ASSISTANT POLICY:

• Use this tool when the user asks about file history, recent changes, "what happened to my file", or wants to restore deleted/modified files.
• Display events in a human-readable format with who did what, when, and to which files.
• For large histories, use pagination with the cursor to fetch additional events.
• Event timestamps are in microseconds since epoch UTC; convert them to readable dates for the user.
• This tool only lists history. For a follow-up restore, call restore_folder with the live containing folder and a target timestamp immediately before the unwanted event.
• only_rewindable=true filters the event list; restore_folder remains authoritative for restore eligibility and errors.

ERROR CASES:

• INVALID_PATH: The provided path is invalid, cannot be resolved, or points to a file (only folders are supported).
• INVALID_CURSOR: cursor was combined with other parameters, or is malformed/expired. When paginating, send only the cursor.
• INVALID_DIRECTION: direction was not "PAST" or "FUTURE".
• PERMISSION_DENIED / ACCESS_ERROR: The user does not have permission to view events in this location.
• RATE_LIMIT_EXCEEDED: Request exceeded tool rate limits.

EXAMPLES:

{"path": "/Documents", "direction": "PAST"} {"path": "ns:123//Reports", "timestamp": 1640000000, "only_rewindable": true} {"path": "id:AbCd-_12"} {"cursor": "opaque_cursor_abc123"}

List shared links owned by the connected user, optionally filtered to a folder

When to use: When the user wants to see what shared links exist for their files/folders, check if a file already has a shared link, or review their sharing activity.

PATHS:

• Input path accepts fq_path, ns_path, or file_id.
• file_id: a Dropbox-issued file id (format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-"; example: "id:AbCd-_12"). It can identify a file or folder.
• Dropbox shared/web URLs are not accepted.
• Paths are case-insensitive.
• If no path is provided, or path is "" or "/", returns all shared links for the user.
• Never strip the "ns:<id>//" prefix from returned paths.

REQUEST MODES:

• First call: optionally send path.
• Pagination: send cursor only. Do not include path.

PARAMETERS:

• path (string, optional): File or folder to list links for. Omit path to list all shared links. Only returns links directly on the specified path (no parent folder links).
• cursor (string, pagination only): Opaque non-empty cursor from a previous list_shared_links response. Reuse only with list_shared_links pagination. Mutually exclusive with path.

RESPONSE CONTRACT:

• links[]: Array of shared link entries.
• url: The shared link URL.
• link_type: "file", "folder", or "other".
• name: Name of the linked file or folder.
• path_lower: Lowercased path in the user's Dropbox. May be empty if the link is not in the authenticated user's Dropbox.
• audience: Effective audience - "public", "team", or "no_one".
• access_level: "view" or "edit".
• expires: Expiration in RFC 3339 format. Empty if no expiration set.
• allow_download: Whether download is allowed via this link.
• password_protected: Whether the link requires a password.
• has_more: Whether the server has more pages to scan. has_more=true means there is more data to scan but does not guarantee additional matching links; a page may return zero links with has_more=true. has_more=false means scanning is complete. Always paginate until has_more=false; do not infer completeness from link count alone.
• cursor: Opaque cursor for the next page. Empty when has_more=false.

ASSISTANT POLICY:

• If cursor is set, send cursor only and drop all other fields.
• Treat results as partial while has_more=true.
• Ask before scanning many additional pages.
• Do NOT automatically call create_shared_link after listing. Only create new links when explicitly asked.

ERROR CASES:

• PATH_NOT_FOUND: The specified path does not exist.
• INVALID_CURSOR: The cursor is invalid or expired. Start a new listing.
• PERMISSION_DENIED: No access to list links for this content.
• RATE_LIMIT_EXCEEDED: Request exceeded tool rate limits.

EXAMPLES:

{"path": "/Documents/report.pdf"} {"path": "/Documents"} {"path": "id:AbCd-_12"} {} {"cursor": "base64_cursor_from_previous_response"}

Move or rename one or more Dropbox files or folders

When to use: Any time the user asks to relocate, rename, or reorganize files and folders. Prefer move over a delete+create dance.

PATHS:

• Each entry's source_path accepts fq_path, ns_path, file_id, or file_id with an appended child path such as "id:AbCd-_12/name.txt".
• destination_path accepts fq_path, ns_path, file_id, or file_id with an appended child path such as "id:AbCd-_12/name.txt"; Dropbox resolves lookup, conflicts, and destination semantics.
• When the user identifies a Dropbox file or folder by name, partial path, description, or other non-canonical reference: Do not ask the user for its exact path initially; call dropbox.search to resolve the source path, passing include_folders=true when that parameter is available. For a partial destination path, use dropbox.search to resolve the path prefix, again passing include_folders=true when available.
• Namespace IDs in ns_path are decimal digits and match [0-9]+.
• file_id: a Dropbox-issued file id (format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-"; example: "id:AbCd-_12"). It can identify a file or folder.
• Dropbox shared/web URLs are not accepted.
• Paths must be Unicode NFC-normalized; decomposed forms are rejected.
• Dropbox may create missing destination parent folders during the move; no need to pre-create parent folders unless the user explicitly asks.
• Paths are case-insensitive; the same entry can cross between fq_path, ns_path, and file_id forms if needed.
• Successful entries may return object.path as ns_path and object.path_display as fq_path. Prefer object.path_display when present and non-empty, both when showing paths to the user and in follow-on tool calls. If path_display is absent or empty, fall back to object.path or object.file_id exactly as returned.
• Never strip the "ns:<id>//" prefix from returned ns_path values.

REQUEST CONTRACT:

• entries (required, 1..1000): list of { source_path, destination_path } pairs.
• autorename (optional, default false): when true, Dropbox renames the destination to avoid a conflict instead of failing that entry.

RESPONSE CONTRACT (flat lifecycle fields, MIRROR of copy/delete): When status is "completed":

• status: "completed"
• result_type: "move"
• move_result.entries[]: per-entry records in request order.
• entry_index: 0-based index into the original entries list.
• entry_status: "success" or "failed".
• object (on success): { name, file_id, object_type: "file"|"folder", path_display, file.size when file, modified_time }.

modified_time is the server-side modification time, in ISO 8601 format when available.

• failure (on failure): { error_code, message }.

When status is "in_progress":

• status: "in_progress"
• operation_id: opaque token to pass to dropbox.check_job_status.
• recommended_poll_after_ms: suggested delay before the next check_job_status call.

Job-level failures are returned as tool errors. Per-entry failures are returned in move_result.entries[] when status is "completed".

ERRORS (job-level):

• INVALID_REQUEST: entries is empty, nil, or malformed
• INVALID_ENTRY: an entries item is missing source_path or destination_path
• INVALID_PATH: source_path is not a valid fq_path/ns_path/file_id value, or destination_path is not a valid fq_path/ns_path/file_id value
• TOO_MANY_ENTRIES: more than 1000 entries submitted in one call
• INVALID_ARGUMENT: Dropbox rejected the batch as malformed

ERRORS (per-entry error_code values):

• Source lookup failures use from_lookup/* codes, such as from_lookup/not_found, malformed paths, non-file/non-folder targets, restricted content, unsupported content type, or locked content.
• Source write failures use from_write/* codes for conflicts, malformed paths, missing write permission, space/quota issues, disallowed names, team-folder constraints, suppressed operations, too many write operations, or access restrictions.
• Destination write failures use to/* codes for destination conflicts, malformed paths, missing write permission, space/quota issues, disallowed names, team-folder constraints, suppressed operations, too many write operations, or access restrictions.
• Move-specific constraints include cant_move_folder_into_itself, cant_move_shared_folder, and cant_move_into_family.
• Batch, sharing, permission/quota, and temporary failures include duplicated_or_nested_paths, too_many_files, cant_copy_shared_folder, cant_nest_shared_folder, cant_transfer_ownership, insufficient_quota, too_many_write_operations, and internal_error.
• unknown_error means server returned an error variant this tool does not recognize.

DUPLICATE DESTINATION QUIRK:

• For duplicate destinations in one batch, later entries may report from_write/conflict even though the practical cause is a destination collision. Report it to the user as a destination conflict.

RETRY GUIDANCE:

• If status is "in_progress", call dropbox.check_job_status with the returned operation_id.
• Do NOT retry the entire batch on per-entry failures; report the specific failures to the user.
• too_many_write_operations and internal_error are transient — retry after a short delay if appropriate.

EXAMPLES:

{"entries": [{"source_path": "/Docs/old.txt", "destination_path": "/Docs/new.txt"}]} {"entries": [{"source_path": "ns:123//A.txt", "destination_path": "ns:123//Archive/A.txt"}], "autorename": true} {"entries": [{"source_path": "id:AbCd-_12", "destination_path": "/Inbox/renamed.pdf"}]} {"entries": [{"source_path": "/Docs/old.txt", "destination_path": "id:AbCd-_12/new.txt"}]}

ASSISTANT POLICY:

• Before calling this tool, the assistant MUST summarize the exact mutation plan and get explicit user confirmation in chat.
• The assistant MUST NOT claim the mutation already happened until the tool returns a successful response.
• After a successful response, the assistant MUST clearly list exactly what changed, using returned paths, file_id values, status values, and URLs when available.
• If the response represents partial success, the assistant MUST separate the succeeded and failed parts explicitly. When both shared_with and share_errors are present, report each list separately.
• After a successful response, the assistant MUST tell the user how to revert the change.
• For created files or folders, tell the user you can revert by calling dropbox.delete on the returned path_display after separate explicit confirmation.
• For deleted files or folders, tell the user they can restore deleted content and include https://help.dropbox.com/delete-restore/recover-deleted-files-folders.
• When recovering an older file version is relevant, include https://help.dropbox.com/delete-restore/recover-older-versions.
• For sharing changes, instruct the user to manage or revoke sharing from the Dropbox web UI and include https://help.dropbox.com/share/unshare-folder.
• Dropbox path handling: path_display is the preferred path. Always use path_display when it is present and non-empty, both in user-facing output and in follow-on tool calls. If path_display is absent or empty, fall back to the returned path/file_id exactly as provided.

Tool

Name: dropbox.restore_file_revision Purpose: Write the contents of a prior revision identified by rev to destination_path. The destination receives a new file revision containing those prior contents.

PATHS:

• destination_path accepts fq_path (for example "/Documents/file.txt") or ns_path (for example "ns:123//Documents/file.txt"). file_id is NOT accepted.
• Dropbox shared/web URLs are not accepted.
• Paths are case-insensitive.
• destination_path and rev must be in the same namespace.
• Never strip the "ns:<id>//" prefix from returned paths.

WRITE WARNING:

• This tool upserts the rev's contents to destination_path. It is not limited to the file the rev originally came from.
• If destination_path does not exist, restore creates a new file there from the rev's contents.
• If destination_path already exists, restore overwrites that file's content, even when it is an unrelated file.
• Any valid rev can be written to any writable destination_path in the same namespace. There is no guard that checks whether the rev belongs to the destination file.
• Restoring a deleted file's last rev to its old path can resurrect that file.

REQUEST CONTRACT:

• destination_path (string, REQUIRED): Destination path where the prior revision's contents will be written.
• rev (string, REQUIRED): Revision hash to restore. Obtain from a prior list_file_revisions or get_file_metadata response.

RESPONSE CONTRACT:

• file: object describing the file at destination_path after the restore.
• name, path, modified_time, file_id
• modified_time is the server-side modification time, in ISO 8601 format when available.
• object_type: "file"
• file.size: File size in bytes.
• path_display: fq_path for human display when populated.
• rev: Revision hash of the current/returned state of the file. This is a new rev distinct from the rev that was restored.
• Prefer path_display when present and non-empty, both when showing the returned file to the user and in follow-on MCP calls. If path_display is absent or empty, fall back to path (ns_path). Use file_id only for tools that explicitly accept it; restore_file_revision does not.

ASSISTANT POLICY:

• Before calling this tool, the assistant MUST summarize the exact mutation plan and get explicit user confirmation in chat.
• The assistant MUST NOT claim the mutation already happened until the tool returns a successful response.
• After a successful response, the assistant MUST clearly list exactly what changed, using returned paths, file_id values, status values, and URLs when available.
• If the response represents partial success, the assistant MUST separate the succeeded and failed parts explicitly. When both shared_with and share_errors are present, report each list separately.
• After a successful response, the assistant MUST tell the user how to revert the change.
• For created files or folders, tell the user you can revert by calling dropbox.delete on the returned path_display after separate explicit confirmation.
• For deleted files or folders, tell the user they can restore deleted content and include https://help.dropbox.com/delete-restore/recover-deleted-files-folders.
• When recovering an older file version is relevant, include https://help.dropbox.com/delete-restore/recover-older-versions.
• For sharing changes, instruct the user to manage or revoke sharing from the Dropbox web UI and include https://help.dropbox.com/share/unshare-folder.
• Dropbox path handling: path_display is the preferred path. Always use path_display when it is present and non-empty, both in user-facing output and in follow-on tool calls. If path_display is absent or empty, fall back to the returned path/file_id exactly as provided.

ERRORS:

• INVALID_REQUEST / MISSING_PATH / MISSING_REV: input validation
• INVALID_PATH: destination_path is malformed
• FILE_NOT_FOUND / PATH_NOT_FOUND: backend could not locate a required path while preparing the restore. A valid nonexistent destination_path may still be creatable.
• INVALID_REVISION: rev is unknown, outside the restorable window, or in a different namespace from destination_path
• PERMISSION_DENIED: no write access to destination_path
• RESTORE_IN_PROGRESS: restore was accepted, but the restoration work needs more time than this tool monitors for. The restore may still complete after this error.
• FILE_LOCKED: destination file is locked

RETRY GUIDANCE:

• On RESTORE_IN_PROGRESS, do not assume failure. Wait briefly, check destination_path metadata or contents if possible, and retry with the same arguments only if the destination still is not restored.
• Do NOT retry on INVALID_REVISION; the rev is not restorable.

EXAMPLES:

{"destination_path": "/Documents/report.pdf", "rev": "a1c10ce0dd78"} {"destination_path": "ns:123//Projects/image.png", "rev": "0123456789ab"}

Tool

Name: dropbox.restore_folder Purpose: Restore a folder to a previous state by rewinding all changes back to a specific point in time. When to use: When the user wants to undo changes to a folder and restore it to how it looked at an earlier time. This is useful for recovering from accidental deletions, unwanted edits, or reverting to a known-good state.

PARAMETERS:

• path (string, required): Path to the folder to restore. Accepts fq_path, ns_path, or file_id. file_id: a Dropbox-issued file id (format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-"; example: "id:AbCd-_12"). It can identify a file or folder. Dropbox shared/web URLs are not accepted.
• target_ts_microseconds (uint64, required): Target timestamp to restore to, in microseconds since epoch UTC. The folder will be rewound to this point in time.
• is_team (boolean, optional): Whether this is a team restore. Defaults to false. When false, affects individual and shared folder content but not team-owned content. When true, affects team-owned content.

RESPONSE CONTRACT:

• operation_id: Signed operation token for this restore operation. Pass this to check_job_status to poll for completion. This is an encrypted, signed token containing the restore job ID and user binding.

ASSISTANT POLICY:

• Use this tool when the user wants to restore a folder to a previous state or undo recent changes.
• Ask the user to confirm before proceeding - folder restores are significant operations.
• Convert human-readable dates/times to microseconds since epoch UTC when constructing target_ts_microseconds.
• Explain that the restore is asynchronous and returns immediately with an operation ID.
• After calling this tool, use check_job_status with the returned operation_id to poll for completion.
• Pass operation_id unchanged. On INVALID_OPERATION_ID, do not re-poll with the same token; start a new restore operation only if the user still wants the restore.
• On completion, report restore_folder_result, including the restored path and file/folder counts.
• For team restores, set is_team=true only when explicitly requested and the user has appropriate permissions.
• To recover a deleted child, restore its live containing folder to a timestamp immediately before the deletion. Do not target the deleted path itself.
• Apply ACCOUNT ELIGIBILITY and ERROR CASES below before retrying or suggesting an alternate restore scope.

IMPORTANT NOTES:

• This operation is asynchronous. The API returns immediately with an operation ID, but the actual restore happens in the background.
• Use check_job_status to poll for completion status.
• Folder restores affect all content within the folder, including subfolders.
• Team restores require appropriate team admin permissions.

ACCOUNT ELIGIBILITY (who can restore, and from where):

• Eligible paid personal accounts: "/" can rewind the whole account scope, while a specific live folder limits the restore to that folder tree.
• Plans without Rewind: the tool returns REWIND_NOT_SUPPORTED_BY_PLAN. This means the plan does not support Rewind, not that the actor lacks permission. There is no path or argument change that makes the restore succeed; see https://help.dropbox.com/delete-restore/rewind for currently eligible plans.
• Team accounts: "/" is the team member root and is never a valid restore target; it returns TEAM_MEMBER_ROOT_NOT_RESTORABLE before RewindsStart. Target a specific writable folder instead. Rewind availability is also controlled by team policy and is admin-only by default unless an admin enables it for members. Team-owned content restores require is_team=true, edit access to the team folder, and the required team permission.
• These outcomes are plan/scope policy, not transient errors. Do not retry; surface the explanation to the user.

ERROR CASES:

• PATH_REQUIRED: No path was provided.
• TARGET_TIMESTAMP_REQUIRED: No target timestamp was provided.
• INVALID_PATH: The provided path is invalid or cannot be resolved. Note: a DELETED child folder path resolves to INVALID_PATH (the live object no longer exists); restore the live PARENT folder to recover deleted children instead of targeting the deleted child directly.
• PATH_NOT_FOLDER: The provided path points to a file instead of a folder.
• PATH_DELETED: The provided path points to a deleted object.
• TEAM_MEMBER_ROOT_NOT_RESTORABLE: The authenticated team member root "/" is not a valid restore target. Choose a specific live folder. Not retryable with the same path.
• INSUFFICIENT_PERMISSIONS: The actor does not have permission to restore the requested scope. On a team account, target a specific writable folder or ask a team admin to enable Rewind for members. Not retryable with the same path and permissions.
• REWIND_NOT_SUPPORTED_BY_PLAN: Folder restore (Rewind) is not supported by this account plan. See https://help.dropbox.com/delete-restore/rewind. Not retryable.
• INVALID_ARGUMENTS: The restore request arguments were rejected by the backend (bad path, timestamp, or namespace scope).
• INVALID_OPERATION_ID: check_job_status rejected the operation token because it is missing, malformed, expired, issued to a different user, or invalid for the Rewind status endpoint. Not retryable with the same token.
• RATE_LIMIT_EXCEEDED: Request exceeded tool rate limits.

EXAMPLES:

{"path": "/Documents/Projects", "target_ts_microseconds": 1640000000000000} {"path": "ns:123//Reports", "target_ts_microseconds": 1640000000000000} {"path": "id:AbCd-_12", "target_ts_microseconds": 1640000000000000, "is_team": true}

Search Dropbox files and folders by name or content, with optional filters

REQUEST:

• New search: non-empty query is required. Optional filters and sorting parameters can scope or refine results.
• max_results controls the maximum number of results returned by a new search. It accepts 1-1000 and defaults to 100 when omitted.
• Pagination: send only the non-empty opaque cursor returned by a previous search response. Do not include query or filters with cursor.
• search_mode is optional. Omit it to use Dropbox's default search behavior, or set it to "title_only" to search filenames only. Semantic retrieval, when available, is selected automatically by Dropbox rather than through search_mode.
• Do not combine search_mode="title_only" with filename_only=false; filename_only=true is accepted for compatibility.

INPUT SHAPES:

• path accepts fq_path or ns_path.
• Namespace IDs in ns_path are decimal digits and match [0-9]+.

RESPONSE:

• results: Unified search results
• id (string, required): Tool-ready identifier when the result has a Dropbox file_id; otherwise an empty string. Format: "id:<id>", where <id> uses A-Z, a-z, 0-9, "_" and "-". Example: "id:AbCd-_12".
• title (string, required): File or folder basename. Example: "quarterly-report.pdf".
• url (string, required): Openable Dropbox URL supplied directly by Fileverse search; empty when unavailable. Example: "https://www.dropbox.com/home/Reports/quarterly-report.pdf".
• path (string, optional): Namespace-qualified path for follow-on calls. Example: "ns:123//Reports/quarterly-report.pdf".
• path_display (string, optional): Human-readable display path. Example: "/Reports/quarterly-report.pdf".
• object_type (string, optional): Result kind, such as "file", "folder", "paper", or "deleted". Example: "file".
• match_type (string, optional): Where the query matched, such as "FILENAME", "FILE_CONTENT", or "BOTH_FILENAME_AND_CONTENT". Example: "FILENAME".
• mime_type (string, optional): MIME type when available; omitted for folders. Example: "application/pdf".
• size (integer, optional): File size in bytes; omitted when zero. Example: 2048.
• last_modified (string, optional): ISO 8601 modification timestamp. Example: "2026-03-24T17:04:05Z".
• rank (integer, optional): 1-based rank in the Fileverse search result stream; omitted when zero. Example: 1.
• has_more, cursor, total_results: Pagination fields populated in advanced/raw mode

NOTES:

• Query-only requests use simplified search: they return up to 100 active file results, never return folders, and do not include pagination fields.
• To return folders, specify include_folders. Providing this parameter activates advanced mode.
• Any extra parameter beyond query, or any cursor call, switches search into advanced mode.
• Search may return files that later fail text extraction in fetch.

EXAMPLES: {"query": "quarterly reports"} {"query": "quarterly reports", "max_results": 25} {"query": "quarterly reports", "search_mode": "title_only"} {"query": "projects", "include_folders": true} {"query": "budget", "path": "/Documents", "file_categories": ["PDF"], "order_by": "last_modified"} {"query": "budget", "path": "ns:123//Documents", "file_categories": ["PDF"], "order_by": "last_modified"} {"cursor": "base64_cursor_from_previous_response"}

Tool

Name: dropbox.upload_file Purpose: Upload a file from the current conversation to Dropbox. When to use: When the user explicitly asks to save a file (attachment, generated artifact, or file-library selection) to a specific Dropbox destination.

BEHAVIOR:

• upload_file saves files from the conversation to Dropbox using the ChatGPT

openai/fileParams adapter.

• Do NOT construct source_file manually; it is always injected by ChatGPT.

ASSISTANT POLICY:

• Before calling, ensure the source file and exact Dropbox destination are unambiguous.
• An explicit user request to upload or save an unambiguous source file to a

complete fq_path or ns_path destination (including the filename) counts as explicit user confirmation; do NOT ask for separate confirmation.

• If the source file or exact destination is missing or ambiguous, ask the user to

clarify before calling.

• Do NOT call without an explicit user request.
• Do NOT pass free-form URLs, only files provided through the ChatGPT file parameter.
• If Dropbox normalization changes the final path, show it and confirm again.

PATHS:

• Input destination_path accepts fq_path or ns_path.
• Namespace IDs in ns_path are decimal digits and match [0-9]+.
• file_id and Dropbox shared/web URLs are not accepted as destination.
• Paths are case-insensitive.
• Parent must exist. This tool does not create missing parent folders.

REQUEST CONTRACT:

• destination_path (string, REQUIRED): Full Dropbox path including filename.
• source_file (object, REQUIRED): File object injected by ChatGPT file parameter.

Do NOT construct this manually.

RESPONSE CONTRACT: When status is "completed":

• status: "completed"
• file: object with name, path, modified_time, file_id, object_type, file.size,

path_display.

When status is "in_progress":

• status: "in_progress"
• operation_id: opaque token for polling via dropbox.check_upload_file_status.

ERRORS:

• INVALID_PATH: destination path is empty or invalid
• INVALID_SOURCE_FILE: source_file is missing, is missing download_url, contains

unknown fields, or download_url points at a host not permitted for ChatGPT fileParam uploads

• PARENT_NOT_FOUND: parent path doesn't exist
• ALREADY_EXISTS: file exists at target path (do NOT retry with same path;

ask the user for a different name or location)

• PERMISSION_DENIED: no write access
• QUOTA_EXCEEDED: account storage quota exceeded
• RATE_LIMITED: too many concurrent requests; retry after delay
• TEAM_ROOT_NOT_WRITABLE: cannot write directly in team root

RETRY GUIDANCE:

• Do NOT retry on ALREADY_EXISTS or TEAM_ROOT_NOT_WRITABLE.
• Follow the ASSISTANT POLICY above before calling; an explicit request with an

unambiguous source file and exact destination is sufficient explicit user confirmation.

• MUST NOT claim the mutation already happened until the tool returns a successful response.
• Use dropbox.check_upload_file_status to poll async operations.

how to revert the change:

• Use dropbox.delete to remove the uploaded file.
• https://help.dropbox.com/delete-restore/recover-deleted-files-folders
• https://help.dropbox.com/delete-restore/recover-older-versions
• https://help.dropbox.com/share/unshare-folder

EXAMPLES:

{"destination_path": "/Documents/report.pdf", "source_file": {"download_url": "https://files.oaiusercontent.com/report.pdf", "file_id": "file-abc123", "mime_type": "application/pdf", "file_name": "report.pdf"}} {"destination_path": "ns:123//Projects/image.png", "source_file": {"download_url": "https://files.oaiusercontent.com/image.png", "file_id": "file-xyz789"}}

Get the connected Dropbox user's identity, team, and namespace roots

PARAMETERS: None required.

RESPONSE CONTRACT:

• account_id: Public Dropbox account ID (pid_eci)
• display_name: User's full display name
• email: User's email address
• country, locale: Account profile fields from the authenticated user context
• team_id, team_name: Team fields. team_id is a public Dropbox team ID (pid_eci). If omitted, this is a personal account. If present, this is a team account.
• root_namespace_id, home_namespace_id: Namespace root fields for interpreting Dropbox paths

ASSISTANT POLICY:

Use this when the user asks who they are signed in as, what team/account Dropbox MCP is using, or when you need the user's root namespace or home namespace for path reasoning.