Skip to main content
Glama
Sign In
trahloff

Aldine

by trahloff
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Write a whole file

write_file
DestructiveIdempotent

Creates a new file or replaces an entire file in an Aldine project; pass a base version to avoid overwriting newer content.

Instructions

Create a new file, or replace a whole file. For an existing file prefer edit_file — a whole-file write on an open document teleports collaborators' viewports and can drop their in-flight typing. Pass base_version (contentVersion from a prior read of this file) to get {error:"version_conflict"} instead of overwriting newer content — only a change to this file conflicts, never one to another file; on conflict re-read and re-write once, then ask. Folders come into being with the first file written inside them. The first .tex written into a project with no main document becomes the main document (newRoot in the result). Committed as author Claude before the tool answers, under message (the intent, imperative); without one the commit is titled "Update ". The result's commit and head are that commit; content identical to the file makes no commit and answers commit:null with unchanged:true (nothing is pending).

Input Schema

NameRequiredDescriptionDefault
pathYesFile path relative to the project root, e.g. "main.tex" or "sections/intro.tex" — no leading "/", no "..", and hidden folders (.git, .aldine-out) are off limits.
branchNoBranch name (defaults to 'main'). Every result, error results included, echoes {branch, head} — head is the branch's current commit (after a write, the commit that write made). Pass the branch explicitly whenever you are not on main.
contentYes
messageNoCommit message stating the intent of this change, imperative ("Tighten the abstract"), at most 200 characters. It titles the commit in the History panel; every call is one commit.
projectNoProject id. Optional when the access token is scoped to exactly one project.
base_versionNocontentVersion (or fileVersion) from your read of this file, or contentVersion from project_structure for a file you are creating. Refused with {error:"version_conflict", reason, currentVersion, fileVersion} when this file changed after that read (changes to other files on the branch do not count), or when base_version is newer than the branch's contentVersion (a server restart or another node issued it) — either way re-read the file and use the contentVersion that read returns.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds genuinely non-obvious behavior beyond that: the collaborator viewport side effect, folder auto-creation, the .tex main-document promotion (newRoot), author/commit semantics, and the no-op case returning commit:null with unchanged:true. It does not discuss permissions or rate limits, hence a 4 rather than 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?

The action statement and the edit_file routing are front-loaded, and nearly every clause carries information an agent needs. It is a dense single block with several ideas chained together, which costs some readability, but there is little wasted text.

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?

There is no output schema, so the description must explain results, and it does: version_conflict shape, newRoot, the returned commit and head, and the unchanged:true/commit:null no-op case. For a 6-parameter destructive write tool this is complete enough to call correctly.

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 high (83%), so the schema carries most parameter meaning and the baseline would be 3. The description nevertheless adds value the schema does not state: conflict scope ('only a change to this file conflicts, never one to another file'), the re-read-once retry protocol, and the default commit title 'Update <path>' when message is omitted.

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 plus scope: 'Create a new file, or replace a whole file.' It immediately distinguishes itself from the sibling edit_file, so an agent can tell the two apart without opening either 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?

States explicitly when to prefer the alternative ('For an existing file prefer edit_file') and gives the reason (collaborator viewport teleporting, dropped typing). It also gives a decision procedure for conflicts: re-read and re-write once, then ask.

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