Skip to main content
Glama

write

Destructive

Create or replace a file on a remote machine with atomic saves and preserved permissions; use edit tools for existing file changes and request guarded-fleet confirmation first.

Instructions

Create or replace a file on the remote machine (content up to 1 MiB; atomic, mode kept). Prefer edit or multi_edit for changes to an existing file. 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"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeNoPermission bits for a new file (decimal, e.g. 420 for 0644).
pathYesFile path on the remote machine: absolute, or relative to the workspace directory.
fleetNoFleet name. Omit to use the default.
confirmNoGuarded fleets only: the fleet name, set only after the user explicitly agreed. Never set it on your own.
contentYesThe complete new file content (at most 1 MiB; use upload for more). Replaces the file.
contextNoContext name. Omit to use the default.
workspaceNoWorkspace id. Omit to use this session's workspace on the fleet.

Output Schema

NameRequiredDescriptionDefault
kindYes
mimeNo
noteNo
pathNo
sizeNo
countNo
linesNo
whereYes
sha256No
contentNo
entriesNo
new_fileNo
warningsNo
truncatedNo
workspaceYes
next_offsetNo
total_linesNo
omitted_bytesNo
written_bytesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare destructive=true and readOnlyHint=false, but the description adds behavior the annotations do not carry: a 1 MiB content ceiling, atomic write semantics, preservation of the mode, and a consent gate on guarded fleets. It stops short of covering failure behavior or the exact overwrite consequence for an existing file, so it is strong but not exhaustive.

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?

Three short sentences, front-loaded with the primary action and scope, followed by the sibling alternative and then the guarded-fleet prerequisite. No filler and the most decision-critical constraint (the size cap and atomicity) is placed up front.

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?

With an output schema present, return values need not be explained; what remains—size limit, atomicity, mode handling, the sibling alternative, and the consent workflow—is all covered for a 7-parameter destructive write tool. Nothing an agent needs in order to call this safely is missing.

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 every parameter (including `confirm`, `fleet`, `workspace`, and `context`) is already documented in structured data, and the description largely restates the `confirm` consent rule already present in the schema. Baseline 3 applies; the description adds no syntax or format detail beyond 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?

The description opens with a specific verb pair and resource ("Create or replace a file on the remote machine"), and immediately distinguishes this tool from the `edit`/`multi_edit` siblings that modify existing files. An agent can tell what the tool does and how it differs from neighbors 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?

It explicitly routes the agent to alternatives ("Prefer edit or multi_edit for changes to an existing file"), which is the key routing decision for a write tool, and adds a hard precondition for guarded fleets: ask the user first and only then set `confirm`. When-not guidance and prerequisites are both present.

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