github-tools

Unlink a GitHub project from a repository

github_project_unlink

Idempotent

Unlink a GitHub project board from a repository without deleting board data; the board remains unchanged if not linked, and required project and repository permissions are checked.

Instructions

Unlink a project board from a repository. The viewer must be able to update the board and write to the repository; a board that is not linked is left as it is (changed: false). Nothing on the board is deleted. A board is named by project: its number, owner/number or its URL, used as it is; any other project is a title, and no project is Roadmap: the open board of that whole title is looked up, never guessed, in owner's boards if owner is given, else in the boards linked to repo, then its organization's, then the viewer's. Needs a token with the project scope; if GitHub reports missing scopes, run gh auth refresh -s project.

Input Schema

Name	Required	Description
`repo`	No	owner/name of the repository to link or unlink; defaults to the working tree's repository (its origin). Also where the board lookup starts.
`owner`	No	A user or organization login, or "@me": the owner of a numbered board, else the only owner searched for a title.
`project`	No	The board, as its number, owner/number or its URL (used as it is; a bare number takes owner, else the owner of repo or of the working tree's repository), or as its title, looked up among open boards (whole title, case-insensitive). Default: the title Roadmap.

Output Schema

Name	Required	Description
`repo`	Yes	owner/name of the repository.
`changed`	Yes	false when the board was already in the wanted state.
`project`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.7.0Nov 6, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Goes well beyond the annotations: it discloses that nothing on the board is deleted, that an already-unlinked board returns changed: false, the required token scope ('project'), and a concrete remediation ('gh auth refresh -s project'). That is exactly the context an agent needs for a permission-gated mutation that annotations flag as non-destructive and idempotent.

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 purpose is front-loaded, but the remainder is a single dense run-on with nested clauses ('used as it is; any other project is a title, and no project is Roadmap: the open board of that whole title is looked up...') that forces re-reading. The content earns its place; the sentence structure does not.

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?

An output schema exists, so return values need no explanation, and the description still covers preconditions, idempotent no-op semantics, non-destructiveness, lookup fallback order and auth remediation. Nothing an agent needs in order to call this correctly is missing.

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 baseline is 3, but the description adds a resolution order that the schema only sketches: a board is an owner/number or URL used verbatim, otherwise treated as a title, with lookup in owner's boards, then the repo's linked boards, then the organization's, then the viewer's. That precedence chain is genuine added meaning for the 'project' parameter.

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?

Opens with a specific verb and resource ('Unlink a project board from a repository'), which is immediately distinguishable from the sibling github_project_link without opening the schema. The scope of the operation (board-to-repo association only) is unambiguous.

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?

States the preconditions for use ('viewer must be able to update the board and write to the repository') and what happens when the precondition is moot ('a board that is not linked is left as it is'). It does not explicitly name github_project_link as the inverse alternative, so the when-to-use routing is implied rather than stated.

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