cern-opendata-mcp-server

List CERN Open Data Record Files

cern_opendata_list_files

Read-onlyIdempotent

List one record's files: its file indexes (groups of up to ~1,500 files) with their XRootD URI-list URLs, and per file the XRootD URI, HTTPS download URL, size, adler32 checksum and availability. Without index, returns the record's indexes and its regular files; with index, reads only that index and pages through its files. Files marked on demand sit on tape and must be requested on the record's portal page before download.

Input Schema

TableJSON Schema

Name	Required	Description
`index`	No	A file index key from the indexes list, matched exactly (a .txt ending is read as .json). Omit to list the record's indexes and regular files.
`limit`	No	Files per page, 1-500. A value above 500 is served at 500.
`recid`	Yes	Record id: up to 12 digits (6004), optionally after a lowercase experiment prefix (atlas-160006). cern_opendata_search_records and cern_opendata_get_records return it.
`cursor`	No	next_cursor from the previous page, unchanged, with the same recid and index. Omit for the first page.

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	The page size (limit) applied to this call.
`error`	No	Present when the call failed. Absent on success.
`files`	No	This page of files: regular files in record scope, the index's files in index scope.
`recid`	No	The record id.
`scope`	No	record: the record's indexes and regular files; index: one index's files.
`shown`	No	Number of items returned on this page.
`title`	No	Record title.
`notice`	No	Guidance for the next call: how to page on, why nothing matched and what to change, or a caveat about the results.
`indexes`	No	Every file index in record scope; only the selected one in index scope.
`children`	No	Set only for an umbrella record holding no files itself: the child recids whose files make it up. Empty otherwise.
`has_more`	No	True when more files remain past this page.
`truncated`	No	True when more results remain past this page; notice says how to reach them.
`portal_url`	No	The record page, where on-demand (tape) files are requested.
`totalCount`	No	Files in scope: regular files in record scope, index files in index scope.
`next_cursor`	No	Pass as cursor, with the same recid and index, for the next page.
`availability`	No	Record-level availability: online, partial, ondemand or requested.
`availability_details`	No	File counts by availability state for the whole record.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 18, 2026

changedInput schema / properties / limit / description

Previous value: -"Files per page, 1-500."New value: +"Files per page, 1-500. A value above 500 is served at 500."

changedInput schema / properties / limit / maximum
```
Previous value: -500New value: +10000
```

changedInput schema / properties / recid / description

Previous value: -"Record id: up to 12 digits (6004), optionally after an experiment prefix (atlas-160006); recid:6004 or a portal record URL also work. cern_opendata_search_records and cern_opendata_get_records return it."New value: +"Record id: up to 12 digits (6004), optionally after a lowercase experiment prefix (atlas-160006). cern_opendata_search_records and cern_opendata_get_records return it."

First observedOct 2, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only cover read-only/idempotent/open-world safety, and the description adds real operational context: indexes group up to ~1,500 files, results are paged, and on-demand files are tape-resident and require a portal request before download. That tape caveat is exactly the kind of prerequisite the annotations cannot express.

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 sentences, front-loaded with the core action and result fields, then the index/no-index branch, then the tape caveat. Dense but every clause carries operational information; the first sentence is somewhat long, so not maximally tight.

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 4-parameter read tool with an output schema present, the description supplies everything an agent needs: what is returned, how index toggles the result set, paging behavior, and the on-demand download precondition. Return-value detail need not be duplicated since an output schema exists.

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 meaning beyond the schema by explaining the semantic effect of index (changes the result shape and enables paging) and the paging relationship between limit and cursor. It does not restate the recid prefix syntax or the 500-cap nuance already in the schema.

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 ('List one record's files') and immediately scopes what 'files' means: file indexes with URI-list URLs plus per-file XRootD/HTTPS URIs, size, checksum and availability. This is clearly distinguishable from siblings like search_records and get_records, which operate on records rather than a record's file listing.

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?

The description gives explicit conditional usage: omit index to get the record's indexes and regular files, supply index to read just that index and page through it. It also warns that on-demand files sit on tape and must be requested on the portal before download. It stops short of naming alternative tools or saying when not to call it, so it is clear context rather than full routing guidance.

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

All cern-opendata-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.