Skip to main content
Glama

write_file

Destructive

Writes or updates a file inside a workspace, replacing it by default or writing at a byte offset for in-place edits; guarded fleets require explicit user confirmation.

Instructions

Write a file inside your workspace (content up to 8 MiB). offset 0 (the default) replaces the file; a larger offset writes in place. Paths are inside the workspace: this tool never uploads local files. On a guarded fleet you must first ask the user and get their explicit agreement; only then set confirm to the fleet name.

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": {
      "path": "<path>",
      "content": "<content>"
    },
    "name": "write_file"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeNoPermission bits for a new file (decimal, e.g. 420 for 0644).
pathYesFile path inside the workspace.
fleetNoFleet name. Omit to use the default.
offsetNoByte offset to write at. 0 (default) replaces the file.
confirmNoGuarded fleets only: the fleet name, set only after the user explicitly agreed. Never set it on your own.
contentYesFile content (at most 8 MiB once decoded).
contextNoContext name. Omit to use the default.
encodingNoHow content is encoded: text (default) or base64.
workspaceNoWorkspace id. Omit to use this session's workspace on the fleet.

Output Schema

NameRequiredDescriptionDefault
sizeYes
whereYes
sha256Yes
bytes_writtenYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already flag destructiveHint=true and openWorldHint=true, so the bar is lower, yet the description still adds meaningful behavior: offset 0 replaces the whole file while a larger offset writes in place, plus an 8 MiB ceiling and workspace path confinement. The user-consent gating for guarded fleets is genuinely operational information not encoded in annotations.

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

Conciseness5/5

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

Four tight sentences with the core capability, the offset semantics, the path constraint, and the safety gate in that order. No filler and the most decision-relevant facts are front-loaded.

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?

With nine parameters, a destructive write and an output schema, the description covers the traps an agent would otherwise hit: overwrite vs in-place, size limit, path confinement, and the guarded-fleet consent flow. Remaining gaps (encoding implications, idempotency, what the response looks like) are minor since an output schema exists.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3. The description does add real meaning for `offset` (replace vs in-place) and `confirm` (only after explicit user agreement on a guarded fleet), but leaves `mode`, `encoding`, `fleet`, `context`, and `workspace` entirely to the 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?

States a specific verb and resource (write a file), scopes it to the workspace, and gives a hard size limit. It also pre-empts confusion with the `upload` sibling by stating 'this tool never uploads local files', so an agent can route correctly without opening another schema.

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

Usage Guidelines4/5

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

Provides a clear when-not condition (local file uploads belong elsewhere) and a concrete prerequisite procedure for guarded fleets: ask the user, get explicit agreement, then set `confirm`. It does not distinguish write_file from siblings like `write`/`edit`/`multi_edit` for in-place modification, so it falls short of a full routing guide.

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