github-tools

Create a GitHub project board

github_project_create

Idempotent

Creates a GitHub project board for a user or organization, or reuses an existing one by title, and applies the standard template with Status, Start and Target fields plus Roadmap, Kanban and Backlog views.

Instructions

Create a project board for a user or organization, or reuse the open board of that owner and exact title (case-insensitive; several are invalid_argument), and bring it to the standard template. The title defaults to Roadmap. A board that has to be made is empty, or a copy of template without its draft items. With standard (the default): the fields Status (Todo, In Progress, Waiting, Done, Cancelled, each with a color and a description), Start and Target (dates), and the views Roadmap, Kanban and Backlog. On a board this call made, Status gets exactly those options, keeping the ids of GitHub's own Todo, In Progress and Done, and GitHub's default view View 1 is deleted once the three views exist. On a reused or copied board only the missing fields, options and views are added, and nothing is deleted. A reused board must be one the viewer may update. dates: "issue_fields" uses the organization's issue fields Start date and Target date as the board's dates, refused before the board is made when the owner is a user or lacks them. link_repo links the board to a repository (needs write permission there) unless it is already linked. GitHub links only boards of the repository's own owner, so a repository of another owner is invalid_argument, before the board is made. Once the board exists, a failed step does not fail the call: it is listed in errors and the board is still returned. notes lists what the API cannot do, such as setting the Roadmap view's date fields. Needs a token with the project scope; if GitHub reports missing scopes, run gh auth refresh -s project.

Input Schema

Name	Required	Description
`dates`	No	"board" (default) makes the board's own date fields Start and Target; "issue_fields" uses the organization's issue fields Start date and Target date instead, so an issue carries the same dates on every board and they are set with the issue tools (a pull request or draft has none). Organization boards only.
`owner`	Yes	The user or organization login that owns the board, or "@me".
`title`	No	The board's title (default Roadmap).
`standard`	No	Bring the board to the standard template: its fields and views (default true).
`template`	No	A board to copy, without its draft items, when the board has to be made: its number, owner/number or URL (a bare number or a title is looked up among owner's boards).
`link_repo`	No	owner/name of a repository to link the board to; needs write permission.

Output Schema

Name	Required	Description
`notes`	Yes	What still has to be done by hand.
`views`	Yes	The standard views, in order; created: false when the board already had one of that name.
`errors`	Yes	Failed steps (fields, views, default_view, link), keyed by step; {} when none.
`fields`	Yes	The standard fields, in order.
`linked`	Yes	owner/name of the repository the board is linked to; null when none was asked.
`created`	Yes	false when an open board of that owner and title was reused.
`project`	Yes
`copied_from`	Yes	owner/projects/N of the board that was copied; null when none was.
`deleted_default_view`	Yes	Whether View 1, GitHub's default view, was deleted; only on a board this call made.

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?

Beyond the annotations, it discloses reuse by exact title, deletion of GitHub's default View 1 on newly created boards, addition-only behavior on reused boards, partial success through an errors list, auth scope requirements, and pre-creation refusal cases. These are substantial behavioral details that materially affect correct invocation.

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 description front-loads creation/reuse behavior, but it is dense and contains awkward run-on phrasing such as "A board that has to be made is empty..." and "notes lists what the API cannot do." Most content is useful, but the structure makes it harder to scan than necessary.

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 complex create/reuse tool, it covers defaults, permissions, authentication scopes, invalid cases, and partial failures. Since an output schema exists, it does not need to explain return values, and no critical invocation information appears to be 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 meaningful semantics for title defaults, standard defaults, template copying, link_repo permissions, and the issue_fields refusal behavior for user-owned boards. It does not add much syntax beyond the schema, but it does explain parameter consequences.

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 states a specific verb and resource: create or reuse a GitHub project board for an owner, with an exact title and optional standard template. It makes the create/reuse semantics clear enough that an agent can distinguish this from project read, link, or field/view tools even though sibling names are not used.

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 explains when a board is created versus reused, default title and standard behavior, permission prerequisites, invalid_argument conditions, and partial-failure handling. It does not explicitly name sibling alternatives such as github_project_read or github_project_field_ensure, so it falls short of fully explicit alternative routing.

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