Agent Coherence — Stale Write Guard (FS)

Official

Overview Schema Source Related Servers Discussions Admin

swg_write

Writes a workspace text file under a stale-write guard: acquire the path, write, commit, and keep the grant until released so concurrent agents cannot silently overwrite changes.

Instructions

Write a workspace text file (acquire -> write -> commit). In either mode the write takes a write grant on the path and keeps it after the write. When you finish writing a path, swg_release it: until you do, other opted-in agents that write it wait, for up to 30 minutes. On a refuse-mode server (SWG_ON_HELD=refuse) a success also carries opted_in: true when the write asked first, false when the path is not among the managed files, so the write took the file from any agent that held it. A refusal carries reason, recover and retryable; follow its next_step when it has one. DENIED with reason=stale_view if the file changed since you read it — a peer commit OR an out-of-band edit (another tool/editor): recover with swg_reacquire, then write FROM its bytes, never the content you just sent. The other reasons: other_holder (refuse mode only), another agent holds the path and nothing was written (recover=wait_then_reacquire); commit_preempted, a mid-write preempt (disk may hold un-versioned bytes; reacquire_and_reconcile); commit_unconfirmed, the bytes are on disk but may be unrecorded (recover=write_again); link_out_of_managed (refuse mode only), the path goes through a link to a file outside the managed files; handed_off, this session handed the path off; coordinator_failed, the coordinator failed while answering (recover=reacquire when an earlier attempt of this session still holds the path); coordinator_unavailable, it gave no usable answer or is not attached; caller_principal_absent, caller_principal_foreign or caller_principal_claimed, this session's caller principal was refused (swg_status shows principal_claim); internal_error, a failure with no recovery; invalid_path or io_error, a bad path or a disk failure. SINGLE-HOST only. Out of guarantee and NOT detected in v1: writers on different hosts or across a synced/network mount, divergent-history reconciliation, semantic correctness, server-enforced auto-merge.

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": "swg_write"
  }
}

Input Schema

Name	Required	Description	Default
`path`	Yes
`content`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.12.0Jul 15, 2026

TDQS

A4/5.0

Behavior5/5

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

Annotations only declare readOnlyHint=false, so the description carries real weight and delivers: a write grant is taken on the path and retained after the write, peers block for up to 30 minutes, refuse-mode success carries opted_in true/false with its meaning, and DENIED reasons each come with a named recovery. It also flags the guarantee boundaries (single-host, out-of-band edits, un-versioned bytes after commit_preempted) that an agent could not infer from annotations.

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?

The core behavior and the release obligation are correctly front-loaded, but the error taxonomy is a single enormous run-on sentence enumerating a dozen reasons, which is hard to scan and mixes primary usage with exhaustive failure reference. The closing 'Out of guarantee and NOT detected in v1' sentence does earn its place as a scope boundary.

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 two-parameter mutation tool with no output schema and minimal annotations, the definition covers lifecycle, contention, recovery and scope limits thoroughly, and even describes what a success response carries in refuse mode. The remaining gaps are path format/content semantics and the absence of any statement about what the commit returns in non-refuse mode.

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 0% for both required parameters, so the description must compensate and only partly does: it implies path semantics via managed files, links (link_out_of_managed) and stale_view, but never states whether path is workspace-relative or absolute, nor anything about content encoding or size. The parameter names are self-evident enough that this is a moderate rather than severe gap.

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?

The description states a specific verb and resource ('Write a workspace text file') and even sketches the protocol (acquire -> write -> commit), so an agent knows exactly what the tool does. It does not distinguish itself from the closest sibling, swg_write_cas, so an agent cannot tell from this text which of the two write tools to pick.

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?

It gives clear operational routing: release the path with swg_release when done, otherwise other opted-in agents wait up to 30 minutes; on stale_view, recover with swg_reacquire and rewrite from its bytes; on a refusal, follow next_step. What is missing is a positive statement of when to prefer swg_write over swg_write_cas, and any exclusion for non-text or cross-host use beyond the closing SINGLE-HOST note.

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

Deploy Server