cern-opendata-mcp-server

Search CERN Open Data Records

cern_opendata_search_records

Read-onlyIdempotent

Search the CERN Open Data Portal's datasets, software, environments, documentation and supplementary records with exact-vocabulary filters and an optional full-text query. The filters are experiment, record type, physics category, keyword, collision energy and type, file format, data-taking year, event count, availability, collection, and LHCb magnet polarity, stripping stream and stripping version. Returns compact hits with recids plus live facet counts. Each facet ignores its own filter, so its counts show the alternatives under the other filters. Filter values are exact upstream; common spellings are normalized, and cern_opendata_list_reference lists the vocabulary. Paging reaches the first 10,000 matches.

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

Input Schema

Name	Required	Description
`page`	No	Page number, from 1, counting pages of the limit applied. page × limit may not exceed 10,000.
`sort`	No	bestmatch (relevance), mostrecent (by date_published, newest first), title (A-Z) or title_desc (Z-A). Omitted: bestmatch with a query, mostrecent (newest first) without.
`type`	No	Up to 7 types (OR): Dataset, Documentation, Environment, Software, Supplementaries, News, or Primary::Secondary (Dataset::Collision, Dataset::Simulated). Omit for all six primaries; Glossary is excluded.
`limit`	No	Hits per page, 1-50. A value above 50 is served at 50.
`query`	No	Verbatim OpenSearch query_string: AND between terms, double weight for title matches. Supports title:"…", recid:(1 OR 2), run_period:("Run2012B"); cern_opendata_list_reference topic query_syntax lists forms. Omit for filters alone.
`year_to`	No	Inclusive latest data-taking year; alone means through this year.
`category`	No	Up to 20 simulated-dataset categories (OR): primary (Exotica, Higgs Physics, Standard Model Physics, Supersymmetry) or Primary::Secondary (Higgs Physics::Standard Model). Case/separator normalized. Commas stay within an item (Exotica::Heavy Fermions, Heavy Righ-Handed Neutrinos). Heavy-Ion Physics also matches its leading-space spelling. cern_opendata_list_reference topic categories lists all values.
`keywords`	No	Up to 10 verbatim, case-sensitive keywords (OR); Education differs from education. A comma within a keyword stays in one item.
`file_type`	No	Up to 20 formats/data tiers (OR): nanoaod, miniaod, aod, root, DAOD_PHYSLITE, csv, etc. Known-value case normalized.
`year_from`	No	Inclusive earliest data-taking year; alone means onward. For one year, set both year bounds to it.
`collection`	No	Up to 10 exact, case-sensitive collections (OR), e.g. CMS-Validated-Runs; copy a record's collections spellings.
`experiment`	No	Up to 9 experiments (OR): ALICE, ATLAS, CMS, DELPHI, JADE, LHCb, OPERA, PHENIX, TOTEM. Case normalized.
`max_events`	No	Maximum number of events, inclusive.
`min_events`	No	Minimum number of events, inclusive.
`availability`	No	Up to 4 availability states (OR): online, partial, ondemand (tape; request before download), requested.
`collision_type`	No	Up to 6 collision types (OR): pp, PbPb, pPb, e+e-, Interfill. PbPb also matches Pb-Pb.
`magnet_polarity`	No	Up to 2 LHCb collision-dataset polarities (OR): MagDown, MagUp. Case normalized.
`collision_energy`	No	Up to 15 energies (OR), e.g. 7TeV, 8TeV, 13TeV, 5.02TeV. "13TeV, 13.6TeV" is one value/item.
`stripping_stream`	No	Up to 11 LHCb stripping streams (OR), e.g. BHADRON, CHARM, DIMUON, EW, LEPTONIC; also matches stripping docs. Case normalized. cern_opendata_list_reference topic lhcb lists them.
`stripping_version`	No	Up to 12 LHCb stripping versions (OR), e.g. stripping21, stripping21r1p2. Case normalized.

Output Schema

Name	Required	Description
`cap`	No	The page size (limit) applied to this call.
`hits`	No	Matching records on this page.
`page`	No	The page returned.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of items returned on this page.
`facets`	No	Live counts under all other filters: each facet ignores its own filter. Terms list 10 values alphabetically (file_type: 100); type and category buckets list 10 secondary values. Overflow fields sum counts past these caps, counting a record once per value; other_count is 0 for year and number_events. cern_opendata_list_reference topics record_types/categories list all secondary values; a Primary::Secondary filter gives its record count as totalCount.
`notice`	No	Continuation, empty-result guidance or result caveats; absent when none.
`has_more`	No	Next page has matches within the first 10,000; false at the reachable end even if more exist (see truncated/notice).
`truncated`	No	True when more results remain past this page; notice says how to reach them.
`totalCount`	No	Total matches for the query and filters.
`applied_filters`	No	The filters as the server applied them.

Schema Changelog

Changes observed during successful MCP inspections.

Changed21 schema fields changedOct 30, 2026

changedInput schema / properties / availability / description

Previous value: -"Record availability (OR): online, partial, ondemand (on tape, requested before download) or requested. Up to 4."New value: +"Up to 4 availability states (OR): online, partial, ondemand (tape; request before download), requested."

changedInput schema / properties / category / description

Previous value: -"Physics categories of simulated datasets (OR): a primary such as Exotica, Higgs Physics, Standard Model Physics or Supersymmetry, or Primary::Secondary such as Higgs Physics::Standard Model. Up to 20; case and the separator are normalized, and a value holding a comma (Exotica::Heavy Fermions, Heavy Righ-Handed Neutrinos) is one item. Heavy-Ion Physics also matches its leading-space spelling. cern_opendata_list_reference topic categories lists every value."New value: +"Up to 20 simulated-dataset categories (OR): primary (Exotica, Higgs Physics, Standard Model Physics, Supersymmetry) or Primary::Secondary (Higgs Physics::Standard Model). Case/separator normalized. Commas stay within an item (Exotica::Heavy Fermions, Heavy Righ-Handed Neutrinos). Heavy-Ion Physics also matches its leading-space spelling. cern_opendata_list_reference topic categories lists all values."

changedInput schema / properties / collection / description

Previous value: -"Portal collections (OR), exact and case-sensitive, such as CMS-Validated-Runs; copy spellings from a record's collections field. Up to 10."New value: +"Up to 10 exact, case-sensitive collections (OR), e.g. CMS-Validated-Runs; copy a record's collections spellings."

changedInput schema / properties / collision_energy / description

Previous value: -"Collision energies (OR), such as 7TeV, 8TeV, 13TeV or 5.02TeV. Up to 15; \"13TeV, 13.6TeV\" is one upstream value and one item."New value: +"Up to 15 energies (OR), e.g. 7TeV, 8TeV, 13TeV, 5.02TeV. \"13TeV, 13.6TeV\" is one value/item."

changedInput schema / properties / collision_type / description

Previous value: -"Collision types (OR): pp, PbPb, pPb, e+e-, Interfill. PbPb also matches the Pb-Pb spelling. Up to 6."New value: +"Up to 6 collision types (OR): pp, PbPb, pPb, e+e-, Interfill. PbPb also matches Pb-Pb."

changedInput schema / properties / experiment / description

Previous value: -"Experiments (OR): ALICE, ATLAS, CMS, DELPHI, JADE, LHCb, OPERA, PHENIX, TOTEM. Up to 9; case is normalized."New value: +"Up to 9 experiments (OR): ALICE, ATLAS, CMS, DELPHI, JADE, LHCb, OPERA, PHENIX, TOTEM. Case normalized."

changedInput schema / properties / file_type / description

Previous value: -"File formats and data tiers (OR), such as nanoaod, miniaod, aod, root, DAOD_PHYSLITE or csv. Up to 20; case is normalized for known values."New value: +"Up to 20 formats/data tiers (OR): nanoaod, miniaod, aod, root, DAOD_PHYSLITE, csv, etc. Known-value case normalized."

changedInput schema / properties / keywords / description

Previous value: -"Record keywords (OR), exact and case-sensitive (Education and education differ), sent as given. Up to 10; a keyword holding a comma is one item."New value: +"Up to 10 verbatim, case-sensitive keywords (OR); Education differs from education. A comma within a keyword stays in one item."

changedInput schema / properties / magnet_polarity / description

Previous value: -"LHCb magnet polarities (OR): MagDown or MagUp, set on LHCb collision datasets. Up to 2; case is normalized."New value: +"Up to 2 LHCb collision-dataset polarities (OR): MagDown, MagUp. Case normalized."

