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_file_metadata

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"}

get_file_request

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"}

get_shared_link_metadata

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"}

list_file_requests

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_file_revisions

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"}

list_folder

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, is_dir) - 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_restore_events

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"}

list_shared_links

Internal MCP app widget bridge for client logging events.

client_log_proxy

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.

move

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.

file_preview

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"}

restore_file_revision

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}

restore_folder

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"}

search

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. - modified_time is the server-side modification time, in ISO 8601 format when available. 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"}}

upload_file

Apply an explicit complete Paper title/body state with three-way merge. Use for a new document body, major rewrite, or restructuring. Prefer paper_edit_content or paper_edit_table for small surgical edits, active comment anchors, task metadata, or partial table changes. Workflow: call paper_read_document, build the desired complete body, then call once with its revision. doc_ref: file ID, pad ID, or Dropbox URL. base_revision: required revision returned by paper_read_document. body_markdown: complete desired body only; do not prepend the Paper title. Empty clears the body. A leading H1 remains a body heading. Use real newlines. title: desired title when changing it; empty preserves the current title. Supported Markdown includes headings, bullets, numbered items, tasks, tracked tasks, decisions, quotes, fenced code, tables, and common inline formatting. # Dropbox Paper Formatting Paper makes each empty Markdown line a visible blank block; adjacent prose has no margin. User templates, explicit styling, and deliberate existing formatting win. Repair accepted documents locally. One source line per prose paragraph; let Paper wrap and split paragraphs longer than about four rendered lines. Put exactly one blank between prose paragraphs, none doubled or trailing. Keep compact metadata lines consecutive. Set the document title in its field; do not repeat it as a body H1. Use H1, H2, and H3 for main sections, subsections, and deeper sections according to the document outline. Add one blank before headings after prose/lists, none after preamble/heading/table/divider, and none after headings. Colon lead-ins touch lists; list items are consecutive and single-line unless nested. One blank follows a list before prose/heading. All-bold standalone lines become H3; write `**Next steps**:` (colon outside bold) for a bold prose label. Tables: short header labels, preferably two or three columns, no adjacent blanks. A separator row (`| --- | --- |`) immediately after the first row sets a native top header; omit it for a table without a header. Reads preserve the separator when a header exists. Bold labels alone do not set a header. Remove the separator, not row 0, to remove header styling while retaining all cell content. Dividers mark major mode changes only, usually zero to two, without adjacent blanks. After writing, re-read canonical revision and structural spacing; inspect live Paper when available, report limits, and repair only affected blocks. Do not depend on CSS pixels/colors. Check prose-to-prose, heading-to-body, colon-to-list, list-to-prose, table header, divider, and document end in the live surface. Without it, do not claim rendered spacing. Mentions in body_markdown use @<user_ref>, where user_ref is "me", a decimal Dropbox user ID, a dbid, or an exact email. Use \@<...> for literal text; bare @name remains plain text. Mentions are ignored inside inline/fenced code and link destinations. A target must resolve to exactly one active account that already has explicit document access; organization membership alone is not sufficient. Mentioning never provisions a user or grants access. Unknown, inactive, ambiguous, and ineligible refs all reject the whole apply with the same non-identifying error. Verify the exact email or user ID; if the intended user is not already a collaborator, ask the user to share the document first. The title is always plain text: @<...> in title is stored literally. Returns new_revision, canonical merged body_markdown/title, doc_id, diff, and any conflicts. After success, replace local state with the returned canonical state; it includes non-overlapping concurrent human edits. Re-read with paper_read_document to verify the new revision, content, and formatting. Concurrency: non-overlapping edits merge. Overlapping edits fail without applying changes; re-read and rebuild from the new state. Limitations on changed lines: - Comment anchors can be destroyed. - Tables are atomic; a cell change replaces the table and can overwrite concurrent cell edits. - Markdown cannot faithfully represent every Paper embed, tracked-task attribute, or rich format. - Inserted lines receive new section IDs. Never retry an unknown mutation outcome without re-reading.

