gitlab-mcp

gitlab_mr_update

Update a merge request's title, description, labels, assignee, milestone, or state. Set or clear draft status, change target branch, or toggle squash and discussion lock.

Instructions

Update a merge request. Pass draft to set or clear the "WIP: " prefix (when no title is given the current title is read first). labels:[] clears all labels and assignee_id:0 unassigns - omitting a field leaves it alone.

Input Schema

TableJSON Schema

Name	Required	Description
`iid`	Yes	project-scoped internal id - the number in !123 for a merge request or #123 for an issue, not the global id
`draft`	No	set or clear the "WIP: " title prefix
`title`	No
`labels`	No	replaces the whole label set; [] clears it
`squash`	No
`project`	Yes	project id ('42') or full path ('group/subgroup/app'); a path is URL-encoded for you
`assignee_id`	No	assignee numeric user id (find it with gitlab_users_search); 0 unassigns
`description`	No
`state_event`	No	close or reopen the merge request
`milestone_id`	No	0 unassigns
`target_branch`	No	branch name, e.g. feature/login
`discussion_locked`	No	when locked, only project members can comment or resolve
`remove_source_branch`	No

Output Schema

TableJSON Schema

Name	Required	Description
`id`	No
`iid`	No	internal id - the number in !123
`sha`	No	HEAD of the source branch
`state`	No	opened / closed / locked / merged
`title`	No
`author`	No	user reference
`labels`	No
`web_url`	No
`assignee`	No	user reference
`milestone`	No
`project_id`	No
`description`	No
`merge_status`	No	'can_be_merged' / 'cannot_be_merged' / 'unchecked'. A merged merge request on 11.3 still reports can_be_merged, so read state first - merge_status alone is not a green light
`changes_count`	No	a string on 11.3, not a number
`has_conflicts`	No	not sent by 11.3; compare merge_status instead
`source_branch`	No
`target_branch`	No
`merge_commit_sha`	No
`user_notes_count`	No
`work_in_progress`	No	11.3 marks a draft MR this way; the title carries a "WIP: " prefix. Verified present on every one of 100 merge requests on the live instance

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Oct 5, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Annotations only supply readOnlyHint=false, so the description carries most of the burden and does well: it discloses patch semantics, sentinel values (labels:[] clears, assignee_id:0 unassigns), and the non-obvious draft/title read-then-write interaction. It omits permission requirements and any indication of what the response returns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences with no filler. The core update purpose and the most surprising interaction (draft/title) are front-loaded, and the sentinel rules follow compactly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter mutation tool with an output schema, the description covers the risky, non-obvious behavior (patch semantics, sentinel values, draft/title coupling). Return values need no explanation given the output schema; only auth/permission expectations are unaddressed.

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 69%, and the description adds genuine meaning beyond it: the 'omitting a field leaves it alone' patch contract and the draft-with-no-title read-first behavior are not in the schema. Sentinel semantics for labels/assignee_id largely restate schema descriptions, so it is not a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Update a merge request'), which distinguishes it cleanly from siblings like gitlab_mr_create, gitlab_mr_merge, and gitlab_mr_get. It does not, however, explicitly name those siblings or delimit scope against them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: the tool is for modifying an existing MR, and the description clarifies patch semantics ('omitting a field leaves it alone'). There is no explicit when-to-use/when-not or routing to gitlab_mr_merge for state transitions versus state_event here.

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