changedInput schema / properties / query / description

Previous value: -"Full-text query, sent verbatim as an OpenSearch query_string (AND between terms; title matches weigh double). Field forms such as title:\"…\", recid:(1 OR 2) or run_period:(\"Run2012B\") work; cern_opendata_list_reference with topic query_syntax lists them. Omit to browse by filters alone."New value: +"Verbatim OpenSearch query_string: AND between terms, double weight for title matches. Supports title:\"…\", recid:(1 OR 2), run_period:(\"Run2012B\"); cern_opendata_list_reference topic query_syntax lists forms. Omit for filters alone."

changedInput schema / properties / stripping_stream / description

Previous value: -"LHCb stripping streams (OR), such as BHADRON, CHARM, DIMUON, EW or LEPTONIC; they also match LHCb stripping documentation. Up to 11; case is normalized. cern_opendata_list_reference topic lhcb lists them."New value: +"Up to 11 LHCb stripping streams (OR), e.g. BHADRON, CHARM, DIMUON, EW, LEPTONIC; also matches stripping docs. Case normalized. cern_opendata_list_reference topic lhcb lists them."

changedInput schema / properties / stripping_version / description

Previous value: -"LHCb stripping versions (OR), such as stripping21 or stripping21r1p2. Up to 12; case is normalized."New value: +"Up to 12 LHCb stripping versions (OR), e.g. stripping21, stripping21r1p2. Case normalized."

changedInput schema / properties / type / description

Previous value: -"Record types (OR): a primary (Dataset, Documentation, Environment, Software, Supplementaries, News) or Primary::Secondary such as Dataset::Collision or Dataset::Simulated. Up to 7. Omit for every served type; Glossary is not served."New value: +"Up to 7 types (OR): Dataset, Documentation, Environment, Software, Supplementaries, News, or Primary::Secondary (Dataset::Collision, Dataset::Simulated). Omit for all six primaries; Glossary is excluded."

changedInput schema / properties / year_from / description

Previous value: -"Earliest data-taking year, inclusive. Alone, it means this year onward; for one year, set year_from and year_to to it."New value: +"Inclusive earliest data-taking year; alone means onward. For one year, set both year bounds to it."

changedInput schema / properties / year_to / description

Previous value: -"Latest data-taking year, inclusive. Alone, it means up to this year."New value: +"Inclusive latest data-taking year; alone means through this year."

changedOutput schema / properties / facets / description

Previous value: -"Live facet counts. Each facet ignores its own filter, so its counts show the alternatives under the other filters. Terms facets list the first 10 values alphabetically (file_type up to 100), and type and category buckets their first 10 secondary values. other_count, subtypes_other_count and subcategories_other_count sum the counts of the values past those caps, so a record holding several of them counts once per value; other_count is 0 for year and number_events. cern_opendata_list_reference topics record_types and categories list every secondary value, and a Primary::Secondary type or category filter returns its record count as totalCount."New value: +"Live counts under all other filters: each facet ignores its own filter. Terms list 10 values alphabetically (file_type: 100); type and category buckets list 10 secondary values. Overflow fields sum counts past these caps, counting a record once per value; other_count is 0 for year and number_events. cern_opendata_list_reference topics record_types/categories list all secondary values; a Primary::Secondary filter gives its record count as totalCount."

changedOutput schema / properties / has_more / description

Previous value: -"True when the next page holds matches and lies within the first 10,000. False on the last reachable page even when more matches exist; truncated and notice say so."New value: +"Next page has matches within the first 10,000; false at the reachable end even if more exist (see truncated/notice)."

changedOutput schema / properties / hits / items / properties / type / description

Previous value: -"Record type as the portal classifies it."New value: +"Portal record classification."

changedOutput schema / properties / hits / items / properties / type / properties / primary / description

Previous value: -"Primary type: Dataset, Software, Environment, Documentation, Supplementaries or News. Empty when the record states none."New value: +"Dataset, Software, Environment, Documentation, Supplementaries or News; empty when unstated."

changedOutput schema / properties / hits / items / properties / type / properties / secondary / description

Previous value: -"Secondary types, such as Collision or Simulated; empty when none."New value: +"Secondary types (Collision, Simulated, etc.); empty when none."

changedOutput schema / properties / notice / description

Previous value: -"Guidance for the next call: how to page on, why nothing matched and what to change, or a caveat about the results."New value: +"Continuation, empty-result guidance or result caveats; absent when none."

Changed32 schema fields changedOct 18, 2026

changedInput schema / properties / availability / description

Previous value: -"Record availability (OR): online, partial, ondemand (on tape, requested before download) or requested. Array or comma-separated string, up to 4."New value: +"Record availability (OR): online, partial, ondemand (on tape, requested before download) or requested. Up to 4."

changedInput schema / properties / category / description

Previous value: -"Physics categories of simulated datasets (OR): a primary such as Exotica, Higgs Physics, Standard Model Physics or Supersymmetry, or Primary::Secondary such as Higgs Physics::Standard Model. Array or comma-separated string, up to 20; case and the separator are normalized, and a known value holding a comma is kept whole. Heavy-Ion Physics also matches its leading-space spelling. cern_opendata_list_reference topic categories lists every value."New value: +"Physics categories of simulated datasets (OR): a primary such as Exotica, Higgs Physics, Standard Model Physics or Supersymmetry, or Primary::Secondary such as Higgs Physics::Standard Model. Up to 20; case and the separator are normalized, and a value holding a comma (Exotica::Heavy Fermions, Heavy Righ-Handed Neutrinos) is one item. Heavy-Ion Physics also matches its leading-space spelling. cern_opendata_list_reference topic categories lists every value."

changedInput schema / properties / collection / description

Previous value: -"Portal collections (OR), exact and case-sensitive, such as CMS-Validated-Runs; copy spellings from a record's collections field. Array or comma-separated string, up to 10."New value: +"Portal collections (OR), exact and case-sensitive, such as CMS-Validated-Runs; copy spellings from a record's collections field. Up to 10."

changedInput schema / properties / collision_energy / description

Previous value: -"Collision energies (OR), such as 7TeV, 8TeV, 13TeV or 5.02TeV. Array or comma-separated string, up to 15; \"13TeV, 13.6TeV\" is one upstream value and is kept whole."New value: +"Collision energies (OR), such as 7TeV, 8TeV, 13TeV or 5.02TeV. Up to 15; \"13TeV, 13.6TeV\" is one upstream value and one item."

changedInput schema / properties / collision_type / description

Previous value: -"Collision types (OR): pp, PbPb, pPb, e+e-, Interfill. PbPb also matches the Pb-Pb spelling. Array or comma-separated string, up to 6."New value: +"Collision types (OR): pp, PbPb, pPb, e+e-, Interfill. PbPb also matches the Pb-Pb spelling. Up to 6."

changedInput schema / properties / experiment / description

Previous value: -"Experiments (OR): ALICE, ATLAS, CMS, DELPHI, JADE, LHCb, OPERA, PHENIX, TOTEM. Array or comma-separated string, up to 9; case is normalized."New value: +"Experiments (OR): ALICE, ATLAS, CMS, DELPHI, JADE, LHCb, OPERA, PHENIX, TOTEM. Up to 9; case is normalized."

changedInput schema / properties / file_type / description

Previous value: -"File formats and data tiers (OR), such as nanoaod, miniaod, aod, root, DAOD_PHYSLITE or csv. Array or comma-separated string, up to 20; case is normalized for known values."New value: +"File formats and data tiers (OR), such as nanoaod, miniaod, aod, root, DAOD_PHYSLITE or csv. Up to 20; case is normalized for known values."

changedInput schema / properties / keywords / description

Previous value: -"Record keywords (OR), exact and case-sensitive (Education and education differ), sent as given. Array or comma-separated string, up to 10; pass a keyword holding a comma in an array."New value: +"Record keywords (OR), exact and case-sensitive (Education and education differ), sent as given. Up to 10; a keyword holding a comma is one item."

changedInput schema / properties / limit / description

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

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

changedInput schema / properties / magnet_polarity / description

Previous value: -"LHCb magnet polarities (OR): MagDown or MagUp, set on LHCb collision datasets. Array or comma-separated string, up to 2; case is normalized."New value: +"LHCb magnet polarities (OR): MagDown or MagUp, set on LHCb collision datasets. Up to 2; case is normalized."