Add a Paper comment thread, reply to a thread, or resolve a thread. Supply exactly one of add, reply, or resolve. Use for discussion/review state, not document content edits. add: - Call paper_read_document first. - section_id, zero-based section_line, and receipt come from section_lines[]. - text is comment text (max 10,000 characters). Create a mention with @<user_ref>, where user_ref is me, a decimal Dropbox user ID, a dbid, or an exact email. Use \@<...> for literal text; bare @name remains plain text. - A target must resolve to exactly one active account that already has explicit document access; organization membership alone is not sufficient. Mentioning never provisions or grants access. Only existing explicit collaborators are subscribed or notified. Unknown, inactive, ambiguous, and ineligible refs fail the whole comment mutation with the same non-identifying error. Verify the exact email or user ID; if the intended user is not already a collaborator, ask the user to share the document first. - Reads render mentions as @<user_id>; use users[] for the current display_name and email. - optional anchor_text must exactly match visible text on the target line. - optional cell {row,col} targets a 0-based table cell; anchor_text then matches within that cell. reply: - thread_id comes from paper_read_document or an earlier comment result. - text follows the same mention syntax and eligibility rules as add.text. - A receipt/read is unnecessary when a valid thread_id is already known. resolve: - thread_id comes from paper_read_document. - receipt is the containing section's receipt: match the thread section_id to sections[].id. Returns available new_revision, thread_id, comment_id, and diff. Show the diff to the user. Resolving is destructive to active discussion state. Invalid/stale anchors fail without applying; re-read before retrying. Do not blindly retry an unknown comment outcome.

Create a new empty Paper document. Use when the user asks for a new Paper doc. Do not use to edit an existing doc. title: required document title. Do not duplicate it as an H1 when adding the body; follow the Dropbox Paper Formatting guidance in paper_read_document. dir_path: optional folder path within the user's personal Dropbox. For users on a team, this may be either a home-relative path such as `/Paper Docs` or an account-root path through the mounted personal folder, such as `/John Doe/Paper Docs`. Team-space folders are not supported. Omit unless the user requested a location. Returns doc_id, URL, and file_path. Call paper_read_document with doc_id before adding content so later writes use current receipts. Failures leave no usable document result; do not invent an ID.

Atomically edit Paper title and non-table body content. One call may update lines, delete lines, replace exact text, and update the title. Use for surgical or mixed edits. Do not use for table cells/dimensions, inserting new blocks, or bulk document restructuring. Precondition: call paper_read_document for current addresses and receipts. Follow its Dropbox Paper Formatting guidance; preserve deliberate existing formatting and make local repairs. At least one operation is required. All operations succeed in one revision or none apply. update_lines[] targets an existing line with section_id, zero-based section_line, and line receipt. markdown is the complete replacement line. Markdown prefixes can change paragraph/heading/list/task type. Code-block type is preserved. Use completed or uncompleted for task state; do not set both. Tracked tasks additionally accept due_date, assignees (including "me"), clear_due_date, and clear_assignees. Mentions in update_lines[].markdown and find_and_replace[].replace use @<user_ref>, where user_ref is "me", a decimal Dropbox user ID, a dbid, or an exact email. Use \@<...> for literal text; bare @name remains plain text. Tracked-task assignees[] accepts the same bare user_ref forms without @<...> wrapping. Mentions are ignored inside inline/fenced code and link destinations. A target must resolve to exactly one active account that already has explicit document access; organization membership alone is not sufficient. Mentioning never provisions a user or grants access. Unknown, inactive, ambiguous, and ineligible refs all reject the entire edit with the same non-identifying error. Verify the exact email or user ID; if the intended user is not already a collaborator, ask the user to share the document first. update_title.text is always plain text, so @<...> is stored literally there. delete_lines[] targets lines with section_id, section_line, and line receipt. The server safely orders deletions. Never target readonly or synthetic terminal lines. find_and_replace[] performs document-wide exact visible-text replacements. search must be non-empty. Use when the intended match is unambiguous; otherwise use addressed line updates. Multiple replacements run in request order inside the same atomic mutation. update_title is present only when changing the title: - text is the new title; empty text clears it. - receipt is title_receipt from paper_read_document. Line-update rules: - Plain text demotes promotable lines to paragraphs; prefixes promote supported types. - Tracked tasks, decisions, and tables cannot be converted through a line update. - Replacing a table line cannot change its dimensions; use paper_edit_table. - Heading edits can change section structure, so re-read afterward. Conflicting/overlapping operations in the same request are rejected rather than ordered ambiguously. Stale receipts or any invalid target fail the entire batch with no changes. Returns new_revision and a combined diff. Show it to the user. Re-read after every successful content mutation to verify its revision and formatting, and after stale errors before retrying.

