github-tools

Ensure a GitHub project field

github_project_field_ensure

Idempotent

Create a missing project board field or append missing single-select options while keeping existing option ids and order, so board columns match the workflow you need.

Instructions

Make sure a field exists on a project board the viewer may update, without ever making a second one: a missing field is created, and the missing options of an existing single select are appended after its own, which keep their id, name, color, description and order, so nothing already set moves. A new single_select field needs options. Status can be extended but not created. A field of that name with another type, options on a field that is not single_select, a repeated option name and a color GitHub does not list are invalid_argument, before anything is written. With issue_field: true (organization boards only) the column mirrors the organization's issue field of that name, such as Priority, Start date or Target date; it is added when the board lacks it, and a field of the board's own with that name is invalid_argument. 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
`name`	Yes	The field's name, matched without regard to case.
`repo`	No	owner/name; defaults to the working tree's repository (its origin). Where the board lookup starts, and the owner of a bare board number.
`type`	No	The field's type; a field of that name with another type is invalid_argument. Required unless issue_field is true, where it only checks the issue field's type.
`owner`	No	A user or organization login, or "@me": the owner of a numbered board, else the only owner searched for a title.
`options`	No	single_select only, not with issue_field: Name, Name:COLOR or Name:COLOR:Description (the description is everything after the second colon). COLOR is one of GRAY, BLUE, GREEN, YELLOW, ORANGE, RED, PINK, PURPLE, in any case; the default is GRAY.
`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.
`issue_field`	No	Add a column that mirrors the organization's issue field of that name instead of a field of the board's own; its options and values are the organization's and the issue's.

Output Schema

Name	Required	Description
`field`	Yes	The field as it is now, with its options in order.
`created`	Yes	Whether this call made the field.
`project`	Yes
`added_options`	Yes	The names of the options this call added; [] when none.

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?

Annotations only say not-read-only, idempotent, non-destructive, open-world; the description adds what actually matters: existing options keep id, name, color, description and order so "nothing already set moves", and validation happens "before anything is written". It also discloses the auth prerequisite (project scope, gh auth refresh -s project), which is exactly the kind of operational context annotations cannot carry.

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 lead sentence is well front-loaded and no sentence is filler, but the remainder is a chain of very long semicolon-and-comma clauses (the project-resolution sentence alone runs several lines), making it hard to parse on a single pass. Dense but not disciplined.

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 seven-parameter mutating, open-world tool, the description covers creation rules, extension rules, validation failures, the organization issue_field mirror, board resolution order, the Roadmap default and the token scope requirement. An output schema exists, so return values need not be described.

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; the prose goes further by describing the interaction between project/owner/repo (a bare number takes owner, else the owner of repo or the working tree; a title is looked up among open boards, never guessed) rather than documenting each parameter in isolation. The type/issue_field dependency and the single_select-only restriction on options are also restated as constraints, not just field docs.

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?

"Make sure a field exists on a project board... without ever making a second one" states a specific verb-and-resource plus the ensure semantics (create-or-extend) that separates it from github_project_view_ensure, github_project_create and the item_* siblings. It immediately names both branches: a missing field is created, existing single-select options are appended.

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 concrete when/when-not rules: "A new single_select field needs options", "Status can be extended but not created", and the four conditions that are invalid_argument before anything is written. The issue_field branch is scoped to organization boards and forbids a board-local field of the same name. It never names a sibling tool as the alternative path, which keeps it 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.