Skip to main content
Glama

fs_upload

fs_upload = files. fs_write = text and small inline content. Uploads an image, PDF, video, zip, font, large artifact, or attachment without carrying binary bytes or base64 in tool arguments.

Client capability matrix:

  • Native-file connector clients: file carries a temporary authorized file reference that this tool streams through the upload relay.

  • Clients with raw HTTP access: an omitted file mints a one-time upload_url that accepts raw bytes with the returned Content-Type. This two-step transport keeps base64 out of tool arguments. One request carries at most 100 MB; a bigger file goes up in parts through the returned multipart_url (start, send each part, then complete — the reply spells out the steps). With size_bytes, a file over 90 MB comes back already started, with parts_url, part_size, part_count and complete_url; a size over the plan's per-file limit is refused with PAYLOAD_TOO_LARGE before any byte moves.

  • Other shell-less MCP clients: standard MCP arguments have no protocol-level file input, so upload availability depends on compatible host file references or raw HTTP access.

The connector reference and upload URL are temporary transports, not the durable artifact. After storage, the saved bytes are addressed by path; fs_signed_url provides a private human download and public:true with fs_public_url provides a permanent public URL. The PUT response and native call both return { path, size_bytes, content_type, version }.

file must be a connector-provided file reference. A local path string, URL string, base64 string, or text value is rejected rather than being mistaken for bytes. content_type overrides connector metadata; otherwise MIME is inferred from connector metadata and the filename/path. Files are private unless public:true is supplied.

Native connector call:

{ "project_id": "my-saas", "path": "/uploads/alice/avatar.png", "file": "<attached connector file>", "public": true }

Raw-PUT fallback:

{ "project_id": "my-saas", "path": "/uploads/archive.zip", "content_type": "application/zip" }

Large file (over 90 MB), uploaded in parts:

{ "project_id": "my-saas", "path": "/uploads/video.mp4", "content_type": "video/mp4", "size_bytes": 125829120 }

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project_id": "<project_id>",
      "path": "<path>"
    },
    "name": "fs_upload"
  }
}

Input Schema

NameRequiredDescriptionDefault
fileNoNative connector file reference shaped as {download_url, file_id, mime_type?, file_name?}. Path strings, base64, and inline bytes are rejected. An omitted value requests the raw-PUT upload_url fallback.
pathYesDestination storage path with leading slash, e.g. "/uploads/avatar.png".
publicNoServe this file at a public /storage URL. Default false (private).
project_idYesProject ID (UUID), subdomain, or slug — resolved server-side, no UUID lookup needed. 'default' also works when the account has exactly one project; multi-project accounts must name one (the error lists them).
size_bytesNoRaw-PUT fallback only: the whole file size in bytes, when known. Over 90 MB, the upload starts in parts and the reply carries parts_url, part_size, part_count and complete_url; over the plan limit, it is refused with PAYLOAD_TOO_LARGE before any byte moves.
content_typeNoOptional MIME override, e.g. "image/png". Otherwise inferred from connector metadata and filename/path.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only say readOnly=false, idempotent=false, destructive=false; the description adds the substantive behavior an agent needs: no binary/base64 in arguments, temporary transport vs durable `path`, private-by-default unless `public:true`, a 100 MB per-request cap, a 90 MB multipart threshold, PAYLOAD_TOO_LARGE refusal before bytes move, and the `{path, size_bytes, content_type, version}` return shape. Nothing here conflicts with the readOnly/destructive hints.

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 fs_write differentiator and organized with bold headers and three runnable examples, so it is easy to scan. It is longer than strictly necessary — the client capability matrix and the three examples restate some of the same transport facts — but the density is justified by a genuinely multi-modal upload flow.

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?

For a non-idempotent, multi-transport, nested-object tool with no output schema, the description covers entry paths, size limits, failure modes, privacy default, and explicitly states the response shape. An agent has everything needed to choose a transport and call it correctly.

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

Parameters4/5

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

Schema coverage is already 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: omitting `file` mints an upload_url, `size_bytes` over 90 MB pre-starts a multipart upload, and `content_type` overrides connector metadata. It also clarifies that local paths, URLs, and base64 for `file` are rejected, which is a semantic constraint beyond the nested-object schema.

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 plus an explicit contrast: 'fs_upload = files. fs_write = text and small inline content.' An agent can immediately separate binary upload from text write without consulting either schema.

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 when-to-use routing: binary assets to fs_upload, text to fs_write, native connector clients vs raw-HTTP clients vs other MCP clients, and when the one-time upload_url fallback is minted. It also names downstream alternatives for retrieval (fs_signed_url for private, fs_public_url for public), so the agent knows what to call after upload.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources