Skip to main content
Glama

write_file

Destructive

Apply verified operational-transform updates to an Overleaf document by replacing full text or targeted old/new text edits, optionally recording tracked changes.

Instructions

Replace a text document with a verified OT update that changes only the words that differ, optionally recorded as tracked changes, one per changed group of words; where a changed word touches a comment or tracked change, the update is one edit from the first change to the last instead. Supply the new text through exactly one of content (the whole text), localPath (a local file holding it, never sent through the tool call), or edits: 1 to 100 { oldText, newText } applied in order to the document at revision, each oldText matching exactly once in the text the edits before it left, with whitespace and line endings exact; an empty newText deletes. An oldText that does not match is INVALID_ARGUMENT with details.kind edit_not_found, one that matches more than once edit_ambiguous, each with details.editIndex (0-based), and nothing is sent; otherwise the result is written as content would be. A write that hit a timeout, a lost socket, or an error Overleaf reported on the document after the update was sent is never resent: the live document is observed instead, and recoveredAfterTimeout: true means the intended text was confirmed. An update Overleaf refused as too large is UPDATE_TOO_LARGE with details.outcome not_applied: nothing was stored. On a ShareJS (legacy editor) document, text that adds a character outside the Basic Multilingual Plane, such as an emoji, adds another copy of one the document holds, or changes their order is INVALID_ARGUMENT with details.line (1-based) and nothing is sent, because Overleaf would store it as U+FFFD; editing text on either side of one the document already holds is fine. With writeMode tracked, a write Overleaf applied without recording it as tracked changes by this account is PROTOCOL_UNSUPPORTED with details.kind applied_untracked and details.liveRevision: it is live and not reverted, so read the file before writing again; if another update followed the write before that check, it is REVISION_CONFLICT with details.outcome unknown instead. A review-only collaborator can write only with writeMode tracked, and a read-only one cannot write: either is PERMISSION_DENIED before anything is sent.

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": {
      "projectId": "<projectId>",
      "filePath": "<filePath>",
      "revision": "<revision>"
    },
    "name": "write_file"
  }
}

Input Schema

NameRequiredDescriptionDefault
editsNoTargeted changes, 1 to 100, applied in order; exactly one of content, localPath, edits
contentNoComplete replacement text; exactly one of content, localPath, edits
filePathYesProject-relative path using forward slashes
revisionYesOpaque revision returned by a prior read or write
localPathNoLocal UTF-8 text file holding the complete replacement; exactly one of content, localPath, edits
projectIdYesOverleaf project ID
writeModeNoUse tracked to record inserted and deleted text as Overleaf tracked changes; defaults to untrackeduntracked

Output Schema

NameRequiredDescriptionDefault
protocolYes
revisionYes
writeModeYes
trackChangesActiveYes
recoveredAfterTimeoutNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.3.0

TDQS

A4.5/5.0
Behavior5/5

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

Far exceeds what destructiveHint=true and idempotentHint=false convey: it discloses that failed writes are never resent but observed instead, the exact error kinds (edit_not_found, edit_ambiguous, UPDATE_TOO_LARGE with details.outcome not_applied, PROTOCOL_UNSUPPORTED applied_untracked, REVISION_CONFLICT), the ShareJS BMP/emoji rejection, and the collaborator permission model. No statement contradicts the annotations; 'nothing is sent' on validation failure is consistent with a destructive but non-idempotent write.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, and nearly every clause carries unique operational information, but it is delivered as an unbroken multi-hundred-word sentence chain with no paragraphing or list structure, making the critical failure-mode information hard to scan. Sizing is defensible for the complexity; the formatting is not.

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 destructive, non-idempotent write against a collaborative OT document with an existing output schema, the description covers input modes, ordering semantics, error taxonomy, recovery behavior, legacy-editor limits, and permissions. An agent has everything needed to invoke it correctly and to interpret the failure cases.

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 baseline is 3, but the description adds real meaning: localPath is 'never sent through the tool call', edits are applied in order with each oldText matching exactly once in the text left by prior edits with exact whitespace and line endings, and an empty newText deletes. The only reason this is not a 5 is that revision is left as the schema's opaque token with no added guidance on reuse.

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?

Opens with a specific verb and resource: 'Replace a text document with a verified OT update that changes only the words that differ'. It immediately distinguishes itself from create_file (which would add a document) and write_section (section-scoped) by scoping the behavior to whole-document wording-level replacement with optional tracked changes.

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?

Gives explicit selection rules among its own input modes ('exactly one of content ... localPath ... or edits') and states the condition for writeMode tracked, plus the permission cases where writing is possible or blocked. It does not, however, name sibling alternatives such as write_section for section-scoped edits, so the agent must infer that routing itself.

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