gitlab-mcp

gitlab_file_get

Read-only

Read one GitLab file at a branch, tag, or commit, defaulting to the project default branch. Pass an MR source branch to view it as the merge request does; capped output flags truncation.

Instructions

Read one file from the repository at a ref. Defaults to the project default branch - pass ref= to read the file as the merge request sees it. Output is capped, and a truncated read says so.

Input Schema

TableJSON Schema

Name	Required	Description
`ref`	No	branch, tag or commit SHA; defaults to the project default branch
`path`	Yes	repository-relative file path, e.g. 'src/app.ts' (no leading slash)
`project`	Yes	project id ('42') or full path ('group/subgroup/app'); a path is URL-encoded for you
`maxChars`	No	cap on returned characters; the file itself may be longer

Output Schema

TableJSON Schema

Name	Required	Description
`ref`	Yes
`url`	No
`path`	Yes
`size`	Yes	characters returned, after truncation
`dryRun`	No
`content`	No
`truncated`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Oct 5, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the default-branch fallback and the self-disclosing output cap with truncation signal. A rate limit or size ceiling beyond maxChars is not stated, but the core behavior is well disclosed.

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 short sentences, front-loaded with the core action, then the ref tip, then the output caveat. Nothing repeats the name or wastes space.

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?

With an output schema present, return values need no prose, and the description still flags the truncation behavior. Combined with 100% schema coverage and a read-only annotation, an agent has everything needed to call this correctly.

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 description adds meaning beyond the schema by explaining the MR source_branch ref pattern, a workflow the schema's generic 'branch, tag or commit SHA' wording does not convey.

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: 'Read one file from the repository at a ref.' This is clearly distinct from sibling tools like gitlab_project_get, gitlab_mr_changes, or gitlab_commit_list, and the ref scoping makes the access model unambiguous.

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 when-to-use guidance: pass ref=<the MR source_branch> to read the file as the merge request sees it. It does not name alternative siblings or state when-not to use this tool, so it stops short of a full routing guide.

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