Skip to main content
Glama

fs_write

fs_write = text and small inline content. fs_upload = real files. Write UTF-8 text or other small content already present in the tool call to project file storage. Parent directories are auto-created. Overwrites create a new version automatically (history keeps the last 3 versions on Free, 10 on Builder).

Images, PDFs, video, zip files, fonts, large artifacts, and task attachments go through fs_upload, so binary bytes never enter model context. Base64 input remains accepted here only for backward compatibility with existing callers; new binary uploads go through fs_upload.

It holds notes, JSON, CSV, generated source text, and small cached text that is not project code (project code goes through project_deploy).

There are two file surfaces: deployed source is read with project_files_list / project_file_read; fs_write and fs_read are runtime storage for uploads and generated files via sw.fs. Project source such as src/App.tsx or api/foo.ts is read with project_file_read, not fs_read.

Files are PRIVATE by default. A file served at a public URL (e.g. an embedded app image) takes public: true, and fs_public_url returns the URL. Without it the file is only reachable through your authenticated code.

Example (text):

{ "project_id": "my-saas", "path": "/notes/run.txt", "content_type": "text/plain", "content": "upload completed" }

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>",
      "content": "<content>"
    },
    "name": "fs_write"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYesFull path with leading slash, e.g. "/images/avatar.png"
publicNoPublic /storage URL exposure without auth. False (default) keeps files private; true supports images and assets embedded in an application.
contentYesFile content — UTF-8 text or base64 bytes (content_type matches it).
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).
content_typeNoMIME type, e.g. "image/png", "application/pdf". Defaults to application/octet-stream.

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?

Goes well past the annotations by disclosing that parent directories are auto-created, that overwrites create a new version with retention of 3 (Free) / 10 (Builder) versions, that files are private by default, and that base64 input survives only for backward compatibility. These are operational consequences an agent cannot infer from readOnlyHint/destructiveHint alone.

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 one-line disambiguation, then layered detail; headers and an example make it scannable. Slightly redundant, since the base64 backward-compatibility paragraph repeats the fs_upload routing already stated up top, but nothing is wasted enough to hurt.

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

Completeness4/5

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

Covers surfaces, privacy, versioning, and routing for a 5-parameter mutation tool with no output schema. The one gap is that "small content" is never quantified (no size ceiling before an agent should switch to fs_upload), and nothing is said about what the call returns after a write.

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 already 100%, but the description adds real meaning: it explains the privacy default behind `public` and the fs_public_url follow-up, and provides a full worked call showing path/content_type/content usage. This exceeds the baseline-3 expectation for a fully documented 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 an explicit verb+resource contrast ("fs_write = text and small inline content. fs_upload = real files") and states the destination is project file storage. It names the sibling it replaces for binaries and the one used for project code, so an agent can discriminate without opening any 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?

Explicit when-to-use examples (notes, JSON, CSV, generated source text, small cached text) and explicit when-not routes: binaries to fs_upload, project code to project_deploy, deployed source reads to project_file_read. It also clarifies the two file surfaces so runtime storage is not confused with deployed source.

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