github-tools

Link GitHub pull requests into a stack

github_stack_link

Idempotent

Build a native stack of open pull requests bottom-to-top or add new ones on top of an existing stack, ensuring each PR’s base branch matches the head branch below it.

Instructions

Make a native stack of open pull requests of one repository, listed bottom to top, or put more of them on top of an existing stack. Each pull request's base branch must be the head branch of the one below it. It never changes a base or opens a pull request: github_pr_create and github_pr_edit do that, and a chain whose bases do not match is refused with the base to fix. An existing stack only grows on top: list its top pull request (or a longer run of its top, up to all of it) and then the new ones. It is idempotent: pull requests that are in the stack already change nothing and changed is false.

Input Schema

Name	Required	Description	Default
`prs`	Yes	The pull request numbers of the repository, bottom to top; at least 2 unless some are in a stack already, and at most 100. Each one's base branch is the head branch of the one before it.
`repo`	No	owner/name; defaults to the working tree's repository (its origin). Used for a bare number.

Output Schema

Name	Required	Description
`repo`	Yes
`added`	Yes	The pull requests this call put into the stack, bottom to top.
`stack`	Yes	The stack as GitHub holds it after the call, its pull requests bottom to top.
`changed`	Yes	False when the pull requests were in the stack already and nothing was sent.
`created`	Yes	Whether this call made the stack.
`foreign`	Yes

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?

Goes well beyond the annotations: adds the base/head chaining precondition, the refusal behavior with the offending base reported, the grow-only-on-top constraint, and confirms idempotency semantics with 'changed is false'. The annotations only declare non-read-only and idempotent; the description supplies the operational rules an agent needs.

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 the core action, then constraints, then alternatives, then append mechanics, then idempotency. Dense but nearly every clause carries information; a couple of sentences (the sibling references) are slightly parenthetical but justified by routing value.

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?

With an output schema present, return values need not be explained, and the description still covers preconditions, failure behavior, append-only semantics, and idempotency. Nothing an agent needs in order to call this two-parameter mutation correctly is missing.

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 100%, and the schema already documents ordering (bottom to top), the min/max item counts, the base/head relationship, and repo defaulting. The description restates ordering and the grow rule but adds no new syntax or format detail beyond that, so baseline 3 applies.

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 ('Make a native stack of open pull requests of one repository') and covers both create and append modes. It explicitly separates itself from github_pr_create and github_pr_edit, so an agent can route correctly without opening 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 Guidelines5/5

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

Gives explicit when-to-use (build a stack or extend one), when-not-to-use ('never changes a base or opens a pull request'), and names the alternatives that do those jobs. It also explains the append procedure (list the existing top PR or a run of them, then the new ones), leaving no inference needed.

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