Skip to main content
Glama
mergestorm-mcp

mergestorm-mcp

Official

Wait for GitHub PR Vortex review

review_wait_pr
Read-onlyIdempotent

Wait for and read a Vortex review pass on a GitHub pull request from the DB-only endpoint, polling by head SHA and pass until available, timed out, or absent.

Instructions

Read the Vortex pass on a GitHub PR from the DB-only endpoint; review identity is head SHA + pass. timeout_s: 0 reads it once without polling; otherwise it polls for one 45s slice by default (max 300) and returns in_progress on timeout so you can call again, or none when no review exists for that PR and head yet (call once more; if it is none again, Vortex is not reviewing that head: comment @mergestorm-vortex review on the PR, run mg review, or push a new commit). Pass after_sha for the head you pushed and pass to read one exact attempt; when you already hold a resting envelope for that head, also pass after_pass set to its pass and keep it unchanged across retries; never replace it with the pass of an in-progress envelope, and omit after_pass for a head you hold no envelope for. With timeout_s: 0, a pass that does not exist yet returns not_found, so after a push use a positive timeout. Do not pass 300; hosts drop long MCP calls. On rate_limited, wait retry_after_seconds before trying again. After a resting pass, verify each finding; prefer the smallest correct patch; if you skip, post a PR comment starting with mergestorm-loop: dismiss.

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>",
      "pr_number": "<pr_number>"
    },
    "name": "review_wait_pr"
  }
}

Input Schema

NameRequiredDescriptionDefault
passNo
repoYes
ownerYes
after_shaNo
pr_numberYes
timeout_sNo
after_passNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.31

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, yet the description still adds substantial behavior: a 45s polling slice with a 300 max, the in_progress/none/not_found/rate_limited return states, and retry_after_seconds. The only real gap is that 'DB-only endpoint' implies staleness/consistency semantics without spelling out the delay an agent should expect.

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 core purpose and the timeout/after_pass rules are front-loaded and every clause is informative, but it is one long semicolon-chained block with no structural breaks, making the parameter rules hard to scan. The closing remediation advice (verify findings, smallest patch, mergestorm-loop: dismiss comment) is workflow guidance beyond this tool's scope and dilutes the read.

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 7-parameter polling tool with no output schema, the description enumerates the possible result states and their follow-up actions, so an agent can drive the retry loop correctly. Completeness is only slightly short of ideal because the returned envelope's finding shape and the DB-only staleness window are left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden and does: timeout_s (0 = read once, positive = poll one 45s slice, max 300, avoid 300), after_sha (the head you pushed), pass (one exact attempt), and after_pass (used only with a resting envelope, kept constant across retries, never set from an in-progress envelope). Only owner/repo/pr_number go unmentioned, and they are self-evident.

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 ('Read the Vortex pass on a GitHub PR from the DB-only endpoint') plus the identity model (head SHA + pass), which is exactly what an agent needs to know. The GitHub-PR framing also implicitly separates it from the issue/stack review wait siblings.

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 explicit when-to-use branching: timeout_s 0 for a single read, positive timeout after a push, call again on in_progress, call once more on none, and then a concrete escalation ladder (comment @mergestorm-vortex review, mg review, or push a commit) if none repeats. It also names failure handling for rate_limited and warns against timeout_s=300.

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