Provides integration with Git through a pre-commit hook, enforcing claims and conflict detection before commits, with a landing queue that uses git operations like rebase and update-ref.
Uses a single SQLite file as the local-first rendezvous point for coordination state, claims, and radar snapshots across worktrees.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agent-semaphore claim src/api for auth refactoring"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A coordination layer for parallel coding agents. Worktrees do not remove merge conflicts — they postpone them to integration time. agent-semaphore closes the gap: intent-carrying claims on scopes, a warning at the moment of writing, conflict prediction before anything is committed, and a serialized landing queue with a mandatory test gate.
Local-first: no daemon, no cloud, no account. A single SQLite file in the git common dir
is the whole rendezvous point, so every worktree of the repo sees it by construction.
Cross-vendor by design — Claude Code hooks and MCP, Codex CLI over MCP, everyone else
over a git pre-commit hook.
Agent-written pull requests conflict at 27.7% — against 10–20% for human ones (AgenticFlict, 107K+ agent PRs). On co-active pairs the split is 19.8% intra-agent vs 41.7% cross-agent: agents have no horizontal awareness of each other, and every product that ships coordination coordinates only its own agents. A badly resolved conflict carries up to ~26x the bug density of ordinary code (EMSE 2020) — the expensive part is not the conflict, it is the quiet bad resolution.
Isolation is solved and commoditized (a worktree or a container per agent — everyone
ships it). Prediction and integration are not: nobody runs git merge-tree between live
worktrees, and standalone local merge queues effectively do not exist.
Related MCP server: MCP Agent Mail
Layer | Mechanism |
Claims | Leases, never locks: TTL, renewal by activity, monotonic fencing epochs, a mandatory intent ( |
Enforcement | A |
Radar | Snapshots of dirty worktrees taken through a temporary index (never mutating the working tree), compared pairwise with |
Queue | FIFO under |
Hard guarantees exist at exactly one place: the landing path. Hooks and pre-commit are
cooperative admission control and telemetry, not a security boundary — ASEM_HOOK_OFF=1
and ASEM_OVERRIDE=1 are documented, audited escape hatches. This is stated up front
because a coordination layer that pretends to be a sandbox is worse than none.
uv tool install git+https://github.com/alwh1te/agent-semaphore # asem on PATH
# or, from a clone: uv tool install -e .
cd <your repo>
curl -O https://raw.githubusercontent.com/alwh1te/agent-semaphore/main/.agent-semaphore.toml.example
mv .agent-semaphore.toml.example .agent-semaphore.toml # set the gate command, hot classes, target branch
asem init # state in .git/agent-semaphore/
asem install --git-hooks # Claude Code hooks + .mcp.json + git pre-commit
asem doctor # PASS checklistasem claim src/api/ -i "refactor auth parsing" --ttl 30m # exit 3 = held by someone else
asem check src/api/routes.py # who holds it, and what for
asem radar # conflicts between worktrees, before any commit
asem land feature-branch # rebase -> gate -> CAS into the staging branch
asem notices # messages addressed to you
asem status | asem queue status | asem doctorExit codes are part of the contract: 0 ok/free, 3 held/conflict/bounced, 2
usage, 1 internal error — a script can tell "coordination said no" from "the tool
broke".
Nobody in this space had measured whether claims actually reduce conflicts, so the repo ships two benchmarks of its own.
Scripted (docs/benchmark.md, 60 runs, deterministic agents,
compliance = 1 by construction): integration conflicts 60% → 0%, human interventions
9 → 0.
Live agents (docs/bench-llm.md, 40 runs of two concurrent
claude -p agents, $17.95):
mode | ICR | WME | did_work | caught-up | $/run | COR |
no coordination | 40% | 2 | 100% | 0% | $0.34 | 1.00x |
advisory claims | 20% | 1 | 100% | 40% | $0.50 | 1.72x |
claims + radar | 10% | 2 | 80% | 40% | $0.46 | 1.93x |
strict + queue | 0% | 0 | 100% | 40% | $0.50 | 1.98x |
Three findings the scripted harness structurally could not produce:
Conflicts are removed by the catch-up, not by the claim. 10 out of 10 runs where an agent rebased onto its peer's branch merged clean; every conflicted coordinated run is one where both agents claimed politely and neither rebased. A claim serializes writing — it does not hand you the other agent's result. That finding is what produced the "release wakes the waiters and names the branch" feature.
The hook never fired once in 40 runs. With the protocol in the prompt, agents claim before editing and never write into a held scope, so enforcement turned out to be insurance that was not needed — not the working layer.
Coordination can convert a conflict into work that never happened. In two runs the
blocked agent quoted the holder, its intent and its branch, and abandoned its task.
Without the did_work column next to ICR, those runs read as a clean success — which
is why the column is there.
Semantic drift (textually clean, semantically broken) survives every advisory layer in both benchmarks and is caught only by the queue's mandatory gate.
Claude Code — asem install writes project .claude/settings.json (PreToolUse +
PostToolUse), adds Bash(asem:*) and mcp__semaphore__* to the allow-list, and
registers the MCP server in .mcp.json. Committed wiring is host-portable ($HOME
and a bare asem), so a repo shared across machines does not carry one host's paths.
MCP (asem mcp, server key semaphore) — claim, release, check, status,
extend, report_intent, radar, enqueue_land, land_status. Every response
drains pending notices, so agents learn about steals, bounces and moved targets without
polling.
Codex CLI — same MCP server via ~/.codex/config.toml, plus a protocol snippet for
AGENTS.md. Headless Codex silently cancels MCP calls unless the tools are
pre-approved; docs/integration.md has the working config.
Anything else — asem install --git-hooks puts a pre-commit gate in the shared
hooks dir (it chain-loads whatever hook was there before).
docs/00-research.md — the research dossier this design is
built on: the measured problem, the tool landscape, the classic prior art worth
stealing from, the 2024–26 papers, and the three confirmed gaps in the market.
docs/adr/ADR-001-architecture.md — the
architecture, plus a risk register and ten adversarial attacks from a blind review
(eight of them changed the design).
docs/adr/ADR-002-stack-and-state.md — stack,
naming, and where state lives.
docs/benchmark.md / docs/bench-llm.md —
both benchmarks: method, results, and the limitations spelled out.
docs/integration.md — installation and what is wired where.
v1 is implemented and dogfooded: the repository coordinates its own agents through it. 150 tests, a p95 hook-latency gate in CI, both benchmarks reproducible from the repo.
Known limits, stated plainly: promotion from the staging branch to main is still manual
and ungated (asem promote is the next feature); the queue never pushes; there is no
symbol-level scoping, no semantic conflict detection beyond the test gate, no LLM
auto-resolution (the published ceiling is ~55–60% correctness, which is not good enough
to run unattended); and multi-host is a v2 design, though the schema already carries the
host column.
uv run pytest -q # 150 tests
uv run ruff check . && uv run ruff format --check .
uv run python bench/hook_latency.py 200 # hook latency gate (p95 < 100 ms)
uv run python bench/runner.py --seeds 3 && uv run python bench/report.pyThe PreToolUse hook script is vendored outside the package and must stay stdlib-only —
it runs on every write of every agent, so it has a latency budget rather than
dependencies. See CONTRIBUTING.md.
MIT — see LICENSE.
Read-only: who holds these paths/scopes right now (holders with intents, hot-class membership). Call before expanding your edit scope.
| Name | Required | Description | Default |
|---|---|---|---|
| paths | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does the most important thing by declaring 'Read-only' upfront, plus hinting at the response content (holders, intents, hot-class). It omits error behavior, whether paths are globs, staleness/consistency of the holder snapshot, and any permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with the safety property ('Read-only') front-loaded and the usage trigger at the end. Every clause carries information, though the parenthetical jargon costs some immediate readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no annotations and no output schema, the description should explain the shape of what comes back and the path format; it only sketches the return content conceptually. Adequate for an agent already familiar with the lock workflow, thin for a newcomer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% for the single 'paths' parameter, so the description must compensate. It does partially by noting 'paths/scopes', implying the array accepts scope identifiers as well as paths, but gives no format, glob syntax, or path-resolution rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific framing — 'who holds these paths/scopes right now (holders with intents, hot-class membership)' — which identifies it as a read-only holder/lock query, distinct from siblings like claim, release, or extend. The jargon ('hot-class membership', 'intents') is undefined, so the exact semantics of what a 'holder' is remain somewhat opaque.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Call before expanding your edit scope' gives a clear, actionable trigger for using this tool. It does not name a specific alternative (e.g. 'use status for global view, check for per-path') or state when not to call it, keeping it short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Atomically claim path scopes (dir/ preferred, file, or basename glob) before editing them. Blocked responses name the holders, their intent, lease remaining, and advice (wait | narrow_scope | coordinate | steal_candidate).
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | exclusive | |
| wait | No | ||
| reason | Yes | ||
| scopes | Yes | ||
| task_id | No | ||
| ttl_minutes | No | ||
| plan_summary | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it does deliver real value: atomicity is stated, and the blocked-path response is described in detail (holders, intent, lease remaining, and the four advice values). However it omits whether a successful claim creates a persistent lease, how expiry works, and whether `wait` blocks the caller, which are the behaviors an agent most needs to reason about failure and retry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the core action front-loaded and the failure-mode detail relegated to second position, which is the right ordering. Dense but every clause carries information; no filler or restatement of the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a seven-parameter mutation tool with no annotations and no output schema, the description is thin. It explains scope syntax and blocked responses but leaves the mode, wait, TTL, and task-linking parameters undefined, so an agent cannot confidently construct a call beyond the two required fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across seven parameters, so the description must compensate and mostly does not. Only `scopes` receives any semantic treatment (the dir/file/glob forms); `mode`, `wait`, `reason`, `task_id`, `ttl_minutes`, and `plan_summary` are entirely unexplained, and `mode` and `wait` materially change the tool's behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (claim) and resource (path scopes) and enumerates the accepted scope forms: directory with trailing slash preferred, file, or basename glob. That is concrete enough for an agent to know what the tool operates on. It stops short of differentiating itself from the sibling `check`, which is the obvious adjacent operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"before editing them" gives a clear and actionable trigger condition for invoking the tool, which is more than most definitions offer. It does not name alternatives or exclusions, so it never tells the agent when to use `check`, `release`, or `extend` instead, leaving sibling routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enqueue my branch for serialized, test-gated landing into the integration
target. My active claims become retained until the land completes. The queue is
processed by asem queue run (run it via Bash after enqueueing, or poll
land_status). Never merge into the target yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| branch | No | ||
| gate_cmd | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that landing is serialized and gated by tests, that active claims are retained until completion, and that an external command must actually process the queue. Gaps remain around what happens on gate failure, queue position, and whether enqueueing is idempotent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each doing distinct work: what it does, side effects on claims, how the queue is processed, and the prohibition. Front-loaded with the core action and free of boilerplate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description must cover return behavior and parameter meaning — it covers the workflow side well but leaves both parameters undocumented and doesn't say what enqueueing returns (queue position, ticket id) or how to detect gate failure beyond land_status.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for both parameters. The description never mentions `branch` (e.g. whether it defaults to the current branch) and never explains `gate_cmd` — its format, whether it overrides a default gate, or what happens when omitted. 'My branch' only weakly implies the branch parameter, leaving gate_cmd completely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
A specific verb and resource ('enqueue my branch') plus the exact semantics of the operation: serialized, test-gated landing into the integration target. That distinguishes it clearly from siblings like land_status (polling), claim, and release.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete next-step guidance: run `asem queue run` via Bash after enqueueing, or poll land_status. It also carries an explicit prohibition ('Never merge into the target yourself'), which steers the agent away from a plausible wrong action. It does not state preconditions, e.g. whether a branch must be claimed first, so it falls short of a full when/when-not/alternatives matrix.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extend one of my leases (activity usually renews them automatically).
| Name | Required | Description | Default |
|---|---|---|---|
| claim_id | Yes | ||
| ttl_minutes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, and it supplies only one trait: that activity normally auto-renews leases. It does not state that this is a mutation with side effects on lease lifetime, what happens if the extension fails or the claim expired, whether permissions are required, or what the call returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler, and the auto-renewal caveat is placed immediately after the action. It is perhaps too terse for the gaps it leaves, but nothing in it is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with no annotations and no output schema, the description leaves the default-TTL behavior, failure modes, and return shape entirely unexplained. It gives just enough to guess the intent, not enough to call the tool confidently in edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so both parameters are undocumented in the schema and the description must compensate. It only indirectly gestures at ttl_minutes via 'extend' and never explains that claim_id identifies the lease being extended or what happens when ttl_minutes is omitted (its default is null) — the most consequential ambiguity for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the verb 'Extend' and the resource 'leases,' which is more specific than the bare name but only marginally so, since the description largely restates the tool name. It never distinguishes this from siblings like claim, release, or check, so an agent must infer that 'extend' means lengthening an existing lease's TTL rather than acquiring or releasing one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical 'activity usually renews them automatically' is a real usage hint: it implies this call is only needed when the agent is about to be idle and wants to hold the claim. However, it never says 'use this when X, otherwise use Y,' and no alternative sibling is named, so the guidance stays implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Status of land-queue entries. Bounce/park results carry conflict files and exact instructions — a bounced entry means YOU rebase and fix in your worktree, then enqueue again.
| Name | Required | Description | Default |
|---|---|---|---|
| entry_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load, and it does disclose real behavior: bounce/park outcomes include conflict files and instructions, and the agent is expected to rebase and re-enqueue. However, it omits whether the call is read-only, what a non-bounce result looks like, and what happens when no entry_id is supplied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose, then the actionable detail about bounced results. The second sentence runs long but every clause carries operational meaning, so little is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-style tool with no output schema and no annotations, the description covers the failure path well but leaves the normal return shape and the entry_id scoping behavior undefined. It is adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the single optional parameter 'entry_id' is never mentioned in the description. The crucial ambiguity — whether omitting entry_id returns all entries or fails — is left entirely unresolved.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource precisely — 'land-queue entries' status — which an agent can distinguish from general siblings like 'status' or 'report_intent'. It does not explicitly differentiate itself from the closely-named 'check' or 'claim', so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to call this versus 'check', 'status', or 'enqueue_land'. The only guidance is post-hoc: what the agent should do after receiving a bounced result, which is workflow advice rather than tool selection advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cross-worktree conflict prediction: dry-run merges (git merge-tree) between every dirty worktree snapshot and the integration target. TEXTUAL/STRUCTURAL pairs mean your uncommitted direction already collides with someone — coordinate now, not at merge time. UNSTABLE means a snapshot tore mid-scan: rerun.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the full burden and does meaningful work: 'dry-run' signals a non-mutating scan, and it explains the meaning of the TEXTUAL/STRUCTURAL and UNSTABLE result codes the agent will encounter. It omits cost/latency and scope (how many worktrees are scanned, whether it requires an integration target to exist), which keeps it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the mechanism, then the interpretation guidance, then the retry rule. The second sentence is dense with em-dashes and jargon ('uncommitted direction already collides'), which slightly raises reading cost but nothing is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-annotations, no-output-schema tool, the description supplies the important missing context: what it scans, that it is a dry run, and how to read its result codes. Preconditions such as needing an integration target or dirty worktree state are implied rather than stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no argument meaning to convey and the baseline is 4. The description correctly does not waste space on inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete action—dry-run merges (git merge-tree) between dirty worktree snapshots and the integration target—so the agent knows this is a pre-merge conflict prediction scan. It does not name any sibling (check, status, land_status) as an alternative, so differentiation still requires inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Timing guidance is implied rather than stated: 'coordinate now, not at merge time' suggests running before a merge, and 'UNSTABLE means a snapshot tore mid-scan: rerun' gives a retry rule. There is no explicit when-not-to-use and no pointer to which sibling to pick instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Release my claims (all, or those matching the given scope patterns). retain=true keeps them alive until my branch lands (use when work is committed but not yet merged).
| Name | Required | Description | Default |
|---|---|---|---|
| retain | No | ||
| scopes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full burden for what is evidently a state-mutating operation. It explains the retain lifecycle nuance, but omits consequential behavior: whether releasing affects other agents, what happens if the scopes match nothing, whether release is idempotent, or whether it errors when you hold no claims.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the primary action front-loaded and the conditional nuance relegated to a parenthetical. Nothing is redundant, though the parenthetical packs two ideas together.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no annotations and no output schema, the description covers purpose and both parameters adequately. It falls short on outcome information — what the caller sees after release, and failure modes when scopes don't match held claims.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does compensate for both parameters: 'scopes' is framed as patterns to match, and 'retain' is given a concrete lifecycle meaning. It still leaves the pattern syntax (glob? exact path? regex?) undefined, so an agent cannot reliably construct the scopes value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ('Release my claims') and states the two granularities (all, or matching scope patterns). It is clearly the inverse of the sibling 'claim' and distinct from 'extend', though it never names those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It carves out one clear conditional case for retain=true ('use when work is committed but not yet merged'), which is real guidance. However, it says nothing about when to prefer 'extend' over 'release', or when a plain release is appropriate versus retaining.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Declare what you PLAN to touch (no blocking): records an intent claim and returns overlaps with other agents' claims and intents so overlapping tasks can be serialized before work starts.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| plan_summary | Yes | ||
| expected_scopes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the full burden and does disclose the single most important behavioral trait: the call is non-blocking, so it never gates the caller. It also states what comes back (overlaps with other agents' claims and intents). Gaps remain on claim lifetime, whether a follow-up release is required, and idempotency on repeat calls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with the key constraint '(no blocking)' front-loaded, so the reader gets the important qualifier immediately. It is efficient, though the line break mid-sentence and the dense trailing clause slightly hurt readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-required-parameter tool with zero annotations, zero schema descriptions, and no output schema, the description should explain the parameter contract and the shape of the overlap response. It covers the return concept and the non-blocking nature but leaves the parameter semantics and the claim's lifecycle undefined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across three required parameters, so the description must compensate and largely does not. 'What you PLAN to touch' loosely maps to expected_scopes, but task_id and plan_summary are never explained, nor is the expected string format of a scope (path, module, resource id?), which is exactly what an agent would get wrong.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete action (records an intent claim) and a concrete outcome (returns overlaps with other agents' claims), which is far more than the bare name conveys. The parenthetical '(no blocking)' implicitly separates it from the blocking 'claim' sibling, but no sibling is named outright, so the differentiation is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The trailing clause 'so overlapping tasks can be serialized before work starts' implies the moment to call it (pre-work declaration), which is useful but indirect. There is no explicit when-not guidance and no named alternative such as claim/release/check, leaving the agent to guess which coordination tool to reach for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Live coordination picture: agents, claims with intents, integration queue, wait tickets, stale items.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. 'Live coordination picture' implies a real-time read-only aggregate and 'stale items' signals freshness awareness, but it does not explicitly state read-only behavior, scope, or whether the view is globally aggregated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded fragment with no wasted words. It is telegraphic but efficient for a status tool, though a complete sentence with a verb would be slightly clearer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read tool with no output schema, listing the content categories substitutes reasonably for return-value documentation. It tells an agent what to expect from the response, though it could clarify scope or freshness guarantees.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter semantics to document; the baseline for a no-parameter tool is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description expands 'status' into a specific content inventory: agents, claims with intents, integration queue, wait tickets, and stale items. It clearly conveys a live coordination overview, though it lacks an explicit verb and does not distinguish itself from siblings like land_status or radar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to call this tool versus alternatives. Sibling tools such as land_status, radar, and check could plausibly overlap, and the description provides no conditions for choosing between them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0checkclaimenqueue_landextendland_statusradarreleasereport_intentstatusScored across 9 tools
Most tools have clearly distinct roles: claiming, releasing, extending, conflict prediction, enqueueing, and status inspection. The closest overlaps are check vs. status (scoped vs. global read-only views) and claim vs. report_intent (blocking vs. non-blocking declaration), but the descriptions make those distinctions reasonably clear.
The naming mixes bare verbs (claim, check, release, extend), verb_noun forms (report_intent, enqueue_land), and noun-style names (radar, status, land_status). It is still readable and none of the names are cryptic, but there is no predictable naming convention across the set.
Nine tools is well-scoped for an agent coordination server covering claims, intents, conflict detection, and landing. Each tool appears to earn its place without obvious redundancy in count.
The surface covers the main lifecycle: discovery, claiming, releasing, extending, intent reporting, conflict prediction, enqueueing, and status checking. Minor gaps remain, such as no explicit cancel/dequeue operation for a land-queue entry or intent revision, but core workflows are supported.
Coordination for AI coding agents: declare plans, catch design conflicts early, share team memory.
Source control for coding agents: declare an intent, settle overlaps before code, verify each push.
Coding agents from Claude Code, Cursor and Codex claim jobs and lock files on one shared board.
Coordination hub for AI coding agents: message teammates, ask humans, audit every event.