Atomically edit one existing Paper table. One call may update cells and add, delete, or move rows and columns. Use instead of reconstructing table Markdown. Do not target multiple tables or non-table lines. Paper Markdown represents a native top header with a separator row (`| --- | --- |`) immediately after the first row; without the separator, the table has no header. Reads preserve this state. Bold first-row labels alone do not set a native header. paper_edit_table preserves the header state and has no header-toggle field; use paper_apply_markdown to add or remove the separator. The separator is not a cell row and does not count toward row indices. Do not delete row 0 to remove header styling while retaining its content. Markdown does not expose a separate sticky-header setting; verify live behavior before claiming it. Precondition: call paper_read_document. Follow its Dropbox Paper Formatting guidance for tables; preserve deliberate existing structure and formatting. Set doc_ref, the table line's section_id/zero-based section_line, and its line receipt. At least one operation is required. update_cells[]: 0-based row/col plus complete cell Markdown. Empty clears a cell. Supports inline formatting, links, images, and multi-line cell content. Do not use horizontal-rule syntax as a structured cell type. Mentions in update_cells[].markdown and add_rows[]/add_columns[] cells use @<user_ref>, where user_ref is "me", a decimal Dropbox user ID, a dbid, or an exact email. Use \@<...> for literal text; bare @name remains plain text. Mentions are ignored inside inline/fenced code and link destinations. A target must resolve to exactly one active account that already has explicit document access; organization membership alone is not sufficient. Mentioning never provisions a user or grants access. Unknown, inactive, ambiguous, and ineligible refs all reject the whole table edit with the same non-identifying error. Verify the exact email or user ID; if the intended user is not already a collaborator, ask the user to share the document first. add_rows[]: after_position is the 0-based row to insert after; cells must match the current column count. add_columns[]: after_position is the 0-based column to insert after; cells must match the current row count. delete_rows[] / delete_columns[]: position is the 0-based index. move_rows[] / move_columns[]: from_position and to_position are 0-based indices. Operations execute in listed field order against one atomic plan: 1. cell updates 2. row additions 3. column additions 4. row deletions 5. column deletions 6. row moves 7. column moves Indices for later operations refer to the table state after earlier operations. Prefer one coherent request and avoid targeting a row/column both before and after its deletion. Any stale receipt, invalid index, duplicate cell, dimension mismatch, or conflicting operation rejects the entire batch with no changes. Returns new_revision and a whole-table diff. Show it to the user, then re-read to verify the new revision, table structure, and formatting before another table edit; dimensions/indices may have changed.

