gitlab-mcp

gitlab_mr_comment_on_line

Post a review comment on a specific line of a merge request diff; invalid stale SHAs or lines outside the diff are rejected, and the discussion_id lets you reply in the same thread.

Instructions

Comment on one line of the merge request diff, as a normal review comment. Give the path exactly as gitlab_mr_changes reports it and the line number in that side of the file. The required base/start/head SHAs and the old-side line number are resolved from the merge request's latest diff version, so a stale SHA or a line that is not in the diff is reported instead of being sent. The result carries discussion_id - pass it to gitlab_mr_reply to continue the thread.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`iid`	Yes	project-scoped internal id - the number in !123 for a merge request or #123 for an issue, not the global id
`body`	Yes	comment text (GitLab Flavored Markdown)
`line`	Yes	1-based line number in the file
`path`	Yes	repository-relative file path, e.g. 'src/app.ts' (no leading slash)
`side`	No	'new' = the file after the change (added and unchanged lines), 'old' = the file before it (removed and unchanged lines)	new
`project`	Yes	project id ('42') or full path ('group/subgroup/app'); a path is URL-encoded for you

Output Schema

TableJSON Schema

Name	Required	Description
`note_id`	No
`web_url`	No
`position`	No	diff position; a GitLab diff note is only valid with all of these
`resolved`	No
`discussion_id`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Oct 5, 2026

TDQS

A4.7/5.0

Behavior5/5

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

With only readOnlyHint=false in the annotations, the description carries real behavioral weight: it discloses that base/start/head SHAs and the old-side line number are auto-resolved from the latest diff version, and that a stale SHA or out-of-diff line is reported rather than silently sent. It also reveals the return linkage (discussion_id) for follow-up calls — context well beyond the annotation.

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?

Three dense sentences, front-loaded with the purpose, followed by parameter sourcing guidance and the threading handoff. No filler; every sentence contributes actionable information.

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 6-parameter write tool with an output schema, the description covers the difficult parts an agent cannot infer: how to source path/line from a sibling tool, how SHAs are resolved, and how validation failures surface. Return values need not be enumerated given the output schema, and the discussion_id note covers the one essential output field.

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 cross-parameter meaning the schema does not: `path` must match the format reported by gitlab_mr_changes, and `line` is interpreted relative to the chosen side of the diff. That is genuine added semantics over the structured fields.

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+resource+granularity: 'Comment on one line of the merge request diff, as a normal review comment.' This differentiates it from the sibling gitlab_mr_comment (general MR comment) and gitlab_mr_reply (thread continuation) without the agent needing to open any schema.

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?

Gives concrete usage context: derive `path` exactly as gitlab_mr_changes reports it, supply the line on the relevant side, and pass the returned discussion_id to gitlab_mr_reply to continue the thread. It names the alternative for threading, but never states explicit exclusions (e.g., when to choose gitlab_mr_comment over this tool for non-line comments).

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