Skip to main content
Glama

Create or replace one code file

write_file

Create a workspace code file or replace its full content without touching other files, blocks, links, or layout. Use edit_file to change only part of an existing file.

Instructions

THIS is how you edit a workspace code file — a page, a stylesheet, a helper library. Creates it if it doesn't exist. Do NOT re-send the whole workspace with set_workspace_content to change one file: everything else (blocks, links, other files, the camera, the layout) stays untouched here, and re-emitting files you didn't mean to change is how one of them gets silently corrupted. content is the FULL new content, so this is the tool for CREATING a file or replacing one outright — to change part of a file that already exists, use edit_file instead. Names are case-sensitive; a name differing only in case from an existing file is rejected (rename = write the new name, then delete_file the old one). Writing an HTML PAGE also returns what a findable page is still missing (title, description, canonical, lang…) — advisory only, the file is written either way; see get_block_model's PUBLISHING A SITE.

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

Input Schema

NameRequiredDescriptionDefault
seoNoHow much to report about the HTML pages being written: "full" (default) everything, "minimal" only what an indexed page cannot do without, "none" to say nothing. Never blocks the write; a page with <meta name="robots" content="noindex"> is exempt either way.
nameYesCase-sensitive file name, folders with "/" — e.g. "pages/app.css", "lib/http.js".
contentYesThe file's FULL new content — this replaces it. To change PART of an existing file, use edit_file.
workspaceIdYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.53.0

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does most of it: it discloses upsert semantics ('creates it if it doesn't exist'), the scope of side effects ('everything else ... stays untouched'), a rejection rule (case-only name collisions are rejected), and that SEO reporting is advisory and never blocks the write. It omits permission/auth requirements and any error behavior beyond the case-collision rule, which keeps it below a 5.

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?

Well front-loaded — the core action and the primary anti-pattern lead the paragraph, with edge cases (case sensitivity, SEO advisory) trailing. Slightly over-rich: the 'FULL new content' point is made twice (once inline, once via the schema's wording) and the set_workspace_content warning is emphatic to the point of verbosity, but no sentence is truly wasted.

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?

For a 4-parameter tool with no output schema, the description covers semantics, side-effect scope, naming rules, and the one non-obvious return behavior (HTML pages come back with missing SEO metadata). The main gap is operational context — permissions, failure modes other than case collision — which an agent would reasonably want before a write.

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 75%, so the baseline is already decent, and the description still adds meaning: it stresses that `content` must be the FULL new content rather than a patch, and it explains that `name` is case-sensitive with a rename workaround. It does not elaborate on the `seo` enum values beyond pointing at the schema and get_block_model, so it adds real but partial value over the structured fields.

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 ('edit a workspace code file — a page, a stylesheet, a helper library') and immediately delineates it from two siblings: set_workspace_content for whole-workspace rewrites and edit_file for partial edits. The title's 'create or replace' framing is reinforced in the body, so an agent can pick it without opening the 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?

Gives explicit when-to-use (creating a file or replacing it outright), explicit when-not-to-use (don't re-send everything via set_workspace_content; don't use this for partial edits — use edit_file), and even a procedural recipe for renaming (write the new name, then delete_file the old one). Alternatives are named with the condition that selects them.

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