Get Paper document history with authors and diffs. Use it to answer what changed, how a document’s themes evolved, or who contributed to a change. Do not use it to read the current document structure or obtain edit receipts. doc_ref accepts a file ID, pad ID, or Dropbox URL. since accepts rev:1042, a relative duration such as -3h/-7d/-30m, or an RFC 3339 timestamp. Empty since keeps its existing seven-day default. Leave grouped=false (the default) for the aggregate author-annotated diff over that time window. Prefer grouped=true for large history reads; it returns the Paper UI edit sessions in chronological revision order. Use limit to request up to 20 sessions (0 defaults to 20). Pages may contain fewer sessions to stay within processing and size budgets. For the first grouped page, omit after_revision; for every later page, repeat the same since and set after_revision to the prior next_after_revision. Continue even when a page is shorter than limit; stop only when next_after_revision is 0. For example: call with since="-7d", grouped=true, limit=20; then call again with those values plus the returned next_after_revision. Returns canonical doc_id, revision bounds, and either aggregate authors plus diff, or per-session history_entries with author-annotated diffs. This is evidence, not a mutation receipt. Use paper_read_document for current addresses and receipts. Invalid since, after_revision, or limit fails without changing the document. Aggregate history is limited to 10,000 revisions in the requested time range. Grouped pages stop before exceeding 10,000 revisions, or when their processing or size budget is reached, and return a continuation for the remaining sessions. A single session that exceeds a revision or size limit returns an error; a smaller page limit cannot split it. Request aggregate history for a shorter range within the 10,000-revision cap, or a later grouped range that excludes the session. If processing time is exhausted before any session can be returned, retry the same page.

Insert one or more new Paper lines without replacing existing content. Use exactly one placement: in_section, after_line, or at_document_end. Do not use for images or modifying existing lines. Precondition: call paper_read_document and use current addresses/receipts. doc_ref: prefer returned doc_id. lines[].markdown: each item is one logical Paper block. A fenced code block or complete pipe-delimited table must be one item and may contain newlines. Mentions in lines[].markdown use @<user_ref>, where user_ref is "me", a decimal Dropbox user ID, a dbid, or an exact email. Use \@<...> for literal text; bare @name remains plain text. Mentions are not parsed inside inline/fenced code or link destinations. A target must resolve to exactly one active account that already has explicit document access; organization membership alone is not sufficient. Mentioning never provisions a user or grants access. Unknown, inactive, ambiguous, and ineligible refs all reject the whole insert with the same non-identifying error. Verify the exact email or user ID; if the intended user is not already a collaborator, ask the user to share the document first. Placements: - in_section: section_id and section receipt. Default appends to the section body; at_start=true inserts immediately after its heading. Use section_id="preamble" with at_start=true for the document top. - after_line: section_id, zero-based section_line, and section receipt. Inserts after that line. - at_document_end: receipt of the final section from paper_read_document. Markdown prefixes auto-promote headings, lists, tasks, quotes, code blocks, tables, and horizontal rules. Follow the Dropbox Paper Formatting guidance in paper_read_document, including the spacing at the insertion boundaries. All lines insert atomically in one revision. Returns new_revision and diff. Show the diff to the user. Failure behavior: - Supplying zero or multiple placements is invalid. - Empty lines is invalid. - A stale receipt fails without applying the insert; re-read and retry. - After success, re-read to verify the new revision, inserted content, and formatting before another addressed edit; line positions may shift.

Upload image bytes and insert the image into a Paper section. Use for local/generated image data. Do not use for Markdown text or an already-hosted Markdown image URL. Precondition: call paper_read_document. doc_ref: prefer returned doc_id. data: base64-encoded image bytes only. filename: filename with a correct image extension. section_id and receipt: section and current section receipt from the read. section_line: zero-based line after which to insert; 0 inserts after a non-preamble heading. alt_text: concise accessible description. Returns new_revision, hosted URL, and diff. Show the diff to the user. On stale receipt, re-read and retry. Do not blindly retry an unknown upload outcome.

List the caller's recently active Paper documents. Use to discover a doc when its ID or link is unknown. Do not use for full-text search or reading contents. edited_only=true returns docs recently added or edited. viewed_only=true returns docs recently viewed. Leave both false for both activity types. They are mutually exclusive. limit is 1-50; 0 defaults to 20. Returns docs in activity order with doc_id, title, timestamp, and relative time. Pass doc_id to paper_read_document. Deleted/unresolvable docs may be omitted.

