Skip to main content
Glama
Sign In

Dock

by ai.trydock
OverviewDiscussionsAdmin

upload_file

Upload a file into a Files surface (kind='files'). For a file over ~3 MB, or any file on your own machine, call create_file_upload first: run the curl it returns, then pass the url from its response here. You never need a public host to put your own file into Dock. Small files can instead go inline as base64 in content_base64 (a bare base64 string or a data: URL), capped ~3 MB, the request-body limit. You can also pass any public https url and the server fetches the file for you, with the per-tier size cap enforced as it downloads. Provide exactly one of content_base64 / url. The server sniffs the MIME from magic bytes (don't trust the extension), enforces an allowlist, sanitizes SVGs, strips EXIF from images, and counts the bytes against your plan's storage quota. Returns the created file's {id, name, size, mimeType, parentFolderId, createdAt}. surface_slug is required (use list_surfaces to find the files surface); parent_folder_id defaults to the surface root.

Input Schema

NameRequiredDescriptionDefault
urlNoThe `url` a `create_file_upload` link returned, or any public https URL the server fetches the file from (large-file path; no request-body limit). Provide this OR `content_base64`, not both.
mimeNoOptional MIME hint. The server still sniffs magic bytes; this only helps for extension-less or ambiguous content.
slugYesThe workspace slug (bare or org-prefixed).
filenameYesThe file's name, including extension (e.g. "report.pdf").
surface_slugYesThe Files surface slug to upload into (required).
content_base64NoThe file bytes, base64-encoded. Accepts a bare base64 string or a "data:<mime>;base64,..." data URL. ~3 MB cap. Provide this OR `url`, not both.
parent_folder_idNoOptional folder id (from list_files) to place the file in. Defaults to the surface root.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / url / description
      Previous value: -"The `url` a `create_file_upload` link returned (large-file path; no request-body limit). Provide this OR `content_base64`, not both."New value: +"The `url` a `create_file_upload` link returned, or any public https URL the server fetches the file from (large-file path; no request-body limit). Provide this OR `content_base64`, not both."
  2. Changed1 schema field changed
    • addedInput schema / properties / url
      Added value: +{
+  "description": "The `url` a `create_file_upload` link returned (large-file path; no request-body limit). Provide this OR `content_base64`, not both.",
+  "type": "string"
+}
  3. Added

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does: server-side MIME sniffing from magic bytes (extension untrusted), allowlist enforcement, SVG sanitization, EXIF stripping, byte counting against plan storage quota, per-tier download caps, and the ~3 MB request-body limit. This is exactly the non-obvious side-effect disclosure an agent needs before uploading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then ordered by decision path (large file → inline → remote URL → constraints). Every sentence carries information, though the middle sentences are dense run-ons that could be split for easier scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by naming the returned object fields ({id, name, size, mimeType, parentFolderId, createdAt}). Combined with the size-cap, quota, and sanitization notes, an agent has everything needed to invoke this correctly on the first try.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (baseline 3), but the description adds genuine meaning beyond it: it clarifies that `url` accepts either a create_file_upload-returned link or any public https URL, that the two content params are mutually exclusive, that `surface_slug` is required and discoverable via list_surfaces, and that `parent_folder_id` defaults to the surface root.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Upload a file into a Files surface') and immediately delimits the target surface kind. It is clearly distinguishable from the sibling create_file_upload, which it names as a prerequisite rather than a competitor.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit branching rules: >~3 MB or a local file → call create_file_upload first and pass the returned `url`; small files → inline base64; any public https URL → server fetch. It also states the mutual exclusion ('Provide exactly one of content_base64 / url') and points to list_surfaces to obtain a required parameter.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Dock toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources