Skip to main content
Glama
mergestorm-mcp

mergestorm-mcp

Official

Start Vortex review

review_start_pr

Start a Vortex review of an open GitHub pull request at its current head, then read findings with review_wait_pr. Launch a review and avoid duplicate runs at the same head.

Instructions

Start a Vortex review of an open GitHub pull request on the user's account, at its current head. head_sha, when given, must still be the head; otherwise nothing starts and the answer names the live head. Uses one standard credit. Findings post on the pull request; read them with review_wait_pr. A review already running at that head is reported, not started twice. When the result names a background task, its result also arrives through that task when the work finishes.

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_start_pr"
  }
}

Input Schema

NameRequiredDescriptionDefault
repoYes
ownerYes
head_shaNo
pr_numberYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.31

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description discloses cost ('uses one standard credit'), side effect location ('findings post on the pull request'), a dedup rule (an already-running review at that head is reported, not started twice), a failure mode (stale head_sha aborts and names the live head), and async delivery via a background task. These are exactly the behaviors an agent needs and none are inferable from the structured fields.

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

Conciseness5/5

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

Six short sentences, front-loaded with the action and scope, then the precondition, then cost, then where results land and which tool reads them. Every sentence contributes a distinct fact; there is no restatement of the name or title.

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 mutating, credit-consuming, asynchronous tool with no output schema and no annotations covering cost or async behavior, the description covers the essential unknowns: cost, dedup, stale-sha failure, result location, and background-task delivery. It does not describe what the returned payload looks like or what auth scope is required, but the pointer to review_wait_pr and to the background task largely covers the return path.

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 carries the burden. It fully explains the only non-obvious parameter, head_sha: optional, must still match the live head, and what happens when it does not. owner, repo, and pr_number are conventional GitHub identifiers left to their names and schema constraints (minLength, minimum, pattern), which is a minor but real gap.

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 (start), a named resource (a Vortex review of an open GitHub pull request), and a scope qualifier (at its current head, on the user's account). It also names the paired read tool (review_wait_pr), so an agent can separate starting a review from retrieving its findings without opening either schema.

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?

Usage is clearly implied: call this to kick off a review, then use review_wait_pr to read findings. The head_sha precondition is stated as a when-to/when-not rule (stale sha means nothing starts and the live head is returned). It stops short of explicitly ruling out adjacent siblings such as review_list, review_stop_pr, or review_submit.

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