github-tools

Merge a GitHub pull request

github_pr_merge

Destructive

Merge a pull request with merge, squash, or rebase, checking a reviewed head SHA and handling stacked layers so merges match reviewed commits.

Instructions

Merge a pull request with merge, squash or rebase. Every pull request, stacked or not, merges through one GitHub request that this call follows until it ends. method may be left out when the repository allows only one; when it allows several, or the one asked is not allowed, the call fails saying which are. Pass head_sha, the commit that was reviewed, to merge only that: if new commits arrived the call fails with stale and merges nothing. The head merged is always the one read at the start. subject and body set the merge or squash commit's title and message; a rebase makes no merge commit, so they are refused with it. A closed pull request, a draft and one with conflicts are refused before anything is sent, and so is a merged one: it is left as it is, changed is false and nothing else merges. Whether the branch rules and required checks are met is GitHub's to enforce: a pull request they block, or one that is behind its base or unstable, is sent anyway and GitHub's refusal is returned. Nothing bypasses the rules, and a repository that requires a merge queue queues it (status enqueued). In a native stack, merging a layer also merges every open layer below it, each as its own commit, while the layers above stay open and GitHub retargets them. That is refused, listing the layers below, unless with_lower_layers is true; a lower layer that is a draft or in conflict is refused by name. subject and body apply to the named layer only. The call waits up to 45 seconds, reading the request every 3. If GitHub is still merging then, status is pending with a note: read the pull request later with github_pr_read view. The result lists the pull request and the layers taken along as read after the merge. delete_branch deletes the head branch of each pull request that merged, bottom to top, best effort and never failing the call: the default branch, a branch another open pull request is based on, one in a fork and one with new commits since the merge are kept, and branches reports each result. Merging closes the issues the pull request names, in other repositories too. A pull request is 12, #12, owner/repo#12 or its URL; a bare number means the working tree's repository, or repo.

Input Schema

Name	Required	Description
`pr`	Yes	The pull request, as 12, #12, owner/repo#12 or its URL.
`body`	No	The merge or squash commit's message. Not for rebase. For a stacked merge it applies to the named pull request only.
`repo`	No	owner/name; defaults to the working tree's repository (its origin). Used for a bare number.
`method`	No	How to merge: merge, squash or rebase. Optional when the repository allows only one; required when it allows several.
`subject`	No	The merge or squash commit's title. Not for rebase. For a stacked merge it applies to the named pull request only.
`head_sha`	No	Optional 40-character commit SHA the pull request was reviewed at. Fails with stale, merging nothing, if new commits arrived.
`delete_branch`	No	Delete the head branch of each pull request that merged, best effort (default false).
`with_lower_layers`	No	For a pull request in a stack: also merge the open layers below it, which merging it does anyway (default false: refuse and list them).

Output Schema

Name	Required	Description
`pr`	Yes
`repo`	Yes
`notes`	Yes	What to know about the result; [] when nothing.
`errors`	Yes	Failed steps, keyed by step (fields.<Field name>, blocked_by, kind, labels, milestone); {} when none.
`merged`	Yes	The pull request and the open layers below it that the merge took along, bottom to top, as read after.
`method`	Yes	The method of the merge request; null when the pull request was merged already and none was asked.
`status`	Yes	merged; enqueued: in the merge queue; pending: GitHub is still merging when the wait ended; failed: GitHub could not merge it.
`changed`	Yes	False when the pull request was merged already and nothing was sent.
`foreign`	Yes
`request`	Yes	GitHub's ID of the merge request; null when none was made.
`branches`	Yes	What became of each head branch; [] without delete_branch.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.7.0Nov 6, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already flag destructive, non-idempotent, open-world, but the description adds substantial context beyond them: what gets refused before any request, that GitHub's branch rules and required checks are enforced rather than bypassed, merge-queue enqueue behavior, the 45-second wait with 3-second polling and the pending status, and the best-effort branch deletion keep rules (default branch, base of another open PR, fork, new commits).

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?

The text is front-loaded with the core action and method choice, and nearly every sentence carries operational information. It is dense and long for a single paragraph, with some clauses (stack retargeting, issue closing across repositories) that could be split or trimmed, but nothing is truly wasted.

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?

For a destructive, asynchronous, stack-aware merge tool this covers the refusal set, the wait/pending path, stacked-layer behavior and branch cleanup, so an agent can call it and interpret outcomes correctly. With an output schema present, it correctly does not need to fully specify the returned shape.

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 coverage is 100%, so the schema already documents each parameter; the description nonetheless adds real meaning, such as the failure mode when method is omitted or disallowed ('fails saying which are'), the stale semantics of head_sha, and that subject/body are refused with rebase and apply only to the named layer in a stack.

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 description opens with a specific verb and resource ('Merge a pull request') and immediately names the three merge methods. It is clearly distinct from siblings such as github_pr_close, github_pr_ready and github_pr_read, which handle opposite or adjacent lifecycles.

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 gives explicit conditions and alternatives in places: leave out method when only one is allowed, and use 'github_pr_read view' later if the merge is still pending. It also enumerates refusal cases (closed, draft, conflicts, already merged). What is missing is routing to siblings like github_pr_close for non-merge outcomes.

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