changedInput schema / properties / page / description

Previous value: -"Page number, from 1. page × limit may not exceed 10,000."New value: +"Page number, from 1, counting pages of the limit applied. page × limit may not exceed 10,000."

changedInput schema / properties / stripping_stream / description

Previous value: -"LHCb stripping streams (OR), such as BHADRON, CHARM, DIMUON, EW or LEPTONIC; they also match LHCb stripping documentation. Array or comma-separated string, up to 11; case is normalized. cern_opendata_list_reference topic lhcb lists them."New value: +"LHCb stripping streams (OR), such as BHADRON, CHARM, DIMUON, EW or LEPTONIC; they also match LHCb stripping documentation. Up to 11; case is normalized. cern_opendata_list_reference topic lhcb lists them."

changedInput schema / properties / stripping_version / description

Previous value: -"LHCb stripping versions (OR), such as stripping21 or stripping21r1p2. Array or comma-separated string, up to 12; case is normalized."New value: +"LHCb stripping versions (OR), such as stripping21 or stripping21r1p2. Up to 12; case is normalized."

changedInput schema / properties / type / description

Previous value: -"Record types (OR): a primary (Dataset, Documentation, Environment, Software, Supplementaries, News) or Primary::Secondary such as Dataset::Collision or Dataset::Simulated. Array or comma-separated string, up to 7. Omit for every served type; Glossary is not served."New value: +"Record types (OR): a primary (Dataset, Documentation, Environment, Software, Supplementaries, News) or Primary::Secondary such as Dataset::Collision or Dataset::Simulated. Up to 7. Omit for every served type; Glossary is not served."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_query`: query leaves a parenthesis, range bracket or double quote unbalanced, or ends in an escaping backslash (refused before any request); or the portal rejected the query string (invalid query syntax), or answered another 400 the server did not anticipate, whose upstream message is carried. `query_server_error`: Every attempt of a search with query set answered HTTP 500, as the portal does for some malformed queries in place of its 400 syntax rejection. `page_window_exceeded`: page × limit exceeds 10,000, the deepest match the portal pages to. `invalid_range`: year_from is after year_to, or min_events is above max_events. `rate_limited`: The portal's 60-a-minute budget is spent: it answered 429, or the request could not start within the call's deadline. data.retryAfter is set. `upstream_unreadable`: The portal answered with a body the server could not read: not JSON, missing the expected envelope, or over the byte ceiling (then data.retryable is false). Also raised when a search answers 404. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_query`: query leaves a parenthesis, range bracket or double quote unbalanced, or ends in an escaping backslash (refused before any request); or the portal rejected the query string (invalid query syntax), or answered another 400 the server did not anticipate, whose upstream message is carried. `query_server_error`: Every attempt of a search with query set answered HTTP 500, as the portal does for some malformed queries in place of its 400 syntax rejection. `page_window_exceeded`: page × limit, the limit applied (at most 50), exceeds 10,000, the deepest match the portal pages to. `invalid_range`: year_from is after year_to, or min_events is above max_events. `rate_limited`: The portal's 60-a-minute budget is spent: it answered 429, or the request could not start within the call's deadline. data.retryAfter is set. `upstream_unreadable`: The portal answered with a body the server could not read: not JSON, missing the expected envelope, or over the byte ceiling (then data.retryable is false). Also raised when a search answers 404. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / facets / description

Previous value: -"Live facet counts. Each facet ignores its own filter, so its counts show the alternatives under the other filters. Terms facets list the first 10 values alphabetically (file_type up to 100). other_count is 0 for year and number_events."New value: +"Live facet counts. Each facet ignores its own filter, so its counts show the alternatives under the other filters. Terms facets list the first 10 values alphabetically (file_type up to 100), and type and category buckets their first 10 secondary values. other_count, subtypes_other_count and subcategories_other_count sum the counts of the values past those caps, so a record holding several of them counts once per value; other_count is 0 for year and number_events. cern_opendata_list_reference topics record_types and categories list every secondary value, and a Primary::Secondary type or category filter returns its record count as totalCount."

changedOutput schema / properties / facets / properties / availability / properties / other_count / description

Previous value: -"Records past the bucket cap."New value: +"Summed count of the values past the bucket cap, not a record count."

added

Output schema / properties / facets / properties / category / properties / buckets / items / properties / subcategories_other_count

Added value: +{
+  "description": "Summed count of the secondary categories past the 10 listed, not a record count; absent when the list is whole.",
+  "type": "number"
+}

changedOutput schema / properties / facets / properties / category / properties / other_count / description

Previous value: -"Records past the bucket cap."New value: +"Summed count of the values past the bucket cap, not a record count."

changedOutput schema / properties / facets / properties / collision_energy / properties / other_count / description

Previous value: -"Records past the bucket cap."New value: +"Summed count of the values past the bucket cap, not a record count."

changedOutput schema / properties / facets / properties / collision_type / properties / other_count / description

Previous value: -"Records past the bucket cap."New value: +"Summed count of the values past the bucket cap, not a record count."

changedOutput schema / properties / facets / properties / experiment / properties / other_count / description

Previous value: -"Records past the bucket cap."New value: +"Summed count of the values past the bucket cap, not a record count."

changedOutput schema / properties / facets / properties / file_type / properties / other_count / description

Previous value: -"Records past the bucket cap."New value: +"Summed count of the values past the bucket cap, not a record count."

changedOutput schema / properties / facets / properties / keywords / properties / other_count / description

Previous value: -"Records past the bucket cap."New value: +"Summed count of the values past the bucket cap, not a record count."

changedOutput schema / properties / facets / properties / magnet_polarity / properties / other_count / description

Previous value: -"Records past the bucket cap."New value: +"Summed count of the values past the bucket cap, not a record count."

changedOutput schema / properties / facets / properties / number_events / properties / other_count / description

Previous value: -"Records past the bucket cap."New value: +"Summed count of the values past the bucket cap, not a record count."

changedOutput schema / properties / facets / properties / stripping_stream / properties / other_count / description

Previous value: -"Records past the bucket cap."New value: +"Summed count of the values past the bucket cap, not a record count."

changedOutput schema / properties / facets / properties / stripping_version / properties / other_count / description

Previous value: -"Records past the bucket cap."New value: +"Summed count of the values past the bucket cap, not a record count."

added

Output schema / properties / facets / properties / type / properties / buckets / items / properties / subtypes_other_count

Added value: +{
+  "description": "Summed count of the secondary types past the 10 listed, not a record count; absent when the list is whole.",
+  "type": "number"
+}

changedOutput schema / properties / facets / properties / type / properties / other_count / description

Previous value: -"Records past the bucket cap."New value: +"Summed count of the values past the bucket cap, not a record count."

changedOutput schema / properties / facets / properties / year / properties / other_count / description

Previous value: -"Records past the bucket cap."New value: +"Summed count of the values past the bucket cap, not a record count."

First observedOct 2, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare readOnly/openWorld/idempotent, so the bar is lower, but the description adds genuine non-structured behavior: compact hits with recids plus live facet counts, and the crucial detail that each facet ignores its own filter so counts show alternatives. It also discloses the 10,000-match paging ceiling. Rate limits or result-size behavior beyond that cap are not covered.

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?

Front-loaded with purpose, then behavior, then vocabulary/paging caveats – logical ordering with no filler sentences. The long enumeration of filter dimensions partially duplicates the schema and could be trimmed, keeping it below a 5.

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 20-parameter tool with an output schema and full annotation coverage, the description supplies the missing operational context: vocabulary source, normalization behavior, facet semantics, and the 10,000-match paging limit. An agent has everything needed to call it correctly without trial and error.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema itself documents every filter, enum, maxItems and normalization rule, making 3 the baseline. The description adds only marginal param-level insight (exact upstream values, spelling normalization, facet self-exclusion) and largely restates the filter list already in structured data.

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 (Search) applied to a precisely enumerated resource set (datasets, software, environments, documentation, supplementary records) with the filterable dimensions named. An agent can distinguish this from cern_opendata_get_records (lookup by recid) and cern_opendata_search_trigger_paths without opening a schema.

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

Usage Guidelines4/5

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

Gives concrete usage context: filters are exact-vocabulary, common spellings are normalized, cern_opendata_list_reference is named as the vocabulary source, and paging is capped at the first 10,000 matches. It also implies filters-alone usage ('optional full-text query'). It stops short of explicitly excluding siblings like get_records, so not a 5.

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.