Dropbox

Tool

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

PATHS (SUPER IMPORTANT):

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

REQUEST CONTRACT:

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

RESPONSE CONTRACT:

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

ASSISTANT POLICY:

• Before calling this tool, the assistant MUST summarize the exact mutation plan and get explicit user confirmation in chat.
• The assistant MUST NOT claim the mutation already happened until the tool returns a successful response.
• After a successful response, the assistant MUST clearly list exactly what changed, using returned paths, file IDs, 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, instruct the user to delete them from Dropbox. For sharing changes, instruct the user to manage or revoke sharing from the Dropbox web UI.

ERRORS:

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

RETRY GUIDANCE:

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

EXAMPLES:

{"path": "/Documents/notes.txt", "content": "Hello World"} {"path": "ns:123//Code/script.py", "content": "print('hi')"} {"path": "/readme.txt", "content": "Root level file"} 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.create_folder Purpose: Create a new folder in Dropbox.

PATHS (SUPER IMPORTANT):

• Input path accepts fq_path (for example "/Documents/NewFolder") or ns_path (for example "ns:123//Documents/NewFolder").
• Paths are case-insensitive.
• The final path component is the new folder name.
• Output folder.path is always ns_path.
• Never strip the "ns:<id>//" prefix from returned paths.
• Team root is not writable for team accounts. Personal account root is writable.

REQUEST CONTRACT:

• path (string, REQUIRED): Full destination path including the new folder name.
• Parent must already exist.
• To create nested parents, call create_folder for the parents first.

RESPONSE CONTRACT:

• folder: object describing the created folder.
• name: Folder name.
• path: ns_path for follow-on MCP calls.
• modified_time: ISO 8601 when available.
• file_id: Encoded object id. Can be reused as "id:<file_id>".
• object_type: "folder".
• folder: Empty object.
• path_display: fq_path for human display when populated.

ASSISTANT POLICY:

• Before calling this tool, the assistant MUST summarize the exact mutation plan and get explicit user confirmation in chat.
• The assistant MUST NOT claim the mutation already happened until the tool returns a successful response.
• After a successful response, the assistant MUST clearly list exactly what changed, using returned paths, file IDs, 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, instruct the user to delete them from Dropbox. For sharing changes, instruct the user to manage or revoke sharing from the Dropbox web UI.

ERRORS:

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

RETRY GUIDANCE:

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

EXAMPLES:

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

Tool

Name: dropbox.create_shared_link Purpose: Create or reuse a private shared link for a file or folder. When to use: Only when the user explicitly asks to share, get a link, or send a file or folder to someone.

WHAT THIS TOOL DOES:

• Creates or reuses a private, view-only shared link.
• If the user provides one or more email addresses, it also shares the item directly with those specific people.
• It does not create public links.

REQUEST CONTRACT:

• path_or_file_id (string, REQUIRED): File or folder identifier.
• emails (string[], OPTIONAL): Specific email addresses to share with.
• password, expires, allow_download (OPTIONAL): Additional private-link settings when supported.

RESPONSE CONTRACT:

• url: The private shared link to show the user.
• created: True when a new private link was created, false when an existing compatible one was reused.
• shared_with: Emails that were successfully added, if any were requested.
• share_errors: Per-email failures, if any were requested.

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

REQUEST:

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

RESPONSE:

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

NOTES:

• Use the id returned by search directly with this tool, or pass an existing Dropbox path.
• This tool uses the existing Dropbox content extraction backend.
• url prefers GetFileContent.content_link and falls back to GetFileMetadata.file.url when needed.
• Max file size: 5 MiB.
• If extraction fails, the tool returns an error instead of a partial success payload.

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. Please use this tool to preview files in the user's Dropbox, or when the user asks to preview a file.

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 "id:<file_id>"
• ALWAYS prefer "id:<file_id>" when available.
• If "id:<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 "id:<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 FilePreviewResponse 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:abc123"]} → "{ 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 (SUPER IMPORTANT):

• Input path_or_file_id accepts fq_path, ns_path, or "id:<file_id>".
• 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:encoded_file_id".

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 "id:<file_id>".

EXAMPLES:

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

Tool

Name: dropbox.list_folder Purpose: Recursively list files and folders in Dropbox with cursor-based pagination.

PATHS (SUPER IMPORTANT):

• Input path accepts fq_path (for example "/Documents") or ns_path (for example "ns:123//Documents").
• Paths are case-insensitive.
• Use "" or "/" for root.
• Output entries[].path is always ns_path. Use this exact value for follow-on MCP calls.
• Output entries[].file_id can be reused as "id:<file_id>" in follow-on MCP calls.
• This tool does not populate path_display; call get_file_metadata if you need fq_path output.
• Never strip the "ns:<id>//" prefix from returned paths.

REQUEST MODES:

• First call: send {"path": "..."} and omit cursor.
• Pagination: send {"cursor": "..."} only.

PARAMETERS:

• path (string, first call only): Directory to list. Accepts fq_path or ns_path. "" and "/" mean root.
• cursor (string, pagination only): Cursor from a previous list_folder response.

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: Encoded object id. Can be reused as "id:<file_id>".
• object_type: "file" | "folder" | "mount".
• 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 more results remain.
• Page size is variable. Do not infer completeness from entry count alone; always check has_more.

ASSISTANT POLICY:

• Validate modes strictly: first call uses path, pagination uses cursor only.
• 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, always reuse entries[].path or "id:<file_id>" exactly as returned.

EXAMPLES:

{"path": ""} {"path": "/Documents"} {"path": "ns:123//Documents"} {"cursor": "base64_cursor_from_previous_response"}

Search Dropbox files with one public tool that supports both simplified and advanced search flows.

REQUEST:

• New search: query is required. Optional advanced parameters: path, file_extensions, file_categories, max_results, filename_only, order_by, reverse_order, file_status, last_modified_after, last_modified_before.
• Pagination: cursor only. Do not repeat query or filters when cursor is set.

RESPONSE:

• results: Unified search results
• id: Tool-ready file identifier when a file_id is present (format: "id:<file_id>")
• title: File or folder name
• url: Dropbox web URL derived from path_display when available
• 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:

• Plain {"query": "..."} keeps the ChatGPT App simplified flow: up to 20 file results from a single backend search page.
• Any extra parameter beyond query, or any cursor call, switches search into advanced/raw mode.
• Search may return files that later fail text extraction in fetch.