gitlab mcp

list_issues

Read-only

List and filter GitLab issues by project, scope, state, labels, assignee, author, dates, or search to support issue management. Use scope='all' to view issues beyond your own.

Instructions

List issues (default: created by current user; use scope='all' for all). Use this for issue management. Optional project_id. Use get_issue when the iid is known and my_issues for assignments.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_issues"
  }
}

Input Schema

Name	Required	Description
`page`	No	Page number (default 1)
`scope`	No	Issue scope
`state`	No	Issue state
`labels`	No	Label names
`search`	No	Search terms
`summary`	No	If true, return only high-signal fields (id, iid, title, state, web_url, …). Default false keeps the full GitLab JSON.
`due_date`	No	Due date
`jmespath`	No	Optional JMESPath expression filtering the JSON result before return.
`per_page`	No	Items per page (max 100, default 20)
`author_id`	No	Author user ID. Mutually exclusive with author_username.
`milestone`	No	Milestone title
`issue_type`	No	issue, incident, test_case, or task
`project_id`	No	Project ID or URL-encoded path. Omit to list issues across accessible projects.
`assignee_id`	No	User ID, none, or any. Mutually exclusive with assignee_username.
`confidential`	No	Confidential or public
`iteration_id`	No	Iteration ID, none (no iteration), or any (has an iteration).
`created_after`	No	Created after
`updated_after`	No	Updated after
`created_before`	No	Created before
`updated_before`	No	Updated before
`author_username`	No	Author username. Mutually exclusive with author_id.
`assignee_username`	No	Username. Mutually exclusive with assignee_id.
`with_labels_details`	No	Include label details

Schema Changelog

Changes observed during successful MCP inspections.

Changed20 schema fields changedv2.3.22Nov 5, 2026

changedInput schema / properties / assignee_id / description

Previous value: -"Return issues assigned to the given user ID (user id, none, or any). Mutually exclusive with assignee_username."New value: +"User ID, none, or any. Mutually exclusive with assignee_username."

changedInput schema / properties / assignee_username / description

Previous value: -"Return issues assigned to the given username. Mutually exclusive with assignee_id."New value: +"Username. Mutually exclusive with assignee_id."

changedInput schema / properties / author_id / description

Previous value: -"Return issues created by the given user ID. Mutually exclusive with author_username."New value: +"Author user ID. Mutually exclusive with author_username."

changedInput schema / properties / author_username / description

Previous value: -"Return issues created by the given username. Mutually exclusive with author_id."New value: +"Author username. Mutually exclusive with author_id."

changedInput schema / properties / confidential / description

Previous value: -"Filter confidential or public issues"New value: +"Confidential or public"

changedInput schema / properties / created_after / description

Previous value: -"Return issues created after the given time"New value: +"Created after"

changedInput schema / properties / created_before / description

Previous value: -"Return issues created before the given time"New value: +"Created before"

changedInput schema / properties / due_date / description

Previous value: -"Return issues that have the due date"New value: +"Due date"

changedInput schema / properties / issue_type / description

Previous value: -"Filter to a given type of issue. One of issue, incident, test_case or task"New value: +"issue, incident, test_case, or task"

changedInput schema / properties / iteration_id / description

Previous value: -"Return issues assigned to the given iteration ID. None returns issues that do not belong to an iteration. Any returns issues that belong to an iteration. "New value: +"Iteration ID, none (no iteration), or any (has an iteration)."

changedInput schema / properties / labels / description

Previous value: -"Array of label names"New value: +"Label names"

changedInput schema / properties / page / description

Previous value: -"Page number for pagination (default: 1)"New value: +"Page number (default 1)"

changedInput schema / properties / per_page / description

Previous value: -"Number of items per page (max: 100, default: 20)"New value: +"Items per page (max 100, default 20)"

changedInput schema / properties / project_id / description

Previous value: -"Project ID or URL-encoded path (optional - if not provided, lists issues across all accessible projects)"New value: +"Project ID or URL-encoded path. Omit to list issues across accessible projects."

changedInput schema / properties / scope / description

Previous value: -"Return issues from a specific scope"New value: +"Issue scope"

changedInput schema / properties / search / description

Previous value: -"Search for specific terms"New value: +"Search terms"

changedInput schema / properties / state / description

Previous value: -"Return issues with a specific state"New value: +"Issue state"

changedInput schema / properties / updated_after / description

Previous value: -"Return issues updated after the given time"New value: +"Updated after"

changedInput schema / properties / updated_before / description

Previous value: -"Return issues updated before the given time"New value: +"Updated before"

changedInput schema / properties / with_labels_details / description

Previous value: -"Return more details for each label"New value: +"Include label details"

Changed1 schema field changedv2.3.8Oct 24, 2026

addedInput schema / properties / summary

Added value: +{
+  "description": "If true, return only high-signal fields (id, iid, title, state, web_url, …). Default false keeps the full GitLab JSON.",
+  "type": "boolean"
+}

Changed1 schema field changedv2.1.66Sep 23, 2026

addedInput schema / properties / jmespath

Added value: +{
+  "description": "Optional JMESPath expression filtering the JSON result before return.",
+  "type": "string"
+}

Changed4 schema fields changedv2.1.21Jun 15, 2026

changedInput schema / properties / assignee_id / description

Previous value: -"Return issues assigned to the given user ID. user id or none or any"New value: +"Return issues assigned to the given user ID (user id, none, or any). Mutually exclusive with assignee_username."

changedInput schema / properties / assignee_username / description

Previous value: -"Return issues assigned to the given username"New value: +"Return issues assigned to the given username. Mutually exclusive with assignee_id."

changedInput schema / properties / author_id / description

Previous value: -"Return issues created by the given user ID"New value: +"Return issues created by the given user ID. Mutually exclusive with author_username."

changedInput schema / properties / author_username / description

Previous value: -"Return issues created by the given username"New value: +"Return issues created by the given username. Mutually exclusive with author_id."

Addedv2.1.18May 30, 2026
Removedv2.1.14May 22, 2026
Addedv2.1.11May 13, 2026
Removedv2.1.10May 9, 2026
Changed1 schema field changedv2.1.9May 9, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
First observedv1.0.0Jan 2, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds a genuinely non-obvious behavioral fact — that results are silently filtered to issues created by the current user unless scope='all' — which is not stated in the schema. It does not mention pagination limits or the summary/jmespath output-shaping behavior, but those are documented in the schema.

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

Conciseness4/5

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

Three short sentences, front-loaded with the scope default that most affects results, followed by alternatives. The middle sentence 'Use this for issue management' is generic filler that could be dropped without loss.

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 23-parameter, no-required-param list tool with full schema descriptions and read-only annotations, the description supplies what the schema cannot: the implicit scope default and sibling routing. Missing only output-shape/pagination expectations, which the schema's page, per_page, and summary fields largely cover.

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 would be 3. The description adds the missing default value for the scope parameter (created_by_me), which the schema only labels 'Issue scope'. The note that project_id is optional and omitting it spans all accessible projects restates the schema rather than extending it.

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?

The description opens with a specific verb and resource ('List issues') and immediately qualifies the scope with the default behavior (created by current user). It also names the sibling tools get_issue and my_issues so the agent can distinguish the listing role, though the filler sentence 'Use this for issue management' adds nothing.

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?

It gives concrete routing: use scope='all' to broaden beyond the default, use get_issue when the iid is known, and use my_issues for assignments. That covers the main decision points, but there is no guidance on when to use this versus other listing tools like list_projects or list_merge_requests, nor when to omit project_id.

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