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

Agent Coherence — Stale Write Guard (FS)

Official
by Cohexa-ai

swg_status

Read-only

Reports coordinator state, per-path write holders, and the paths this session holds, letting you check for stale-write conflicts and handoff records before writing.

Instructions

Report coherence state: coordinator on|off|unknown (unknown is NOT off), per-path enforced|not_registered (with handoff: the path's handoff record -- giver, successor, version_at_transfer, hold_shape, status, live -- when it has one; per_path is null, not {}, when the coordinator's /status answer carries no list of tracked paths, as a degraded answer does when its registry was busy: retry shortly and do not treat it as nothing tracked; the text result then says per_path=unavailable. With coordinator=unknown, per_path is {} and says nothing about what is tracked), the write holder on each per_path entry someone holds for writing: holder_agent_id (the holder's attempt id, in the 32-hex spelling an other_holder refusal names; ids are per attempt, so it never equals session_agent_id) and held_by (this_attempt; earlier_attempt, an earlier attempt of this session whose grant still stands, which you release; or another_agent), neither key on an entry nobody holds, and this_attempt covering another caller sharing this server, since every caller of one server process is one agent to the coordinator; on_held (this server's mode: refuse when the operator set SWG_ON_HELD=refuse, else displace), held (the sorted paths this session holds for writing, either attempt; null when the coordinator cannot say who holds each path: null means cannot tell, never that nothing is held; the text result gives on_held, held, and a line per path held_by another_agent or earlier_attempt), is_attached/is_degraded/session_id, session_agent_id (this session's id as a handoff successor: the value another session passes to swg_transfer to hand this session a path; it does not change when this session reacquires, and it names this session as a successor only while principal_claim is bound), principal_claim (this session's caller-principal state: bound; unsupported = the coordinator issues none; unconfirmed = the last claim's answer was lost and the next call claims again by itself; refused = the session is bound under another nonce, so every later swg_read/swg_write/swg_gate answers the typed caller_principal_* deny with recover=restart_session while the coordinator stays on; not_attempted = nothing claimed yet), caller_principal_absent_total and caller_principal_refused_total (the coordinator's counters; null, never 0, when it is unreachable or does not report them), registry_schema_version (the schema version of the coordinator's store, an integer; an older release refuses a store at a newer version; null when the coordinator is unreachable (coordinator=unknown) or its answer carries no such field, as a coordinator built before the field does; report it to the user rather than act on it), and heterogeneous_scope_detectable=false (a multi-host or differently-scoped setup is NOT distinguishable in v1). 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

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "swg_status"
  }
}

Input Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.12.0

TDQS

A3.9/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=true, and the description adds substantial context beyond that: the difference between unknown and off, null versus {} for per_path and held, that this_attempt covers co-located callers sharing a server process, and the explicit out-of-guarantee list (multi-host writers, divergent history, auto-merge). It also flags the single-host restriction and running the tool against a heterogeneous setup, which is exactly the kind of caveat annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The content is dense but presented as one enormous sentence with deeply nested parentheses covering ten or more distinct concepts, making it hard to scan or front-load. While little of the information is redundant, the structure actively obstructs comprehension and would benefit from being split into labeled sections.

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 carry the full return-value burden, and it does so exhaustively: each field's meaning, the null-versus-empty distinction, degraded and unreachable cases, and the v1 detection limits. For a zero-parameter status tool with this many nullable and contextual states, an agent has enough to interpret the result 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?

The tool takes zero parameters, so no parameter semantics are needed and the baseline is 4. The description instead spends its space on return-field semantics (holder_agent_id, held_by, principal_claim states), which goes beyond the empty schema's burden.

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?

"Report coherence state" gives a specific verb and object and the description immediately enumerates what is reported: coordinator on|off|unknown, per-path enforcement, write holders, session/principal state, and counters. It clearly distinguishes itself from mutation siblings like swg_write or swg_gate by being a read-only report, though it never names an alternative tool outright.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Guidance is present but oriented toward interpretation rather than tool selection: "retry shortly and do not treat it as nothing tracked" for a degraded answer, and "report it to the user rather than act on it" for registry_schema_version. There is no explicit statement of when to call this versus swg_gate or swg_reacquire, leaving the diagnostic use case implied.

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