gitlab-api

Get groups

gitlab_get_groups

Read-onlyIdempotent

Retrieve GitLab groups with optional filters and pagination to browse group data and support management tasks.

Instructions

Get a list of groups.

Args: **kwargs: Additional parameters for the request (e.g., group_id).

Returns: Response: A wrapper containing the original response and a list of Group models.

Raises: ParameterError: If invalid parameters are provided.

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": "gitlab_get_groups"
  }
}

Input Schema

Name	Required	Description	Default
`data`	No
`name`	No
`page`	No
`path`	No
`avatar`	No
`argument`	No
`group_id`	No
`per_page`	No
`max_pages`	No
`visibility`	No
`description`	No
`lfs_enabled`	No
`total_pages`	No
`default_branch`	No
`emails_enabled`	No
`membership_lock`	No
`mentions_disabled`	No
`wiki_access_level`	No
`auto_devops_enabled`	No
`duo_features_enabled`	No
`ip_restriction_ranges`	No
`share_with_group_lock`	No
`project_creation_level`	No
`request_access_enabled`	No
`shared_runners_setting`	No
`subgroup_creation_level`	No
`two_factor_grace_period`	No
`file_template_project_id`	No
`default_branch_protection`	No
`lock_duo_features_enabled`	No
`allowed_email_domains_list`	No
`enabled_git_access_protocol`	No
`shared_runners_minutes_limit`	No
`math_rendering_limits_enabled`	No
`prevent_forking_outside_group`	No
`unique_project_download_limit`	No
`require_two_factor_authentication`	No
`default_branch_protection_defaults`	No
`extra_shared_runners_minutes_limit`	No
`lock_math_rendering_limits_enabled`	No
`unique_project_download_limit_alertlist`	No
`unique_project_download_limit_allowlist`	No
`prevent_sharing_groups_outside_hierarchy`	No
`auto_ban_user_on_excessive_projects_download`	No
`unique_project_download_limit_interval_in_seconds`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv27.3.20Nov 7, 2026

removedInput schema / properties / api_parameters

Removed value: -{
-  "anyOf": [
-    {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

changedInput schema / properties / argument / default
```
Previous value: -"state=opened"New value: +null
```

removedInput schema / properties / avatar / anyOf

Removed value: -[
-  {
-    "format": "binary",
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / avatar / title
```
Added value: +"Avatar"
```
changedInput schema / properties / page / default
```
Previous value: -1New value: +null
```
changedInput schema / properties / per_page / default
```
Previous value: -100New value: +null
```

First observedv27.3.13Oct 25, 2026

TDQS

C2.8/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description does add value by disclosing the return shape (a wrapper containing a list of Group models) and the ParameterError behavior. What it omits is pagination behavior, despite the schema exposing page, per_page, max_pages, and total_pages — a real gap for a listing tool.

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 description is short and front-loads the purpose, which is good. But it retains docstring boilerplate (Args/Returns/Raises) whose Args section is actively unhelpful, declaring a kwargs parameter that does not exist in the schema and thus wastes the only parameter-facing sentence.

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

Completeness2/5

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

For a tool with 45 parameters and no output schema, the description is far too thin: it explains neither the pagination controls nor what most parameters mean. The Returns section partially compensates for the missing output schema, but the input side is effectively undocumented and the group-filtering story is unclear.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 45 parameters, so the description carries the full explanatory burden and fails: it only says '**kwargs: Additional parameters for the request (e.g., group_id)', which does not describe the actual named schema fields. It gives no hint which parameters filter results (name, path, visibility, search-like fields) versus which appear to be group attribute fields (lfs_enabled, default_branch_protection, two_factor_grace_period), leaving the agent unable to reason about inputs.

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 states a specific verb and resource: 'Get a list of groups', which is unambiguous on its face. However, it offers no differentiation from the many sibling list/read tools in this server (gitlab_get_group, gitlab_get_group_subgroups, gitlab_get_project_groups, gitlab_get_namespaces), so an agent must guess which list tool covers its case.

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

Usage Guidelines2/5

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

There is no when-to-use guidance, no exclusions, and no mention of alternatives among the sibling group/namespace listing tools. The only usage-adjacent content is a Raises clause about ParameterError, which is error behavior, not selection guidance.

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

Deploy Server