Skip to main content
Glama
mergestorm-mcp

mergestorm-mcp

Official

Wait for issue review

issue_review_wait
Read-onlyIdempotent

Wait for the next Vortex review verdict on a GitHub issue and return its state, round, points, summary, and next action so you know whether to answer feedback or open the pull request.

Instructions

Wait for the next Vortex verdict on a GitHub issue. Returns the review state (approved, needs_answers, pending, unreviewed or off), the round, the verdict, the summary, up to 8 points, the review comment link, next (one sentence saying what to do), wait.status and, while there is more to wait for, next_args. wait.status is answered_waiting_for_round (Vortex has an answer after the last verdict and the next round has not finished; with wait.reason answer_not_seen Vortex has no answer after the verdict yet, so post yours), round_running, points (a verdict with points to answer), approved (approved, off, a failed review, the round cap, or unreviewed on a mention-mode repo) or stalled (no round started: about 10 minutes after a queued answer, at once when an answer failed or was skipped without starting a round, about 2 minutes into the wait when no review has started at all (wait.reason no_review_started), or about 10 minutes after the verdict with no answer seen once the wait is at least 2 minutes old; wait.reason says why). timeout_s: 0 reads it once; otherwise it waits for one slice of up to 45s (the default). Call it again with exactly next_args: after_round is the round whose verdict you already saw, so the stale verdict is never returned again, and waiting_since carries the stall clock across slices. Open the pull request only on approved, or when the summary says the issue needs no approval (issue reviews off, or unreviewed on a mention-mode repo). On points, answer in ONE new comment on the issue as the author or a maintainer: for each blocking point, accept its suggested fix or say why not (notes do not block). On a mention-mode repo the comment must tag @mergestorm-vortex and the next round starts at once; on an auto-mode repo it starts about 90s later. Editing the body or an earlier comment starts nothing. Then call once with next_args. On stalled, follow the summary's advice for wait.reason and do not loop on this tool. Never poll GitHub or loop on this tool beyond next_args. A person can also approve with an issue comment whose first line is mergestorm-issue: approve.

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": {
      "owner": "<owner>",
      "repo": "<repo>",
      "number": "<number>"
    },
    "name": "issue_review_wait"
  }
}

Input Schema

NameRequiredDescriptionDefault
repoYes
ownerYes
numberYes
timeout_sNo
after_roundNo
waiting_sinceNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.31

TDQS

A4.3/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds substantial value beyond that: the full enumerated set of wait.status outcomes, concrete stall timings (~2 minutes, ~10 minutes, ~90s round start), and the slicing model where each call waits up to 45s. A 3 reflects that this is good added context layered on top of annotations that already carry the safety semantics, not a case where the description had to do all the work alone.

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 content is dense but the structure is poor: nearly everything is packed into long run-on sentences with parenthetical enumerations, and the wait.status taxonomy in particular is hard to parse on a single read. Most sentences do earn their place informationally, but the presentation makes an agent work to extract the decision rules.

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 has to explain the return payload, and it does in detail: state, round, verdict, summary, up to 8 points, review comment link, next, wait.status, wait.reason and next_args. Combined with the per-state handling instructions, an agent has everything needed to call it correctly and act on the result.

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?

Schema description coverage is 0%, so the description must carry the parameter burden, and it largely does: timeout_s is explained ('0 reads it once; otherwise it waits for one slice of up to 45s (the default)'), after_round is explained as the round whose verdict was already seen so the stale verdict is not returned, and waiting_since is explained as carrying the stall clock. owner, repo and number are not described, but they are self-evident issue identifiers, so the gap is minor.

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?

The opening sentence gives a specific verb and resource: 'Wait for the next Vortex verdict on a GitHub issue.' The phrase 'on a GitHub issue' distinguishes it from the sibling review_wait_pr, which handles pull requests, so an agent can pick the right tool without opening a 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?

It is explicit about when to call, what to do on each verdict, when to open the pull request ('only on approved, or when the summary says the issue needs no approval'), and how to answer points. It also gives negative guidance ('do not loop on this tool', 'Never poll GitHub', 'Editing the body or an earlier comment starts nothing'), which is exactly the when-not-to guidance that prevents bad agent behavior.

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