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_release

Release this session's write grant on one path to unblock other agents waiting to write it, while keeping all other holds; returns ok, path, and released.

Instructions

Give back this session's write grant on one path and keep every other hold. swg_write takes a write grant on the path it writes 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. Answers {ok, path, released}. released=true means this session gave a grant back; it does not mean the path is free (another agent may hold it), and this session keeps a read at the version it held, so its next swg_write of the path needs no swg_reacquire unless the file changed since. released=false means this session had no write grant recorded on the path and nothing was sent, as on a repeat. A release the coordinator did not confirm answers reason=release_unconfirmed, recover=release_again, retryable=true: calling swg_release again is safe, at most twice more; if it still is not confirmed, report that this session's write grant on the path may still stand (swg_reacquire drops every hold, this one included). 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_release"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.16.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only supply readOnlyHint=false, so the description carries the burden and does so thoroughly: concurrency impact (other writers blocked up to 30 min), idempotent retry policy (safe to call again, at most twice more), failure path (reason=release_unconfirmed, recover=release_again, retryable=true), and the residual-risk message to report to the user. It also scopes the guarantee to SINGLE-HOST and lists what is explicitly not detected in v1.

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 purpose and the swg_write contrast, then return semantics, then failure handling. Nearly every sentence earns its place (retry limits, released=true/false meanings), though the parenthetical clauses and hyphenated asides make it dense enough to be harder to scan than necessary.

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?

With no output schema, the description still documents the response shape ({ok, path, released}) and the meaning of both released values, plus error codes and retry guidance. Nothing an agent needs in order to call it correctly or interpret the result is missing.

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 coverage is 0%, so the description must compensate for the lone 'path' parameter. It does clarify that path identifies the path holding this session's write grant ('on the path it writes', 'one path'), but it never states a format, base directory, or whether paths must match exactly what swg_write used, leaving the syntax undocumented.

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 ('Give back this session's write grant on one path') plus the scope ('keep every other hold'), and explicitly contrasts with swg_write ('swg_write takes a write grant ... and keeps it'). An agent can distinguish this from swg_write and swg_reacquire without opening the 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?

Gives an explicit trigger ('When you finish writing a path, swg_release it'), states the cost of not calling it (other opted-in agents wait up to 30 minutes), and pre-empts a pointless call by noting a repeat returns released=false with 'nothing sent'. It also names the relevant siblings and when swg_reacquire is not needed.

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