Skip to main content
Glama

Write File

write_file
DestructiveIdempotent

Creates a new text file or completely overwrites an existing file with the provided content, limited to allowed directories.

Instructions

Create a new file or completely overwrite an existing file with new content. Use with caution as it will overwrite existing files without warning. Handles text content with proper encoding. Only works within allowed directories.

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
pathYesThe file to create, or to overwrite if it exists; its parent directory must exist. Absolute, or relative to an allowed directory; it must resolve inside the allowed directories.
contentYesThe complete text the file will contain, replacing any it had

Output Schema

NameRequiredDescriptionDefault
contentYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.3.0

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description earns credit for adding real context beyond those flags: overwrites happen silently with no warning, content is text with proper encoding, and writes are confined to allowed directories. It stops short of saying whether parent directories are created, though the schema covers that.

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?

Four short sentences, each carrying a distinct point (what it does, destructive risk, content type, scope limit), with the most consequential warning placed early. No filler or repetition.

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?

An output schema exists and the input schema is fully documented, so the description need only cover scope, risk, and content type, which it does. The remaining gap is the absence of routing guidance toward append_file/edit_file for non-wholesale edits.

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 both parameters (path, content) are already fully documented including the parent-directory and sandbox requirements. The description's 'only works within allowed directories' restates the path constraint rather than adding new meaning; baseline 3 applies.

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?

States a specific verb and resource plus the two modes (create new / completely overwrite existing), which is precise enough to act on. It does not differentiate against siblings like append_file or edit_file, so an agent must still infer that distinction.

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

Usage Guidelines3/5

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

Usage guidance is cautionary ('Use with caution as it will overwrite existing files without warning') and states the sandbox constraint, so the implied usage is clear. It never says when to prefer append_file or edit_file instead, which is the most likely selection error for this tool.

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