Dropbox

Return a list 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. 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.

Tool Name: dropbox.get_file_metadata Purpose: Get detailed metadata for a file or folder, including sharing info and permissions. 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"}

Tool Name: dropbox.get_file_request Purpose: Retrieve metadata for one Dropbox file request by raw file 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"}

Tool Name: dropbox.get_shared_link_metadata Purpose: Get metadata for a shared link given its URL. 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"}

Tool Name: dropbox.list_file_requests Purpose: List Dropbox file requests owned by the authenticated user with cursor-based pagination. 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"}

Tool Name: dropbox.list_folder Purpose: List files and folders in Dropbox with cursor-based pagination. Supports recursive (default) and children-only modes. 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: 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"}

Tool Name: dropbox.list_shared_links Purpose: List shared links owned by the authenticated user, optionally filtered to a specific path. 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"}

Tool Name: dropbox.move Purpose: Move one or more files/folders in Dropbox as a single batch. 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. - 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 }. - 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, cant_move_into_vault, 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 - 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 with one public tool that supports both simplified and advanced search flows. REQUEST: - New search: non-empty query is required. Optional filters and sorting parameters can scope or refine results. - Pagination: send only the non-empty opaque cursor returned by a previous search response. Do not include query or filters with cursor. 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: Tool-ready file identifier when a file_id is present. 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. - title: File or folder name - url: Openable Dropbox URL supplied directly by Fileverse search. - path, path_display, object_type, match_type, mime_type, size, last_modified, rank: Additional search result fields when available - has_more, cursor, total_results: Pagination fields populated in advanced/raw mode NOTES: - Query-only requests use simplified search: they return up to 20 active file results and do not include pagination fields. - 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": "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.who_am_i Purpose: Get identity, team, and namespace-root information for the authenticated Dropbox user. 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.