Skip to main content
Glama
Sign In
Agent Coherence — Stale Write Guard (FS)

Agent Coherence — Stale Write Guard (FS)

Official
by Cohexa-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

swg_read

Read a coherence-tracked workspace text file to get its content, version, and owner generation, so you can detect stale views, pass the version to a compare-and-swap write, and gate risky actions.

Instructions

Read a workspace text file under coherence tracking. Returns {content, version, owner_generation}. The version is the comparand you pass to swg_write_cas; KEEP BOTH version and owner_generation and pass them to swg_gate before any irreversible external action you decide from this read (owner_generation=null means this coordinator does not report generations, so swg_gate will hold). When the path has a handoff record the result also carries handoff: the record as it concerns this session (role giver, successor or bystander, the two session_agent_ids, version_at_transfer, hold_shape, status, live); handoff_unknown=true instead means the read was denied and the record could not be fetched. The coordinator attaches the record best-effort, so a result with neither does not prove there is no record; swg_status lists every record. A sticky-INVALID view returns fresh bytes but stays INVALID — use swg_reacquire to recover before writing. If the bytes on disk are not the content at the current version, the read is DENIED with reason=stale_view and no version. A peer's commit still reaching disk clears on its own: swg_reacquire, then swg_read again, retrying for a few seconds. If it stays denied past that, the bytes on disk were never recorded (an out-of-band edit, a commit whose disk write failed, or a write whose commit did not reach the coordinator); reading again does not clear it: swg_write the content swg_reacquire returned (or your merge of it), then swg_read. A write made sooner can be overwritten by a peer commit still reaching disk. 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>"
    },
    "name": "swg_read"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.12.0

TDQS

B3.4/5.0
Behavior3/5

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

The description discloses a lot beyond the annotations: denial with reason=stale_view and no version, sticky-INVALID semantics, best-effort handoff attachment with handoff_unknown=true, and explicit non-guarantees (cross-host, synced mounts, auto-merge). However, the annotation declares readOnlyHint=false while the description frames this purely as a read and never explains what state the call touches or why it is not read-only, which is the one behavioral fact an agent most needs from the annotation/description pair.

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 purpose and return shape are correctly front-loaded, and most sentences carry real operational content rather than filler. But the remainder is one undifferentiated block of run-on sentences mixing return contract, handoff semantics, denial recovery, and out-of-scope caveats with no ordering or structure, making it hard to scan under time pressure.

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 tool whose behavior is entangled with a coherence protocol, the description covers the important states: success, handoff present, handoff_unknown, stale_view denial with its two causes and distinct remedies, and the v1 out-of-guarantee list. With no output schema, it correctly describes the return payload. The gaps are the unexplained non-read-only annotation and the absence of any path format guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one parameter, path, with 0% schema description coverage, so the description must carry the meaning and largely does not: it never says whether the path is workspace-relative or absolute, what file types are acceptable beyond 'text file', or how a path maps to a handoff record. The phrase 'when the path has a handoff record' implies path is the record key, which is the only semantic addition.

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 first sentence gives a specific verb and resource ('Read a workspace text file under coherence tracking') and immediately states the return shape {content, version, owner_generation}, so the agent knows exactly what it gets back. It does not, however, cleanly distinguish itself from siblings as read alternatives — siblings appear only as downstream steps (swg_write_cas, swg_gate, swg_reacquire, swg_status) rather than as things this tool might be confused with.

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?

Guidance is unusually explicit about next actions: pass version to swg_write_cas, pass both version and owner_generation to swg_gate before any irreversible external action, use swg_reacquire before writing on a sticky-INVALID view, and consult swg_status for the full record list. It also states the recovery loop for stale_view (reacquire, re-read, retry a few seconds) and what to do if that fails. What is missing is when NOT to call this at all (e.g. alternatives for non-text or cross-host scenarios), though 'SINGLE-HOST only' partly covers that.

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