Skip to main content
Glama

file_write

Write content to a remote file or apply targeted edits, with overwrite, append, automatic backups, and atomic replacement while preserving permissions and ownership.

Instructions

把 content 原样写进远端文件(不用转义),或用 edits 改其中几处。overwrite 和 edits 先把旧文件备份到 ~/ops-backups/-auto/,再原子替换,保留权限和属主;append 追加到文件末尾。

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": {
      "host": "<host>",
      "path": "<path>"
    },
    "name": "file_write"
  }
}

Input Schema

NameRequiredDescriptionDefault
connNo
hostYes
modeNooverwrite
pathYes远端绝对路径
pswdNo
sudoNo
editsNo代替 content:把每个 old 换成 new,old 必须在文件里刚好出现一次
backupNo覆盖前先备份
contentNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.3.0
    • changedInput schema / properties / backup / description
      Previous value: -"Back up before overwrite"New value: +"覆盖前先备份"
    • addedInput schema / properties / conn
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "hostname": {
      +      "pattern": "^[\\w.:-]+$",
      +      "type": "string"
      +    },
      +    "identity": {
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "jump": {
      +      "type": "string"
      +    },
      +    "password": {
      +      "type": "string"
      +    },
      +    "port": {
      +      "maximum": 65535,
      +      "minimum": 1,
      +      "type": "integer"
      +    },
      +    "user": {
      +      "pattern": "^[\\w.-]+$",
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / edits
      Added value: +{
      +  "description": "代替 content:把每个 old 换成 new,old 必须在文件里刚好出现一次",
      +  "items": {
      +    "properties": {
      +      "new": {
      +        "type": "string"
      +      },
      +      "old": {
      +        "minLength": 1,
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "old",
      +      "new"
      +    ],
      +    "type": "object"
      +  },
      +  "minItems": 1,
      +  "type": "array"
      +}
    • changedInput schema / properties / path / description
      Previous value: -"Absolute remote path"New value: +"远端绝对路径"
    • addedInput schema / properties / pswd
      Added value: +{
      +  "type": "string"
      +}
    • addedInput schema / properties / sudo
      Added value: +{
      +  "type": "boolean"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "host",
      -  "path",
      -  "content"
      -]New value: +[
      +  "host",
      +  "path"
      +]
  2. First observedv0.1.0

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations at all, the description carries the full burden, and it does disclose valuable behavior: overwrite and edits first back up to ~/ops-backups/<date>-auto/, then replace atomically, preserving permissions and owner. However, it says nothing about creation of missing parent directories, what happens when the path does not exist, failure/rollback semantics, or the effect of privilege escalation, all of which matter for a write tool with a sudo flag.

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?

The write action and its variants are front-loaded, and each clause adds information (no escaping, backup path, atomicity, ownership preservation, append position) rather than restating the schema. It is a single dense paragraph; a short structure separating the modes would read slightly better, but there is no filler.

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

Completeness3/5

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

For a 9-parameter mutation tool with a nested connection object, a sudo flag, and no annotations or output schema, the description covers the write/backup semantics well but omits authentication/connection handling, privilege escalation, existence preconditions, and any indication of what is returned. An agent could call it, but not confidently in the privileged or auth-via-conn cases.

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 only 33%, so the description has to compensate, and it does explain content (written verbatim, no escaping), edits (old must occur exactly once), backup location, and mode behavior. But it never mentions sudo, pswd, conn (hostname/user/port/identity/jump), or the separate top-level host parameter, leaving several high-risk parameters with no meaning beyond their names.

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

Purpose4/5

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

The description states a concrete verb and resource ('write content verbatim into a remote file'), and enumerates the three operating shapes: full content write, targeted edits via old/new pairs, and append. It is clearly a remote file mutation tool, distinguishable from exec/pipe by naming files rather than commands, though it never explicitly contrasts itself with those siblings.

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?

It gives usable selection guidance between the tool's own modes: use content for a whole-file write 'without escaping', use edits to change a few places, and append to add to the end. What is missing is any guidance on when to prefer this over the exec/pipe siblings (e.g., instead of a shell redirect) and any precondition such as the file needing to exist for edits.

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

Deploy Server

Other Tools