github-tools

Edit a GitHub pull request

github_pr_edit

DestructiveIdempotent

Change pull request details in one call: title, body, base branch, labels, assignees, reviewers, milestone, and closing issues.

Instructions

Change a pull request in one call: title, body (body replaces it, append_body adds after a blank line), base branch (not for a merged pull request), labels, assignees and reviewers to add or remove (added assignees and reviewers are notified), milestone or remove_milestone, and the issues it closes (add_closes adds a Closes #12 line to the body, remove_closes removes such lines). A milestone that does not exist is an error. Needs write permission on the repository. append_body goes before the closing lines (Closes #12) the body ends with, so those stay the last lines. After closing issues change, the call waits up to a few seconds for GitHub to link them, then lists closing_issues as GitHub links them and notes say when one is not linked (a pull request into a branch other than the default branch links none; otherwise it may link it a moment later) or is still linked (another form of mention in the body or a commit message). A pull request is 12, #12, owner/repo#12 or its URL; a bare number means the working tree's repository, or repo. Attachments are images (png, jpg, gif, webp, svg, up to 10 MiB) and videos (mp4, mov, webm, up to 100 MiB), up to 50, uploaded with the text: a body reference like ![alt](./shot.png) becomes the uploaded file and the others are appended; they need gh 2.99 or newer, and a file that fails to upload is listed under errors.attachments while the rest goes through.

Input Schema

Name	Required	Description
`pr`	Yes	The pull request, as 12, #12, owner/repo#12 or its URL.
`base`	No	The branch of the repository to merge into; not for a merged pull request.
`body`	No	The new body, which replaces the whole old one; empty clears it.
`repo`	No	owner/name; defaults to the working tree's repository (its origin). Used for a bare number.
`title`	No	The new title.
`milestone`	No	A milestone title to set; it must exist.
`add_closes`	No	Issues to close when it merges, in the same forms as closes: a `Closes #12` line is added to the end of the body unless the body has one already.
`add_labels`	No	Labels to add; they must exist.
`append_body`	No	Text added after the current body, set off by a blank line.
`attachments`	No	Images and videos to upload with the text.
`add_assignees`	No	Logins, or "@me".
`add_reviewers`	No	Logins, or org/team, to request a review from; they are notified.
`remove_closes`	No	Issues to stop closing: the body's lines that are only a closing keyword and that issue are removed. A mention in a sentence or a commit message is left as it is, so the issue can stay linked.
`remove_labels`	No
`remove_assignees`	No
`remove_milestone`	No	Take the pull request out of its milestone.
`remove_reviewers`	No

Output Schema

Name	Required	Description
`pr`	Yes
`url`	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.
`changed`	Yes	The arguments that were applied.
`foreign`	Yes
`milestone`	Yes	The milestone that was set; null when none was set or it was removed.
`attachments`	Yes	The files that were sent; [] when none were given.
`closing_issues`	No	The issues GitHub links as closed by the pull request now; only when add_closes or remove_closes was given.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.7.0Nov 6, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Despite annotations already covering destructive/idempotent/openWorld, the description adds substantial beyond-schema behavior: added assignees and reviewers are notified, body fully replaces while append_body inserts before the trailing closing lines, the call waits a few seconds for GitHub to link closing issues and can report one as unlinked or still linked via another mention, and partial attachment failures land in errors.attachments while the rest proceeds.

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 volume is defensible for a 17-parameter tool, but it is delivered as one long run-on paragraph with stacked parentheticals, so the high-value facts (replacement vs append, notification, waiting/linking) are hard to scan. Some material, such as the PR-reference forms, merely restates schema text.

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?

An output schema exists, yet the description still usefully explains the closing_issues/notes return behavior and the partial-failure errors.attachments path, and it covers permissions, error cases and all major field interactions. What is missing is disambiguation against the many sibling PR mutation tools and a resolution of the ambiguous closings/"closes" wording.

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 82%, so the baseline is 3, and the description still adds meaning: body vs append_body ordering semantics, the same-form grammar for PR references, reviewer notification, remove_closes only stripping standalone closing lines, and attachment upload rules (types, sizes, 50 cap, reference-vs-append). The one weak spot is a dangling reference to a "closes" field that does not exist in the schema, forcing the agent to infer it means the add_closes/remove_closes pair.

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 ("Change a pull request in one call") and immediately enumerates the editable surfaces: title, body/append_body, base, labels, assignees/reviewers, milestone, closing issues, attachments. That enumeration cleanly separates it from sibling mutations such as github_pr_create, github_pr_close, github_pr_merge and github_issue_edit without needing to open 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 Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states real preconditions ("Needs write permission on the repository", "A milestone that does not exist is an error", base "not for a merged pull request", attachments "need gh 2.99 or newer") plus per-field usage rules like add_closes skipping a body that already has the line. It never names an alternative sibling or an explicit when-not-to-use-this routing rule, so it falls short of a 5.

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