github-tools

Create a draft item on a GitHub project

github_project_item_create

Create a GitHub project board draft with a title and body, then set its field values in one call; convert it to an issue later.

Instructions

Create a draft item (a title and a body that live only on the board, with no repository, labels or milestone) on a project board the viewer may update, and set field values in the same call. github_project_item_convert turns a draft into an issue. With no Status given the draft starts as Todo when the board has a Status single select with that option. Once the draft exists, a field that fails to set does not fail the call: it is listed in errors as fields., and the item is still returned. Field values are set by field name and option or iteration name, matched without regard to case: text as a string, number as a number or numeric string, date as YYYY-MM-DD, single select as an option name, iteration as an iteration title or @current (the iteration containing today, UTC). Only text, number, date, single select and iteration fields can be set; a column that mirrors an issue field is set with the issue tools' issue_fields, not here. GitHub's own (Title, Assignees, Labels, Milestone, Repository, Linked pull requests, …) are set on the issue, and github_issue_edit sets assignees, labels and milestone. Every field and value is checked before anything is written. 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
`body`	No	Markdown body; empty when left out.
`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.
`owner`	No	A user or organization login, or "@me": the owner of a numbered board, else the only owner searched for a title.
`title`	Yes	The draft's title.
`fields`	No	Field values to set, by field name: {"Status": "Todo", "Target": "2026-12-01"}. Values are text, a number, a YYYY-MM-DD date, an option name or an iteration title (@current is the one containing today). A column that mirrors an issue field is set with the issue tools' issue_fields, not here.
`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
`errors`	Yes	Failed steps, keyed by step (fields.<Field name>, blocked_by, kind, labels, milestone); {} when none.
`fields`	Yes	The values that were set, by field name as the board spells it: an option or iteration by its name, a number as a number.
`item_id`	Yes	The project item's node ID (PVTI_…).
`project`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.7.0Nov 6, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Goes well beyond annotations: default Status becomes Todo when that option exists, field-set failures are non-fatal and reported as errors keyed by fields.<Field name> while the item is still returned, and all field values are validated before anything is written. It also documents the project resolution order and the gh auth refresh -s project remedy. Nothing here contradicts readOnlyHint=false or destructiveHint=false.

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 core action is front-loaded, but the body is a dense run-on block of semicolon-chained clauses covering defaults, error semantics, type coercion, lookup order, and auth in one paragraph. The information earns its place, but the lack of any structure makes it harder to scan than it needs to be.

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 non-idempotent, open-world mutation with nested field objects, the description covers defaults, partial-failure behavior, validation timing, auth requirements, and project disambiguation; an output schema exists, so return values need no further explanation.

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 real semantics: case-insensitive matching of field and option names, @current meaning the iteration containing today in UTC, dates as YYYY-MM-DD, and the full project lookup chain (number/owner-number/URL as-is, otherwise a title searched in owner's boards, then repo-linked, then org, then viewer's, defaulting to Roadmap).

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 ('Create a draft item ... on a project board') and immediately defines what a draft is (title and body living only on the board, no repository, labels or milestone), which cleanly separates it from github_project_item_add and other siblings. It also names the follow-on tool, github_project_item_convert.

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?

Explicitly routes to alternatives: github_project_item_convert for turning a draft into an issue, github_issue_edit for assignees/labels/milestone, and issue_fields for columns that mirror issue fields. It also states the precondition — the viewer must be able to update the board — and the required token scope.

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