github-tools

Edit a GitHub project item

github_project_item_edit

DestructiveIdempotent

Update GitHub project item fields in one validated call: set or clear values, and edit draft title/body or append text, skipping unchanged fields before any write.

Instructions

Change a project item in one call: field values (fields) and fields to empty (clear_fields), and, for a draft only, its title, body (replaces it) or append_body (adds after a blank line). A value an item already holds, and an empty field to clear, are skipped; if everything is in place nothing is written (changed: []). Everything is checked before the first write: a field in both fields and clear_fields, body with append_body, a blank title, draft text on an issue or pull request, an unknown field, option or iteration, a bad date and nothing to change are invalid_argument. A write that fails throws, and its message names what was written before it. An issue's or pull request's own title, body, assignees, labels and milestone are GitHub's, not the board's: github_issue_edit sets them on the issue. 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. An item is named by its node ID (PVTI_…), which also tells its board (a project given beside it must be that board), or by an issue or pull request (12, #12, owner/repo#12 or its URL) that is on the board the lookup finds. A draft can only be named by its ID. 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	Drafts only: the new body, which replaces the whole old one; empty clears it.
`item`	Yes	The board item: its node ID (PVTI_…), or an issue or pull request as 12, #12, owner/repo#12 or its URL, found on the board that project, owner and repo choose. A draft can only be named by its ID.
`repo`	No	owner/name; defaults to the working tree's repository (its origin). Where the board lookup starts, the owner of a bare board number, and the repository of a bare issue or pull request 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`	No	Drafts only: the new 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.
`append_body`	No	Drafts only: text added after the current body, set off by a blank line.
`clear_fields`	No	Names of the fields to empty. A column that mirrors an issue field is cleared with clear_issue_fields in github_issue_edit, not here.

Output Schema

Name	Required	Description
`changed`	Yes	What was written: field names as the board spells them, then title and body; [] when everything was already in place.
`item_id`	Yes
`project`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.7.0Nov 6, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the annotations (destructive=true, idempotent=true), it discloses skip-if-unchanged semantics with a changed: [] return, all-or-nothing validation before the first write, the full invalid_argument condition list, and throw behavior whose message names what was already written. That last detail is important context for a destructive, partially-failing mutation.

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 constraints are front-loaded, but the prose is dense and self-repeating: 'Everything is checked before the first write' and 'Every field and value is checked before anything is written' state the same thing, and issue-vs-board ownership is explained three times. Against a schema with 100% description coverage, the text is oversized.

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 9-parameter destructive mutation, it covers what an agent needs: naming conventions for item and project, lookup order, validation/error semantics, idempotency, and auth requirements. An output schema exists, so the description does not need to document return values.

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 schema already carries most parameter meaning, but the description still adds value: case-insensitive field-name and option matching, value typing per field kind, @current resolving to the UTC iteration containing today, and the board lookup fallback chain (owner's boards, else repo-linked, else organization, else viewer) with Roadmap as default.

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 opening sentence names a specific verb and resource ('Change a project item') and enumerates the exact surface it touches: field values, clear_fields, and draft-only title/body/append_body. It also explicitly distinguishes itself from sibling tools, stating that an issue's own title, body, assignees, labels and milestone belong to github_issue_edit rather than the board.

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?

It gives explicit routing rules: use this tool for board fields, use github_issue_edit for the issue's own metadata, and use issue_fields / clear_issue_fields for columns that mirror issue fields. It also names the preconditions (project-scoped token, gh auth refresh -s project) an agent needs before calling.

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