Skip to main content
Glama

Write file

write_file
Destructive

Create, overwrite, or append files in a locked workspace with optional parent directory creation and SHA-256 conflict checks that refuse writes if the file changed since you read it.

Instructions

Write a file. mode=create (fails if it exists), overwrite, or append. create_dirs=true creates parent folders. Use when: you create a file, replace one entirely, or append. expected_sha256 refuses the write if the file changed since you read it. Avoid when: you change a few lines (edit_file). overwrite is immediate and not undoable: snapshot first when the file is not in git. Output: action (created|overwritten|appended), bytes_written, sha256_after. mode=create on an existing path gives conflict.

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

Input Schema

NameRequiredDescriptionDefault
modeNoDefault overwrite. create fails if the path exists; append adds to the end.
reasonNoOptional why (max 400 chars), audit-logged.
contentYesFull file content to write.
create_dirsNotrue creates missing parent directories (default false).
relative_pathYesWorkspace-relative ('.' = root); absolute/.. outside it rejected.
expected_sha256NoHex SHA-256 of the file's current full content. The write is refused if the file on disk differs. Use sha256_after from your last write/edit of this file; read_file's sha256 only matches when the whole file was returned.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv4.5.0
    • removedInput schema / properties / create_dirs / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "maximum": 1,
      -    "minimum": 0,
      -    "type": "integer"
      -  }
      -]
    • changedInput schema / properties / create_dirs / description
      Previous value: -"1 creates missing parent directories (default 0)."New value: +"true creates missing parent directories (default false)."
    • removedInput schema / properties / create_dirs / maximum
      Removed value: -1
    • removedInput schema / properties / create_dirs / minimum
      Removed value: -0
    • changedInput schema / properties / create_dirs / type
      Previous value: -"integer"New value: +"boolean"
  2. Addedv4.0.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already flag destructiveHint=true and non-idempotent, and the description goes further: overwrite is immediate and not undoable, mode=create on an existing path yields a conflict, and expected_sha256 refuses the write on concurrent modification. It also discloses the exact return fields (action, bytes_written, sha256_after) despite there being no output schema.

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?

Front-loaded one-line purpose, then mode semantics, then Use/Avoid/Output blocks. Every sentence carries actionable information with no filler, and the risk warning sits right next to the alternative guidance.

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 6-parameter destructive write with no output schema, the definition covers modes, directory creation, concurrency safety, rollback advice, and the return payload including the conflict case. Nothing an agent needs before invoking is missing.

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 100%, so the baseline is 3; the description adds value by framing expected_sha256 as an optimistic-concurrency guard ('refuses the write if the file changed since you read it') rather than just a hash parameter, and by stating the default mode implicitly through 'overwrite' framing. Most mode/create_dirs wording restates the schema, keeping it just above baseline.

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+resource ('Write a file') and immediately enumerates the three modes with their semantics. It distinguishes itself from the sibling edit_file, so an agent can choose between whole-file write and surgical edit without inspecting schemas.

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 'Use when' (create, replace entirely, append) and 'Avoid when' (few-line changes -> edit_file) sections name the alternative and the condition that selects it. It also adds a procedural precondition: snapshot first when the file is not in git.

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