Skip to main content
Glama
Sign In
trahloff

Aldine

by trahloff
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Change several files in one commit

batch_write
Destructive

Apply multi-file edits as one named commit, validating every quote anchor and version before writing so failed entries leave all files unchanged.

Instructions

Apply one multi-file change as ONE named commit (author Claude). Each entry carries full content (new files) or quote-anchored edits (existing files, same rules as edit_file). All edits resolve before anything is written — a stale_anchor or ambiguous_anchor writes nothing (the error names the entry as path); fix that entry and resend the whole batch. A version_conflict on any entry also writes nothing: re-read that file and resend. Use it for a coherent change across files; use edit_file for a single file. message = the intent, imperative ("Add related-work section"). The result's commit and head are that commit; a batch that leaves every file as it was makes no commit and answers commit:null with unchanged:true (nothing is pending).

Input Schema

NameRequiredDescriptionDefault
filesYes
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.
messageYesCommit message stating the intent of the change, at most 200 characters.
projectNoProject id. Optional when the access token is scoped to exactly one project.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare destructive/not-idempotent, so the description's added value is the all-or-nothing atomicity contract: 'All edits resolve before anything is written,' stale_anchor/ambiguous_anchor/version_conflict write nothing, and the error names the offending entry. It further discloses the no-op edge case (commit:null, unchanged:true, nothing pending), which no annotation covers.

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?

Front-loaded with the action and the sibling routing in the first and eighth clauses, with error semantics clustered after. It is dense and slightly run-on (errors, no-op result, and message style all in one paragraph), but essentially every sentence carries distinct information.

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, multi-file write with no output schema, the description covers atomicity, per-error recovery, and what the return value contains (commit, head, and the unchanged no-op case). Nothing an agent needs to invoke it safely and interpret the result 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 75%, so the baseline is 3; the description adds real meaning on top — the content-vs-edits mutual exclusion per entry ('full content (new files) or quote-anchored edits… same rules as edit_file') and the intent/imperative convention for message ('Add related-work section'). It stops short of discussing base_version/branch, which remain schema-only.

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 ('Apply one multi-file change as ONE named commit') and immediately distinguishes scope from the closest sibling: 'use edit_file for a single file.' An agent can tell batch_write from edit_file/write_file/commit without opening any 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?

Explicit selection rule: 'Use it for a coherent change across files; use edit_file for a single file.' It also gives the recovery procedure per error class (fix the entry and resend the whole batch; re-read and resend on version_conflict), which is when-to-use guidance in practical form.

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