The CERN GitLab MCP Server connects LLMs to CERN GitLab, enabling discovery, browsing, and analysis of High Energy Physics (HEP) code and repositories through 14 specialized tools.
Search & Discovery
Search Projects – Find public CERN GitLab projects by keyword, topic, or programming language
Search Code – Find code snippets globally or within specific projects, with line-level context (requires authentication)
Search LHCb Stack – Search code within a specific LHCb software stack (e.g., sim11) with automatic Git reference resolution (requires authentication)
Search Issues – Find issues and discussions within a project or across all accessible projects (requires authentication)
Browse & Read Repositories
Get Project Info – Retrieve detailed metadata (stars, description, languages, statistics)
List Project Files – Browse files and directories, with recursive listing and branch support
Get File Content – Fetch file content with binary detection and syntax highlighting hints
Get Project README – Auto-detect and retrieve the project README
Get Wiki Pages – List or retrieve project wiki pages (requires authentication)
Analyze & Inspect
Inspect Project – Analyze project structure, build systems (CMake, Make, etc.), dependencies, and CI/CD configuration in a single report
Releases & Versions
List Releases – Browse release history with tags, dates, and descriptions
Get Release – Retrieve release notes, assets, and download links for a specific release
List Tags – List version tags with filtering and sort control
Connectivity & Operations
Test Connectivity – Verify connection, check authentication status, and retrieve GitLab version info
Flexible deployment – Single-user stdio mode, multi-user HTTP mode for centralized deployments, or a dedicated CLI
Authentication – Works without tokens for public repositories; a personal access token unlocks code search, issue search, wiki access, and private/internal projects
Robustness – Built-in rate limiting, retries with exponential backoff, and graceful error handling
LLM integration – Compatible with Claude Desktop, Claude Code, GitHub Copilot, Gemini CLI, and more
Facilitates analysis of C++ projects through dependency parsing and retrieval of build configuration files.
Provides tools to find and analyze CMakeLists.txt files to understand repository build structures.
Enables the discovery and analysis of scientific codebases by parsing dependency files within Fortran ecosystems.
Enables repository exploration through file tree browsing, tag management, and release tracking.
Provides comprehensive tools for searching repositories, browsing files, and analyzing CI/CD configurations and wiki pages on CERN GitLab instances.
Allows for the retrieval and analysis of Makefiles to understand project build configurations.
Supports analysis of Python projects by parsing requirements.txt, pyproject.toml, and setup.py files to identify dependencies.
Parses TOML-based configuration files, such as pyproject.toml, to extract project dependency and metadata information.
Enables structural analysis of YAML files, specifically targeting GitLab CI/CD configurations and Conda environment definitions.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CERN GitLab MCP Server search for ATLAS analysis repositories written in Python"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
15 MCP tools for searching, browsing, and analyzing CERN GitLab repositories
Dual-mode operation — stdio (single-user) and HTTP (multi-user) modes
CLI tool (cerngitlab-cli) for direct command-line usage
Public access — works without authentication for public repositories
Multi-user HTTP mode — CERN SSO + GitLab OAuth authentication for centralized deployments; GitLab enforces all access permissions natively
HEP-focused — dependency parsing for Python and C++ ecosystems, binary detection for .root files, issue search
Robust — rate limiting, retries with exponential backoff, graceful error handling
Related MCP server: CERN ROOT MCP Server
Requires Python 3.10+.
No installation needed — just use uvx to run directly:
uvx cerngitlab-mcppip install cerngitlab-mcpgit clone https://github.com/MohamedElashri/cerngitlab-mcp
cd cerngitlab-mcp
uv syncAll settings are configured via environment variables prefixed with CERNGITLAB_:
Variable | Default | Description |
|
| GitLab instance URL |
| (empty) | Personal access token (optional, for stdio mode) |
|
| HTTP timeout in seconds |
|
| Max retries for failed requests |
|
| API rate limit |
|
| Logging level |
| (empty) | Default Git branch or tag for code search. Empty uses GitLab's default ref behavior. |
| (empty) | Set any value to auto-detect HTTP mode |
|
| HTTP server bind address |
|
| HTTP server bind port |
| (empty) | HTTP mode — CERN SSO OAuth client ID |
| (empty) | HTTP mode — GitLab OAuth application client ID |
| (empty) | HTTP mode — GitLab OAuth application client secret |
|
| HTTP mode — Public base URL (used for OAuth callback) |
|
| HTTP mode — Directory for persisting OAuth session files |
The server works in two modes:
Without token — Access to all public repositories. Sufficient for most HEP code discovery.
With token — Additional access to internal/private projects, code search, and wiki pages.
To create a token:
Go to https://gitlab.cern.ch/-/user_settings/personal_access_tokens
Create a token with read_api scope
Set CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx
Note: The code search (
search_code), issue search (search_issues), and wiki (get_wiki_pages) tools require authentication on CERN GitLab.
Add to your claude_desktop_config.json:
{
"mcpServers": {
"cerngitlab": {
"command": "uvx",
"args": ["cerngitlab-mcp"],
"env": {
"CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
}
}
}
}Note for macOS users: If you see an error about
uvxnot being found, you may need to provide the absolute path. Claude Desktop does not support~or$HOMEexpansion.
Run
which uvxin your terminal to find the path (e.g.,/Users/yourusername/.local/bin/uvx).Use that absolute path in the
commandfield:"command": "/Users/yourusername/.local/bin/uvx"
Project-specific (default) — installs in the current directory's configuration:
claude mcp add cerngitlab-mcp -- uvx cerngitlab-mcpGlobal — installs for your user account (works in all projects):
claude mcp add --scope user cerngitlab-mcp -- uvx cerngitlab-mcpTo include authentication, add -e CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx before the --:
# Example: Global installation with token
claude mcp add --scope user -e CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx cerngitlab-mcp -- uvx cerngitlab-mcpManual Configuration — you can also manually edit your global config at ~/.claude.json (on Linux/macOS) or %APPDATA%\Claude\claude.json (on Windows):
{
"mcpServers": {
"cerngitlab": {
"command": "uvx",
"args": ["cerngitlab-mcp"],
"env": {
"CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
}
}
}
}Add to your VS Code settings.json:
{
"mcp": {
"servers": {
"cerngitlab": {
"command": "uvx",
"args": ["cerngitlab-mcp"],
"env": {
"CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
}
}
}
}
}Or add a .vscode/mcp.json to your project:
{
"servers": {
"cerngitlab": {
"command": "uvx",
"args": ["cerngitlab-mcp"],
"env": {
"CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
}
}
}
}Add to your ~/.gemini/settings.json:
{
"mcpServers": {
"cerngitlab": {
"command": "uvx",
"args": ["cerngitlab-mcp"],
"env": {
"CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
}
}
}
}# Run with uvx (no install needed)
uvx cerngitlab-mcp
# Or if installed from PyPI
cerngitlab-mcp
# Explicit stdio mode
cerngitlab-mcp --mode stdio
# Or from source
uv run cerngitlab-mcp
# With authentication
CERNGITLAB_TOKEN=glpat-xxx uvx cerngitlab-mcp# HTTP mode for multi-user deployment
cerngitlab-mcp --mode http --host 0.0.0.0 --port 8080
# Or use environment variables
CERNGITLAB_HTTP_MODE=true CERNGITLAB_HOST=0.0.0.0 CERNGITLAB_PORT=8080 cerngitlab-mcp
# Dedicated HTTP entry point
cerngitlab-mcp-http--mode stdio - Single-user mode using stdin/stdout (default)
--mode http - Multi-user mode using HTTP API
--mode auto - Auto-detect based on environment variables
The server automatically detects HTTP mode if CERNGITLAB_HTTP_MODE, CERNGITLAB_HOST, or CERNGITLAB_PORT environment variables are set.
Tool | Description | Auth required |
| Search for public CERN GitLab projects (repositories) by keyword, topic, or language | No |
| Get detailed project metadata (stars, description, languages, statistics) | No |
| List or search project branches and their commit metadata | No |
| List files and directories in a project's repository | No |
| Fetch the content of a specific file (includes binary detection) | No |
| Get the README content for a project | No |
| Search for code within a specific project or globally | Yes* |
| Search for code within an LHCb software stack (e.g., 'sim11'), with automatic Git ref resolution | Yes* |
| Search for issues in a project | Yes |
| List wiki pages for a project | Yes |
| Analyze project structure, build system, dependencies, and CI/CD | No |
| List releases for a project | No |
| Get details of a specific release | No |
| List tags for a project | No |
| Test connection to the GitLab instance | No |
For detailed parameter documentation, see docs/dev.md.
"Search CERN GitLab for Python repositories related to ROOT analysis and show me the most starred ones"
"Get the README and file structure of the lhcb/DaVinci project on CERN GitLab"
"Find branches containing 'release' in lhcb/DaVinci, then search the selected branch for Scheduler configuration"
"Search for repositories on CERN GitLab that use RooFit and show me example fitting code"
"Search the LHCb sim11 stack for the initialization routines in the Boole project"
"Inspect the lhcb/allen project to understand its build system, dependencies, and CI pipeline configuration"
"Search for issues related to 'segmentation fault' in the atlas/athena project to see if others have encountered this"
"List the recent releases of lhcb/DaVinci and show me the release notes for the latest version"
"Search for Gaudi framework configuration files on CERN GitLab and show me examples"
See docs/dev.md for development setup, project structure, testing, and release instructions.
HTTP mode provides a centralized server for multiple users. It uses CERN SSO + GitLab OAuth for authentication, users authenticate with their existing CERN identity, and GitLab's own permission system enforces all access controls.
CERN SSO client — Register a client at the CERN Authorization Service. Note the client ID.
GitLab OAuth application — Create one at https://gitlab.cern.ch/-/profile/applications.
Set the redirect URI to https://gitlabmcp.cern.ch/oauth/callback (replace with actual URL)
Enable the read_api read_repository read_user scopes
Note the application ID and secret.
export CERNGITLAB_CERN_CLIENT_ID=your-cern-sso-client-id
export CERNGITLAB_GITLAB_OAUTH_CLIENT_ID=your-gitlab-oauth-app-id
export CERNGITLAB_GITLAB_OAUTH_CLIENT_SECRET=your-gitlab-oauth-secret
export CERNGITLAB_SERVER_BASE_URL=https://gitlabmcp.cern.ch
export CERNGITLAB_SESSION_STORAGE_PATH=/var/lib/cerngitlab/sessions # optional
# Start the server
cerngitlab-mcp --mode http --host 0.0.0.0 --port 8000See examples/oauth_server.py in the repository for a self-contained reference script.
Client sends a request with Authorization: Bearer <cern-sso-token> header.
Server validates the CERN SSO token via CERN's JWKS endpoint.
If the user has no active GitLab OAuth session, the server returns HTTP 202 with a authorization_url field.
The user visits that URL, authorizes the GitLab OAuth application, and is redirected back to /oauth/callback.
Subsequent requests are served using the stored GitLab OAuth token. Sessions expire after 2 hours.
Method | Path | Auth | Description |
|
| — | Server information |
|
| — | Health check |
|
| CERN SSO | Start or check the OAuth authorization flow |
|
| — | Receive the GitLab OAuth code (browser redirect) |
|
| CERN SSO | List available MCP tools |
|
| CERN SSO | Execute a specific tool |
|
| CERN SSO | Revoke the current user's OAuth session |
|
| — | List all active sessions (admin use) |
Assuming the server is running at https://gitlabmcp.cern.ch and the CERN_SSO_TOKEN environment variable is set to a valid CERN SSO token:
# Step 1 – check authorization status
curl -H "Authorization: Bearer $CERN_SSO_TOKEN" \
https://gitlabmcp.cern.ch/oauth/authorize
# If 202, visit the returned authorization_url in a browser and authorize.
# Step 2 – list available tools (once authorized)
curl -H "Authorization: Bearer $CERN_SSO_TOKEN" \
https://gitlabmcp.cern.ch/tools
# Step 3 – execute a tool
curl -X POST -H "Authorization: Bearer $CERN_SSO_TOKEN" \
-H "Content-Type: application/json" \
-d '{"arguments": {"query": "ROOT"}}' \
https://gitlabmcp.cern.ch/tools/search_projects
# Revoke session
curl -X DELETE -H "Authorization: Bearer $CERN_SSO_TOKEN" \
https://gitlabmcp.cern.ch/sessionA command-line interface is also available for direct usage without the MCP server:
# Install or use with uvx
uvx cerngitlab-cli
# Test connectivity
cerngitlab-cli test-connection
# Search for projects
cerngitlab-cli search-projects --query "ROOT analysis" --language python
# Get project info
cerngitlab-cli get-project-info --project lhcb/DaVinci
# Search code
cerngitlab-cli search-code --search-term "RooFit" --per-page 10
# Inspect project structure
cerngitlab-cli inspect-project --project lhcb/allenAll commands output JSON to stdout for easy piping and composition. See cerngitlab-cli --help for the full list of commands.
A detailed skill file (SKILL.md) is available with:
Complete documentation of all 15 tools
Input/output specifications
Usage examples
Authentication requirements
This can be used by LLMs or agents to understand the available tools and how to use them.
This software is provided under the AGPL-3.0 license.
Retrieve the content of a specific file from a CERN GitLab repository. Returns the file content along with metadata like size, encoding, and a language hint for syntax highlighting. Binary files are detected and reported without attempting to decode them.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | Branch name, tag, or commit SHA (default: project's default branch) | |
| project | Yes | Project identifier — either a numeric ID (e.g. '12345') or a URL-encoded path (e.g. 'atlas/athena') | |
| file_path | Yes | Path to the file within the repository (e.g. 'src/main.py') |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only include readOnlyHint=true, so the description carries the burden of behavioral disclosure. It adds value by detailing that binary files are detected and reported without decoding, and that metadata (size, encoding, language hint) is returned. This goes beyond the annotation without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the core purpose and followed by key behavioral details. No wasted words; each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 not be explained. The description covers binary handling and metadata, which is sufficient for a simple retrieval tool. It omits error handling or size limits, but these are not critical for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all three parameters with clear meanings (project, file_path, ref). The description does not add additional parameter-specific semantics beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('retrieve') and resource ('content of a specific file from a CERN GitLab repository'), clearly distinguishing it from sibling tools like list_project_files which list files rather than contents. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving file content but does not explicitly mention when to use this tool versus alternatives like list_project_files or search_code. No exclusions or conditions are stated, providing only implied guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific CERN GitLab project (metadata, statistics, description). Accepts either a numeric project ID or a full project path (e.g. 'atlas/athena').
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project identifier — either a numeric ID (e.g. '12345') or a URL-encoded path (e.g. 'atlas/athena') |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description correctly matches that by describing a read-only information retrieval operation. It adds useful context about accepted input forms and the kind of content returned, but does not disclose edge-case behavior such as project-not-found handling or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the purpose, and includes a concrete example without any filler or redundant repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple single-parameter read-only tool with a full output schema, so return values need no additional explanation. The description provides the necessary calling context and acceptable input formats, making it complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents that 'project' is either a numeric ID or URL-encoded path. The description reinforces this with a human-friendly example ('atlas/athena') but adds limited new semantic meaning beyond what the input schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('detailed information about a specific CERN GitLab project'), with concrete output categories listed. It is clearly about a single project rather than searching or listing, though it does not explicitly differentiate itself from the similarly scoped sibling 'inspect_project'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes the context: use this when you have a specific project identifier and want metadata/statistics/description. It does not explicitly call out alternatives like 'search_projects' or 'inspect_project', but the usage context is clear and not misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the README file content for a CERN GitLab project. Automatically detects standard README filenames (README.md, README.rst, etc.). Returns the raw content — useful for understanding what a project does.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | Branch name, tag, or commit SHA (default: project's default branch) | |
| project | Yes | Project identifier — either a numeric ID (e.g. '12345') or a URL-encoded path (e.g. 'atlas/athena') |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint=true annotation already establishes the read-only safety profile. The description adds meaningful behavioral context by disclosing automatic README filename detection and that it returns raw content rather than a parsed summary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences lead with the primary action and then cover behavior and purpose. There is no filler or redundant restating of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only tool with an output schema and complete parameter documentation, the description supplies all necessary context. It states what is returned, that standard filenames are auto-detected, and why it is useful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes both parameters with 100% coverage, so the baseline of 3 applies. The description does not add parameter-specific meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Get the README file content') against a concrete resource ('CERN GitLab project'). The mention of automatically detecting standard README filenames further differentiates it from path-based sibling tools like get_file_content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case ('useful for understanding what a project does') but does not explicitly state when to use this tool versus alternatives such as get_file_content, get_project_info, or search_projects. No exclusions or alternative routing is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific release from a CERN GitLab repository. Returns release notes, assets, commit info, and download links. Requires the tag name of the release.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project identifier — either a numeric ID (e.g. '12345') or a URL-encoded path (e.g. 'atlas/athena') | |
| tag_name | Yes | The tag name of the release (e.g. 'v1.0.0') |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers safety, and the description adds useful context about what kind of data is returned. No authorization, pagination, or failure behavior is disclosed, but the annotation lowers the burden and no contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences communicate purpose, return contents, and the prerequisite. The text is front-loaded with the main intent and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read operation with full parameter schema coverage and an output schema. The description conveys the essential purpose and prerequisite; only minor enhancements like explicit sibling differentiation could make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both 'project' and 'tag_name' are already well documented in the input schema. The description adds only that tag_name is required, which the schema already states, providing no additional semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Get detailed information about a specific release'), a clear resource, and the key output categories (release notes, assets, commit info, download links). This distinguishes it from siblings like list_releases and list_tags, which are collection-level operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for fetching one release when the tag name is already known, and explicitly states the tag requirement. However, it does not give explicit when-to-use versus when-not-to-use guidance or mention alternative sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Access wiki pages from a CERN GitLab repository. Can list all wiki pages or retrieve the content of a specific page. Useful for accessing project documentation that lives in the wiki.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project identifier — either a numeric ID (e.g. '12345') or a URL-encoded path (e.g. 'atlas/athena') | |
| page_slug | No | Optional: slug of a specific wiki page to retrieve. If omitted, lists all wiki pages. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the safety profile, so the description only needs to add behavioral details. It does add the list-vs-retrieve mode distinction based on page_slug, but it does not disclose pagination, response shape, or other edge behavior. This matches the modest value expected when annotations already declare read-only semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with no filler: a clear subject line, a functional summary of the two modes, and a useful context note. The most important information is front-loaded, and every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only wiki access tool with a fully documented input schema and an output schema present, the description is complete. An agent can correctly invoke it for listing or retrieving wiki pages without missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both project and page_slug, including the default behavior for an omitted page_slug. The description restates the list-vs-specific behavior, but adds no meaning beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource ('wiki pages') and the exact operations (list all pages or retrieve a specific page's content), and ties it to CERN GitLab. This clearly distinguishes it from sibling tools like get_project_readme and get_file_content by focusing on the wiki.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when the tool is useful: 'project documentation that lives in the wiki.' It does not explicitly name alternatives or exclusions, so it falls short of a 5, but the context is enough for an agent to route wiki-related requests here.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze a CERN GitLab repository to understand its structure, build system, and dependencies. Combines functionality of dependency analysis, build config detection, and CI/CD inspection into a single tool. Returns a comprehensive summary of the project's technical stack.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | Branch name, tag, or commit SHA (default: project's default branch) | |
| project | Yes | Project identifier — either a numeric ID (e.g. '12345') or a URL-encoded path (e.g. 'atlas/athena') |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only safety profile is covered. The description adds useful context by disclosing that this tool aggregates multiple analysis capabilities and returns a summary, which is behavior beyond a simple read. It does not discuss cost, time, or details of what the analysis inspects, but the output schema covers return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler: purpose, scope/behavior, and return value. The main verb and resource are front-loaded, and every sentence contributes meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an aggregating inspection tool, the description is largely complete: it names the analytical dimensions, states the summary output, and the output schema covers the return structure. It could be slightly stronger by referencing specific sibling tools to guide selection, but nothing essential is missing for invoking it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both 'project' and 'ref' are already documented in the schema. The tool description adds no additional parameter semantics, which is acceptable given the schema carries the full burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Analyze') with a clear resource ('a CERN GitLab repository') and defines the output (structure, build system, dependencies, technical stack). It also distinguishes itself from sibling tools by explicitly stating it combines functionality that would otherwise require multiple tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: when a comprehensive project stack overview is needed, covering dependencies, build config, and CI/CD. It implies this is the umbrella tool versus more granular siblings, though it does not explicitly name alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List or search branches in a CERN GitLab repository. Returns branch names and commit metadata so a branch can be selected and passed as the 'ref' argument to repository content and code-search tools.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number to retrieve | |
| search | No | Optional branch-name filter. GitLab supports partial matches and anchors such as '^main$' for an exact match. | |
| project | Yes | Project identifier — either a numeric ID (e.g. '12345') or a URL-encoded path (e.g. 'atlas/athena') | |
| per_page | No | Number of branches to return |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the safety profile. The description adds that results include branch names and commit metadata, plus the intended downstream use, which is useful context. It does not disclose pagination defaults or ordering behavior, but those are partly covered by the schema and output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The core action and scope are front-loaded, and the second sentence adds practical guidance about why the output matters. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity listing tool with a fully documented schema, an output schema, and a readOnly annotation, the description is complete. It tells the agent what the tool does, what it returns, and how the result should be used in subsequent calls.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters well. The description reinforces the purpose of the returned branch names but does not add substantial parameter-level meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List or search'), a clear resource ('branches in a CERN GitLab repository'), and reveals the downstream purpose (supplying a 'ref' argument). This makes it easy to distinguish from sibling tools like list_tags or list_releases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly identifies when the tool is useful: when a branch needs to be selected and passed as a 'ref' to repository content or code-search tools. It does not explicitly state exclusions or when not to use it, but the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files and directories in a CERN GitLab project's repository. Supports recursive listing and path specific lookups.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | Branch name, tag, or commit SHA (default: project's default branch) | |
| path | No | Directory path within the repository (default: root '/') | |
| project | Yes | Project identifier — either a numeric ID (e.g. '12345') or a URL-encoded path (e.g. 'atlas/athena') | |
| per_page | No | Number of entries to return | |
| recursive | No | If true, list files recursively |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the readOnlyHint annotation and presents the operation as a pure read action. However, it adds little behavioral context beyond what the schema already exposes, such as pagination behavior, default branch fallback, or return limitations. The annotation lowers the burden, so this meets the baseline without exceeding it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence defines the action and target, and the second highlights the two most useful capabilities. There is no filler, no repetition of the tool title, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With full schema coverage, a readOnlyHint, and an output schema present, the description together with structured data is sufficient for an agent to invoke this tool correctly. It could be improved by explicitly noting that file contents are not returned here, but that distinction is inferable from the sibling tool set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well documented. The description's mention of 'recursive listing and path specific lookups' restates what the schema says rather than adding new meaning, such as how project IDs are formatted or how recursive and path interact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and a specific resource ('files and directories in a CERN GitLab project's repository'), making the tool's purpose clear. It is distinguishable from siblings like get_file_content or list_branches, though it does not explicitly name or contrast any sibling, so it falls just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_file_content, inspect_project, or list_branches. It mentions recursive listing and path-specific lookups, but it does not give routing cues, exclusions, or prerequisites, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List releases from a CERN GitLab repository. Returns release tags, dates, and descriptions. Useful for tracking software versions and finding changelogs.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project identifier — either a numeric ID (e.g. '12345') or a URL-encoded path (e.g. 'atlas/athena') | |
| per_page | No | Number of releases to return |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the main safety trait, and the description adds that it returns tags, dates, and descriptions. However, it does not disclose behavior such as pagination limits, ordering, or that the result is a list rather than a single release; the output schema covers return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences front-load the action and output, and the final sentence identifies practical use. Every sentence contributes and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only listing tool with an output schema, the description covers the essentials. The only minor gap is that it does not suggest the sibling tool get_release for retrieving one release in detail, but this is not required for calling the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so project and per_page are already fully documented with types, defaults, and constraints. The description adds no additional parameter semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the specific action (list), the resource (releases from a CERN GitLab repository), and the expected output (release tags, dates, descriptions). It does not explicitly contrast itself with siblings like get_release or list_tags, which keeps it from a 5, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear intended use cases: tracking software versions and finding changelogs. It does not explicitly state when not to use it or name an alternative like get_release for a single release, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tags from a CERN GitLab repository. Returns tag names with their associated commit references. Useful for finding version history and release points.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort order by tag name (default: desc — newest first) | desc |
| search | No | Optional: filter tags by name (e.g. 'v1' to find all v1.x tags) | |
| project | Yes | Project identifier — either a numeric ID (e.g. '12345') or a URL-encoded path (e.g. 'atlas/athena') | |
| per_page | No | Number of tags to return |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only supply readOnlyHint=true, and the description adds return-value context (commit references) and use case, but doesn't disclose behavior like pagination defaults, sorting, or search filtering. These are partly covered by schema, so this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences immediately state the action and resource, then add the return contents and intended use. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a complete input schema, an output schema, readOnlyHint annotation, and a clear purpose statement, an agent has everything needed to invoke this tool correctly. No critical gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description does not need to explain parameters. The description adds no parameter-specific semantics beyond the schema's thorough documentation, meriting the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('tags from a CERN GitLab repository'), and clarifies return content ('tag names with their associated commit references'). It does not explicitly differentiate from sibling tools like list_branches or list_releases, so not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear use case ('finding version history and release points') but gives no exclusion criteria or pointers to alternatives. An agent is not told when to prefer list_releases or list_branches over this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for code snippets across CERN GitLab repositories. Can search globally across all public projects or within a specific project. Returns matching files with line-level context. Useful for finding usage examples of specific libraries, functions, or patterns.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | Optional: Git branch or tag to search within | |
| page | No | Page number to retrieve | |
| scope | No | 'blobs' searches file content (default), 'filenames' searches only file names | blobs |
| project | No | Optional: limit search to a specific project (ID or path). If omitted, searches across all public projects. | |
| per_page | No | Number of results to return | |
| search_term | Yes | The code or text to search for |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint and openWorldHint, which are consistent with the description. The description adds useful behavior beyond those hints: it can search globally or within a specific project, and it returns matching files with line-level context. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no filler. The core action and scope are front-loaded, followed by return value and typical use case. Every sentence adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with complete parameter schemas and an output schema, the description covers the essential purpose, scoping options, and return format. Pagination and ref details are already in the schema, so nothing critical is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already fully documented. The description slightly reinforces the project parameter's global-vs-scoped behavior but does not add meaningful semantics beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Search') and resource ('code snippets across CERN GitLab repositories'), clearly distinguishing it from sibling tools like search_projects and search_issues. The description also clarifies the two modes (global vs project-scoped) and the return type (files with line-level context).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: 'Useful for finding usage examples of specific libraries, functions, or patterns.' It implies when to use this tool, though it does not explicitly name alternatives or say when not to use it. The global/project scope options add practical usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for issues and discussions in CERN GitLab projects. Useful for understanding how a library is used, finding solution to common errors, or checking if a feature is supported.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Filter by issue state | all |
| project | No | Optional: limit search to a specific project. If omitted, searches across all projects you have access to. | |
| per_page | No | Number of results to return | |
| search_term | Yes | Keywords to search for in issue titles and descriptions |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description adds that the scope is issues/discussions rather than code and targets CERN GitLab projects. It doesn't mention default state, cross-project behavior, or pagination, though these are covered by the schema. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, with the core function stated first and practical use cases second. There is no filler and no repetition of schema fields or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with fully described parameters and an output schema, the description supplies the missing decision context: what kind of content is searched and when the tool is useful. Nothing necessary to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters have schema descriptions, so the schema carries the semantic weight and the baseline is 3. The description reinforces the purpose of search_term through use cases but adds no parameter-specific meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Search') with a clear resource ('issues and discussions in CERN GitLab projects'). Differentiates from siblings like search_code and search_projects by naming the content type being searched.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete use cases such as 'understanding how a library is used, finding solution to common errors, or checking if a feature is supported,' which tells an agent when this tool is appropriate. It doesn't explicitly name alternative tools or exclusion criteria, so it stops short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for code snippets within a specific LHCb software stack (e.g., 'sim11'). Automatically resolves the correct Git references for projects in that stack.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | Optional: Override the Git branch or tag to search within. If omitted, uses the branch matching the stack. | |
| page | No | Page number to retrieve | |
| scope | No | 'blobs' searches file content (default), 'filenames' searches only file names | blobs |
| stack | Yes | Name of the software stack (e.g. 'sim11') | |
| project | No | Optional: limit search to a specific project (ID or path). If omitted, searches across all public projects using default refs. | |
| per_page | No | Number of results to return | |
| search_term | Yes | The code or text to search for |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation is read-only and open-world, so safety is covered. The description adds meaningful behavioral context beyond annotations: it automatically resolves the correct Git references for stack projects, which is non-obvious and affects how callers should think about the ref parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The core purpose is front-loaded and the most significant behavioral nuance, automatic ref resolution, is included without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema, annotations, and presence of an output schema, the description covers the essential purpose and the main non-obvious behavior. It could be slightly more complete by distinguishing itself from the sibling search_code tool, but what is needed to invoke it correctly is largely present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 value by clarifying the relationship between stack and ref: the stack determines the default Git reference, and the tool resolves it automatically. This goes beyond the individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for code snippets within a specific LHCb software stack and adds the distinctive behavior of automatically resolving Git references. It effectively distinguishes itself from general code search tools like search_code, though it does not explicitly name any sibling as an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case: searching code within an LHCb stack without manually specifying Git refs. However, it does not explicitly state when not to use this tool or mention alternative tools such as search_code or search_projects, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for public CERN GitLab projects (which contain repositories, issues, wikis, etc.) by keywords, topics, or programming language. Useful for discovering HEP code, analysis frameworks, and physics tools.
| Name | Required | Description | Default |
|---|---|---|---|
| order | No | Sort order | desc |
| query | No | Search query string (matches project name, description, etc.) | |
| topic | No | Filter by project topic/tag (e.g. 'physics', 'root', 'atlas') | |
| sort_by | No | Sort results by this field | last_activity_at |
| language | No | Filter by primary programming language (e.g. 'python', 'c++', 'java') | |
| per_page | No | Number of results to return |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds meaningful constraints beyond the readOnlyHint/openWorldHint annotations by specifying that only 'public CERN GitLab projects' are searched and that matching is by keywords/topics/language. This tells the agent about the restricted scope and that no private-project access is involved. No mention of pagination or response structure, but output schema covers the response and the safety profile is already annotated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundant information; the first front-loads the tool's function and scope, the second adds a use-case signal. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with a complete input schema and an output schema, the description covers the core purpose, public scope, and typical applications. It doesn't explicitly route between search_* siblings, which is the main remaining gap, but the resource-level wording ('projects' vs. code/issues) gives strong contextual hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the description's mention of keywords/topics/language mirrors the query, topic, and language parameters without adding new syntax or edge-case details. Baseline of 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Search'), a specific resource ('public CERN GitLab projects'), and the available filter dimensions (keywords, topics, language). It also clarifies that projects contain repositories/issues/wikis, which helps distinguish from code- or issue-level search tools, though it doesn't name sibling alternatives explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Useful for discovering HEP code, analysis frameworks, and physics tools' conveys typical use cases but doesn't state when to prefer search_projects over search_code, search_issues, or search_lhcb_stack, nor any exclusion criteria. Usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Test connectivity to the CERN GitLab instance. Returns the GitLab version, authentication status, and connection health.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the readOnlyHint annotation by specifying the behavioral outputs: GitLab version, authentication status, and connection health. It does not contradict the annotation, and for a read-only connectivity check this is sufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the core purpose and the key return values. Every word earns its place; there is no filler or repetition of schema/annotation data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless connectivity check with a readOnly annotation and an output schema, the description is complete. It tells the agent what the operation does and what information it will receive, leaving no critical gap for selecting or invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema carries no parameter documentation burden. The description correctly implies no inputs are needed, and there is nothing more to add.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Test connectivity') on a specific resource ('the CERN GitLab instance') and lists the expected results (GitLab version, authentication status, connection health). It is easily distinguishable from the sibling tools, which focus on searching and retrieving specific data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as a health/connectivity check, which is the only tool of its kind among the siblings. It gives clear context for when it would be useful, though it does not explicitly state to run it before other operations or mention what to do on failure.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct resource or action: projects, files, code, issues, wiki, releases, branches, tags, and connectivity. Even the multiple search tools are clearly separated by search surface (projects, global code, LHCb stack, issues). The only mild overlap is between get_file_content and get_project_readme, but the README tool's auto-detection makes it a clearly specialized convenience function.
Tool names consistently follow a verb_noun snake_case pattern: get_, list_, search_, test_connectivity, and inspect_project. Verbs are predictable by action type, and no naming convention mixing or irregular casing is present.
At 15 tools, the set sits at the upper boundary of the ideal range, but each tool still earns a place given the breadth of read-only GitLab exploration. It is slightly heavy, especially with niche additions like search_lhcb_stack, but not bloated or redundant.
The tool surface covers project discovery, file browsing, code search, issues, wiki, releases, branches, tags, and project inspection, which forms a strong read-oriented workflow. Missing merge requests, commit history, and diff access are notable gaps for full GitLab coverage, but they are outside the apparent exploration-focused scope.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Go MCP server for GitLab: 2 dynamic tools reach 1000+ REST/GraphQL actions. Free/CE, no paid tier.
The CustomGPT.ai MCP server is a fully managed, RAG-powered endpoint that connects large language models with private knowledge bases and external data sources. It provides tools for retrieval-augmented generation queries (send_message), data ingestion (upload_file), and source listing, enabling AI agents to query private documents like PDFs with high accuracy and real-time citations.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/MohamedElashri/cerngitlab-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