Read a Paper document. Call before addressed edits, comments, or when current content matters. Returns canonical identity, revision, sections, editable lines, receipts, and threads. doc_ref accepts a Dropbox file ID ("id:..."), Paper pad ID, or Dropbox URL. Prefer the returned doc_id in later calls. only_sections=true returns document/section metadata without bodies or threads; use for low-token structure discovery. section_ids returns bodies and threads only for the named sections while still returning the full section index. Unknown IDs fail. Do not combine section_ids with only_sections. Returns: - revision: use as paper_apply_markdown.base_revision. - title and title_receipt. - sections[] with id, display_path, receipt. Section receipts authorize section inserts and resolving threads. - users[] is one unique, document-level identity directory for users referenced by the stored body, comments, or tracked-task metadata. Each entry contains stable user_id plus current email and display_name. Order is unspecified. only_sections=true omits users; section_ids filtering still returns the whole document directory. - Mentions in body, table, and comment text are always returned as @<user_id>. Look up user_id in users[] for current display details. Tracked-task lines keep their association in tracked_task.assignees. Titles are plain text and never expose mentions. The stable text form prevents an email or display-name change from changing document meaning. users[] is safe from enumeration because it is derived only from mentions already embedded in a document the caller can read; it is not a people-search result. Write eligibility requires existing explicit document access when a reference is created. A stored reference remains readable if document access changes later. - section_lines[] with section_id, zero-based section_line, markdown, receipt, readonly. Do not mutate readonly lines. - threads[] with comment/thread IDs and anchor locations. Addressing: - A non-preamble section has its heading at section_line=0 and body at 1+. - The always-present preamble has no heading and starts at 0. - Receipts are opaque and scoped to the object returned. Never invent or reuse a stale receipt. After inserts/deletes, re-read before further position-based edits in that section. Choose the narrowest tool: - paper_apply_markdown: complete-body creation, major rewrite, or restructuring. It is bulk and may replace rich constructs on changed lines. - paper_insert: add text at a section start/end, after a line, or at document end. - paper_insert_image: upload and insert image bytes. - paper_edit_content: atomically update/delete lines, replace exact text, or update the title. - paper_edit_table: atomically update cells or add/delete/move rows and columns in one table. - paper_comment: add, reply to, or resolve a comment thread. - paper_get_doc_history: inspect authors and changes over time. - paper_list_recent_docs: discover recent Paper docs. - paper_create_document: create an empty Paper doc. Paper Markdown: - Blocks: headings (#/##/###), bullets (-), numbered items (1.), tasks (- [ ]), tracked tasks (- ( )), decisions (- { }), quotes (>), fenced code blocks, and pipe-delimited tables. Mentions: - In paper_apply_markdown body_markdown, paper_insert lines, paper_edit_content body destinations, paper_edit_table Markdown cells, and comment/reply text, create a mention with @<user_ref>. user_ref may be me, a decimal Dropbox user ID, dbid:..., or an exact email address. Use \@<...> for literal text. - Marked mentions are ignored inside code spans, fenced code blocks, and link destinations. Bare @name remains plain text. - Tracked-task assignees accept the same bare user_ref forms without @<...> wrapping. - A ref must resolve to exactly one active account that already has explicit document access; organization membership alone is not sufficient. This also handles an email attached to multiple teams: exactly one eligible account must remain. - Mentioning never provisions a user or grants document access. Unknown, inactive, ambiguous, and ineligible refs all fail the whole mutation with the same non-identifying error. Verify the exact email or user ID; if the intended user is not already a collaborator, ask the user to share the document first. - Mention parsing is intentionally not enabled for title fields, image alt text, or paper_create_document titles; @<...> remains ordinary text there. - Inline: **bold**, *italic*, ~~strike~~, `code`, and [text](url). - A table is one section line containing newline-separated pipe rows. Escape a literal pipe as \|. - Each code-block source line is separately addressable after insertion. - Regular tasks support checked state. Tracked tasks additionally support due dates and assignees. # Dropbox Paper Formatting Paper makes each empty Markdown line a visible blank block; adjacent prose has no margin. User templates, explicit styling, and deliberate existing formatting win. Repair accepted documents locally. One source line per prose paragraph; let Paper wrap and split paragraphs longer than about four rendered lines. Put exactly one blank between prose paragraphs, none doubled or trailing. Keep compact metadata lines consecutive. Set the document title in its field; do not repeat it as a body H1. Use H1, H2, and H3 for main sections, subsections, and deeper sections according to the document outline. Add one blank before headings after prose/lists, none after preamble/heading/table/divider, and none after headings. Colon lead-ins touch lists; list items are consecutive and single-line unless nested. One blank follows a list before prose/heading. All-bold standalone lines become H3; write `**Next steps**:` (colon outside bold) for a bold prose label. Tables: short header labels, preferably two or three columns, no adjacent blanks. A separator row (`| --- | --- |`) immediately after the first row sets a native top header; omit it for a table without a header. Reads preserve the separator when a header exists. Bold labels alone do not set a header. Remove the separator, not row 0, to remove header styling while retaining all cell content. Dividers mark major mode changes only, usually zero to two, without adjacent blanks. After writing, re-read canonical revision and structural spacing; inspect live Paper when available, report limits, and repair only affected blocks. Do not depend on CSS pixels/colors. Check prose-to-prose, heading-to-body, colon-to-list, list-to-prose, table header, divider, and document end in the live surface. Without it, do not claim rendered spacing. Mutation workflow: 1. Read and retain doc_id, addresses, receipts, and revision. 2. Make one atomic call when a compact mutation tool supports the requested operations. 3. Show the returned diff to the user. 4. Re-read after every successful content mutation to verify its revision and formatting. On stale/conflict errors, re-read before retrying. Failures: NOT_FOUND means the doc/reference is invalid; permission errors require user access; stale receipt/conflict means re-read and retry from current state. Do not retry an unknown mutation outcome blindly.

Cancel an in-progress Dropbox Sign signature request. Cancelling prevents any remaining signers from signing the document and cannot be undone. Use this tool only when the user explicitly asks to cancel a signature request. Do not use it to decline or reject a single signer: it cancels the entire request for every party. A request can be cancelled only when it was sent successfully rather than left as a draft, has not been signed by every signer (partially signed requests are eligible), and the authenticated user is its sender or the owner of the API app under which it was sent. If it is ineligible, explain why instead of calling the tool. Identify the request first. When its `signature_request_id` is unavailable, use `sign_list_signature_requests` to find it and ask the user to confirm the correct request. If the user is unsure, do not proceed. Before calling `sign_cancel_signature_request`, present a confirmation summary with the document title and the warning, "This will permanently cancel the signature request and cannot be undone." Do not call the tool until the user explicitly confirms, and call it exactly once. Pass only the required `signature_request_id` string; do not pass any other parameters. The response is empty on success: tell the user only that the request was cancelled, without offering to undo the action. If the call fails, surface the error in plain language and do not retry automatically.

Create an unclaimed draft from an existing Dropbox file, returning a `claim_url` that logs the user into Dropbox Sign and then redirects them to the unclaimed draft in the Dropbox Sign web app. Use this tool whenever the user wants to send a Dropbox file for signature or sign it themselves. It does not send anything immediately — the user must finish the workflow in the browser. Default to `"request_signatures"` mode; only use `"self_sign"` if the user explicitly says they want to sign the document themselves. Before calling, confirm the exact Dropbox file (search for it if not already established in the conversation) and pass its file ID as `file_ref`, in the form `id:<id>`. Never invent, reconstruct, truncate, or modify this ID. Determine the mode from context, or ask if it's unclear. Present a confirmation summary first, covering the file name/location and the mode in plain language. For `"request_signatures"`, explain that this will open the Dropbox Sign editor where the user can place fields and send the request. For `"self_sign"`, explain that it will open the editor where the user can place fields and sign the document. Do not include the raw `file_ref` or any internal path in the summary. Call this tool exactly once per confirmed request; do not call it again once a `claim_url` is returned. Collect each signer's name and email address if the user wants to add signers now; never invent or infer a name or email address. Signers are optional — if the user doesn't provide any, create the draft without them and they can be added later in the Dropbox Sign editor. Include any provided signers in the confirmation summary, listing each name and email address. The response contains only `claim_url`. Always present it as a plain URL on its own line — never as a markdown link, and never paraphrased or shortened. Explain that opening it logs the user into Dropbox Sign and then redirects them to the draft, where they can place fields and complete the request; do not describe the request as sent or completed. Only after the call succeeds and you present the `claim_url`, offer relevant follow-up help in your own words. For `"request_signatures"`, explain that after the user sends the request from the Dropbox Sign editor, they can return to this chat to check its status. Also let them know they can ask to find or download other completed or pending requests, cancel pending requests, or remind pending signers. For `"self_sign"`, explain that after they complete their signature in the editor, they can return to this chat to find the document, check its status, or download it. Do not suggest sending, cancellation, or signer reminders for the self-sign draft. Keep this brief and natural rather than presenting a fixed script or implying that any action has already happened. If the call fails, do not offer this follow-up guidance. If the call fails, surface the error message in plain language, do not present a `claim_url`, and do not retry automatically. For any unexplained or generic failure, do not present a raw error; tell the user to confirm the file is saved in Dropbox and accessible to them before retrying.

Download the current PDF snapshot for a Dropbox Sign signature request, returning a temporary `file_url` that can be used to fetch the file. Use this tool only when the user asks to download a signature request. Identify the request first with `sign_list_signature_requests` when its `signature_request_id` is unavailable. Confirm it is the intended request before calling this tool. Pass only the required `signature_request_id`; do not pass any other parameters. The response contains only `file_url`. It is a temporary, presigned URL and a bearer credential for the current PDF snapshot. Treat it as sensitive: share it only with the authenticated user, do not log it, do not include it in summaries or third-party requests, and do not transform, fetch, stream, or base64-encode its contents. Present the URL as a markdown link with clear descriptive text (e.g. `[Download signature request](<file_url>)`) rather than printing the raw URL, and advise the user that it expires. If the call fails because the request is unavailable, deleted, or the user is not permitted to access it, explain the error in plain language. Do not retry automatically.

List and search Dropbox Sign signature requests for the authenticated user. Use this tool when the user wants to find, review, check the state of, or search for signature requests associated with their Dropbox Sign account. This is the primary tool for answering questions like "find my completed requests", "show requests sent to Alice", or "what did I send last month". Do not use it to create, send, cancel, or modify a signature request. PARAMETERS: - max_results (int, optional): Maximum number of results to return, 1-50. Omit when the user has not asked for a particular count. RESPONSE CONTRACT: - signatureRequests[]: Array of signature request objects. - signatureRequestId: Internal ID. Use for follow-up tool calls (cancel, download, remind). Do not display unless the user explicitly needs it. - title: The document title of the signature request. - status: Overall request state. One of: "awaiting_signature", "completed", "declined", "expired". - dateSent: ISO 8601 timestamp when the request was sent. - dateCompleted: ISO 8601 timestamp when all signers completed (empty if not yet completed). - requesterEmailAddress: Email address of the person who sent the request. - signatures[]: Array of signers on this request. - signerName: Signer's display name. - signerEmailAddress: Signer's email address. - statusCode: Per-signer state. One of: "signed", "on_hold", "awaiting_signature", "awaiting_my_signature", "declined", "expired". - order: Signing order position (0-based). ASSISTANT POLICY — Searching and filtering: - When the user asks to find requests sent TO a specific person, match against signatures[].signerEmailAddress and signatures[].signerName (case-insensitive partial match). - When the user asks to find requests FROM a specific person, match against requesterEmailAddress (case-insensitive partial match). Do not claim to filter by requester name. - When the user asks about requests by status (e.g. "completed", "pending", "awaiting signature", "declined", "expired"), match against the status field. Treat "pending" as equivalent to "awaiting_signature". - When the user asks about requests by date or time range (e.g. "last week", "in September"), use dateSent for sent or created ranges and dateCompleted for completion ranges. - When the user asks about requests by title or document name, match against the title field (case-insensitive partial match). - When combining criteria (e.g. "completed requests sent to Alice last month"), apply all filters together. - Present results in a clear summary: title, status, date sent, and signer names. Include dateCompleted for completed requests. - This tool returns at most 50 results. If the result set is at the limit, inform the user that there may be additional matching requests not shown. ASSISTANT POLICY — General: - Do not display signer email addresses or requesterEmailAddress unless the user specifically asks for them or needs to disambiguate between people with similar names. - Treat `signatureRequestId` as an internal reference for follow-up tools rather than a value to display unless the user explicitly needs it. - Use signer details to show the exact people who would receive a reminder before confirmation. - Only after the tool returns successfully and you present the results, conversationally offer relevant next steps in your own words. Tailor the suggestions to the results and the user's request instead of reciting every option every time: - Download a completed or pending signature request. - Cancel a pending signature request. - Send a reminder to pending signers. - Prepare a new document for signature from a file in the user's Dropbox. To start, the user can identify the Dropbox file and provide each signer's name and email address; signer details can also be added later in the Dropbox Sign editor. - Make it clear that the user can ask for these follow-up actions in the current chat. Do not claim an action has been taken until its corresponding tool has completed successfully. - If the tool returns an error, do not offer these follow-up actions. - If access is denied, do not retry with different identifiers. - If the request fails unexpectedly, report that the signature-request list could not be retrieved and avoid claiming that no requests exist.

Send reminders for a Dropbox Sign signature request. Use this only after the user has selected an incomplete request from `sign_list_signature_requests`. Before calling, identify the exact recipients who will be contacted and obtain clear confirmation. Do not expose the raw `signature_request_id` in that confirmation. The tool accepts the internal signature-request ID and an optional `email_addresses` list of up to 50 unique recipients. When `email_addresses` is omitted or empty, it determines eligible recipients from the request data fetched before sending. For unordered signing, it sends one reminder to every recipient currently awaiting signature. When email addresses are provided, it sends reminders only to requested recipients who are currently eligible. A requested address that belongs to the request but is not eligible is returned as `not_currently_eligible`; an address that is not a recipient is returned as `recipient_not_found`. For ordered signing, only the current eligible signer can be reminded. Other requested recipients are reported as `not_currently_eligible`, and the response's `is_ordered_signing`, `current_signer_email`, and `current_signer_name` fields identify who can currently be reminded. If the current user is the recipient expected to sign, the tool does not send them a reminder; the result says `signature_required`. The current signer name falls back to their email address when Sign has no name. The tool never intentionally sends reminders to signed, declined, expired, on-hold, or later ordered recipients. The response's request status is the status observed immediately before sending reminders; the tool does not refresh it afterward. Call this tool exactly once after confirmation. It makes one underlying Sign reminder call per eligible recipient and does not retry. A recipient result of `sent` confirms that Sign accepted that reminder. `rate_limited` means Sign indicates the recipient was reminded recently; do not retry automatically. `sign_rejected` means Sign could no longer send the reminder, and `account_unavailable` means the connected Sign account cannot send it. `failed` means the outcome is unknown. `signature_required`, `not_currently_eligible`, and `recipient_not_found` mean no reminder was attempted. Do not retry unsuccessful recipients automatically.