Skip to main content
Glama
mergestorm-mcp

mergestorm-mcp

Official

Open GitHub issue

issue_create

Create a GitHub issue without GitHub credentials: the Surge App files it and names you in the body, so you can open the pull request it is required for.

Instructions

Open a GitHub issue through Mergestorm with no GitHub credentials: the Surge App creates it and names you in the body. Use it for the issue a pull request must have before it is opened, then put Fixes # in the commit or pull request body. Defaults to the origin repository of cwd; pass owner and repo together to name another. labels must already exist on the repository; an unknown one is refused with unknown_label and nothing is created. Calling it again with the same title returns the open issue it already made (created: false) when that issue is among the newest 100 open issues of the repository; an older one, or two calls at the same time, can still create a duplicate, so check the returned number before retrying after a lost response. Needs write access to the repository through your linked GitHub account and Surge installed on it. After creating it, call issue_review_wait with the returned number and do not open a pull request until the issue is approved: reply once in an issue comment, accepting each blocking point's suggested fix or saying why not (notes do not block; Vortex re-checks the blocking points once and approves), then call issue_review_wait again.

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": {
      "title": "<title>"
    },
    "name": "issue_create"
  }
}

Input Schema

NameRequiredDescriptionDefault
cwdNo
bodyNo
repoNo
ownerNo
titleYes
labelsNo

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?

Goes well beyond the annotations: labels must pre-exist or the call is refused with unknown_label and nothing is created, repeat calls with the same title return the existing issue with created: false only if it is among the newest 100 open issues, concurrent calls can duplicate, and write access plus Surge installation are prerequisites. This is precisely the side-effect, failure-mode, and idempotency detail the annotations cannot convey.

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

Conciseness4/5

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

Front-loads purpose and repository defaults before failure modes and the review workflow, and nearly every sentence carries actionable information. It is nevertheless a dense single paragraph where the review-reply protocol could be compressed or delegated to issue_review_wait.

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?

Although there is no output schema, the description discloses the meaningful return values (the created flag and the issue number) and how to use them before retrying. For a mutating, non-idempotent tool with prerequisites, the description covers outcomes, errors, and required follow-up.

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?

Schema description coverage is 0%, so the description must carry the load; it does explain cwd (defaults to the origin repository of cwd), the owner/repo pairing rule, title's role in deduplication, and the labels constraint. It leaves body mostly unexplained (its purpose, that Fixes #<number> belongs in the commit or PR body rather than here) and says nothing about limits on labels or title.

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 ('Open a GitHub issue through Mergestorm'), plus the distinctive mechanism (Surge App creates it and names you, no GitHub credentials needed). It is clearly separable from the sibling issue_review_wait, which it explicitly names as the downstream step.

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 ('the issue a pull request must have before it is opened'), the required follow-up sequence with issue_review_wait, and the exact reply protocol for approval. It also documents when not to proceed: do not open a pull request until the issue is approved.

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