Skip to main content
Glama
mergestorm-mcp

mergestorm-mcp

Official

Wait for stack attention

stack_wait
Read-onlyIdempotent

Wait for a pull-request stack to need attention, returning status snapshots or a timeout envelope so clients can monitor blockers and decide when to act.

Instructions

Wait for a stack to need attention. Returns a mergestorm.stack_watch/v1 envelope; timeout_s: 0 returns one snapshot and timeout_s: 1-45 waits up to that many seconds, returning the current status (waiting or in_progress) if a snapshot was read and no attention is found. A timeout with either of those statuses is not a failure; waiting and in_progress end this slice, and the next call is stack_wait again with the same cursor. A timeout of failed means no assessment was produced. A stack that no longer exists returns status failed with watch.done true (reason not_found) and is not an error. While Cyclone or Vortex is still working on the blocked PR it returns in_progress, not attention, with busy[] naming the PR, blocker, and agent; agents carries that PR's vortexStatus, cycloneStatus, vortexReview, and busy flags. When another layer has a blocker no agent works on, attention names that blocker instead and busy[] is empty. A blocker no agent run clears (a merge conflict vs the live parent, a restack Conflict or Restack failed, a Draft PR, a seam review pending with no review running, "Seam review stuck in reviewing, no review running", "Seam re-review pending, no review running", "Seam verdict is for an older head, no review running", or a review skipped for review quota) is still named during that in_progress, in blocker, prNumber, headSha, and issues[], with actAfter: "agents_idle" and waitingOn listing the busy agents: plan the fix, and act when a snapshot after the agents finish returns attention, re-reading the blocker then. A merge conflict or restack Conflict waits only for a Cyclone run that is pushing, never for a Vortex review, and Cyclone starts no review-fix batch on a conflicted head. Blockers the agents can change keep blocker and actAfter null. Attention never calls for changing a PR's GitHub base. When present, repair names the concrete fix for attention (restack_conflict and merge_conflict carry liveParent, never mg-park-*). For the three stuck-seam blockers, repair kind seam_review_stuck: do not patch or push; tell the human to click Continue, which re-queues the seam review at the live head. A pending land gate (landGatePending) returns in_progress, not attention. Auto land off after a merge_failed, gh_error, or ci_timeout bounce (the stack's autoLandOff reads reason bounced) returns attention with the blocker "Auto land off after bounce", the bounce in issues[], and a repair of kind auto_land_off: fix the cause, then turn Auto land back on or enqueue. auto_land_switched_off (returned only when the PR has no live blocker of its own): Auto land was switched off without a bounce (queue entry cancelled, or nothing left to land); do not patch, push or turn it back on yourself, tell the human. A Vortex request_changes handoff at the live head returns attention with blocker "Vortex findings need a person" and repair kind vortex_findings; verify its findings against the live head. Attention covers every open layer, parked ones included, not only currentCandidate: it names the lowest layer with a blocker an agent must fix and no Vortex or Cyclone run working on it, and once that blocker clears the next read names the next blocked layer. Follow watch.next.args until watch.done; background watching requires a confirmed host notification. See server instructions.

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": {
      "stack_id": "<stack_id>"
    },
    "name": "stack_wait"
  }
}

Input Schema

NameRequiredDescriptionDefault
stack_idYes
bounce_idNo
timeout_sNo
after_finished_atNo
enrolled_head_shaNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.31

TDQS

A3.9/5.0
Behavior5/5

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

Annotations only say this is a safe, idempotent, open-world read; the description adds the things that actually drive agent behavior — that a missing stack returns status failed with watch.done true and is not an error, that in_progress means Cyclone or Vortex is busy rather than attention, and that landGatePending and agents_idle blockers resolve to in_progress. It goes further and enumerates repair kinds (restack_conflict, seam_review_stuck, auto_land_off, vortex_findings) with instructions on what not to do, such as not patching a stuck seam and not changing a PR's GitHub base.

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 purpose is front-loaded, but everything after it is a single dense block of run-on sentences mixing polling semantics, blocker taxonomy, and repair instructions, with embedded quoted strings from server messages. Much of the content earns its place, but the lack of grouping or progressive disclosure makes it hard to scan and increases the chance an agent latches on the wrong clause.

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 complex blocking tool with no output schema, the description covers return values, status meanings, error-versus-normal outcomes, and multi-layer attention ordering well enough to call it correctly. The gap is input-side: four of five parameters go unexplained, so an agent must guess at cursor/resume fields like after_finished_at and enrolled_head_sha.

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?

With 0% schema description coverage the description has to carry all five parameters, and it only really does timeout_s (0 = single snapshot, 1-45 = wait window, default implied by the 45 cap). stack_id, bounce_id, after_finished_at, and enrolled_head_sha are never mentioned, and 'cursor' appears only as something carried across calls without saying which field it lives in.

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 opening sentence gives a specific verb and resource ('Wait for a stack to need attention') and immediately states the return envelope, so an agent knows this is a blocking attention-poll rather than a status read. It stops short of naming a sibling such as stack_status or stack_publish_status to say which to pick when you want a non-waiting snapshot.

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 spells out the polling contract precisely: timeout_s 0 is one snapshot, 1-45 blocks, either timeout status is not a failure, and the next call repeats with the same cursor. It also says to follow watch.next.args until watch.done and that background watching requires a confirmed host notification. What's missing is any explicit exclusion against siblings like review_wait or stack_status, so the when-not case is inferred rather than stated.

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