cern-inspire-mcp-server

Export INSPIRE citations

cern_inspire_export_citations

Read-onlyIdempotent

Export INSPIRE-HEP's citation entries for the papers a literature query selects, as BibTeX or LaTeX \bibitem entries (EU or US style), keyed by INSPIRE texkeys and ready to paste into a bibliography. Name specific papers with "recid:451647 or arxiv:1207.7214 or doi:10.1016/…", or export a topic, author, or citing set with any query cern_inspire_search_literature accepts. Up to 50 entries per page; page through larger sets (only the first 10,000 matches are reachable). Entries are INSPIRE's verbatim text (long author lists arrive abbreviated as "First, Name and others").

Input Schema

TableJSON Schema

Name	Required	Description	Default
`page`	No	Page number, starting at 1. page × size may not exceed 10,000.
`size`	No	Entries per page (1–50, default 10).
`sort`	No	Entry order: relevance (default), mostrecent, or mostcited.	relevance
`query`	Yes	Literature query selecting the papers to cite, narrowed by the same document_types, subjects, year_from and year_to filters as search. Named papers: "recid:451647 or arxiv:1207.7214 or doi:10.1016/j.physletb.2012.08.020". Or a topic ("t higgs and topcite 500+"), an author ("a Edward.Witten.1"), or citing papers ("refersto:recid:451647"). Empty recognized field clauses such as "a:" are invalid; other syntax is passed through without complete grammar validation. See cern_inspire_list_reference topic search_syntax.
`format`	No	Entry format: bibtex (default), latex-eu, or latex-us (\bibitem entries in European or US style).	bibtex
`year_to`	No	Latest year to include (1900–2100, inclusive), matched on the earliest date INSPIRE records for the paper. Omit for no upper bound.
`subjects`	No	Restrict to INSPIRE subject categories (up to 4). Multiple values must ALL hold, not either. Values: Astrophysics, Phenomenology-HEP, Theory-HEP, Quantum Physics, Unknown, Gravitation and Cosmology, Experiment-HEP, Theory-Nucl, Accelerators, Instrumentation, General Physics, Experiment-Nucl, Math and Math Physics, Condensed Matter, Computing, Lattice, Other, Data Analysis and Statistics.
`year_from`	No	Earliest year to include (1900–2100, inclusive), matched on the earliest date INSPIRE records for the paper. Omit for no lower bound.
`document_types`	No	Restrict to INSPIRE document types (up to 4). Multiple values must ALL hold (published + review = published reviews), not either. Values: article, published, conference paper, thesis, review, note, proceedings, lectures, book chapter, book, introductory, activity report, report.

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	The page size applied.
`page`	No	The page returned.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of entries on this page.
`format`	No	The entry format returned.
`notice`	No	Guidance when nothing matched, the page is past the last or came back empty inside the match count, more papers follow, or the page could not be checked against the match count.
`entries`	No	Citation entries, in the requested order.
`nextPage`	No	The page number to request next, when more papers follow within the 10,000-result window.
`truncated`	No	True when more matched papers follow this page.
`appliedFilters`	No	Sort and filters applied, or "none".

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedOct 16, 2026

addedInput schema / properties / document_types

Added value: +{
+  "description": "Restrict to INSPIRE document types (up to 4). Multiple values must ALL hold (published + review = published reviews), not either. Values: article, published, conference paper, thesis, review, note, proceedings, lectures, book chapter, book, introductory, activity report, report.",
+  "items": {
+    "description": "An INSPIRE document type.",
+    "enum": [
+      "article",
+      "published",
+      "conference paper",
+      "thesis",
+      "review",
+      "note",
+      "proceedings",
+      "lectures",
+      "book chapter",
+      "book",
+      "introductory",
+      "activity report",
+      "report"
+    ],
+    "type": "string"
+  },
+  "maxItems": 4,
+  "type": "array"
+}

changedInput schema / properties / query / description

Previous value: -"Literature query selecting the papers to cite. Named papers: \"recid:451647 or arxiv:1207.7214 or doi:10.1016/j.physletb.2012.08.020\". Or any INSPIRE query: a topic (\"t higgs and topcite 500+\"), an author (\"a Edward.Witten.1\"), or the papers citing a record (\"refersto:recid:451647\"). See cern_inspire_list_reference topic search_syntax."New value: +"Literature query selecting the papers to cite, narrowed by the same document_types, subjects, year_from and year_to filters as search. Named papers: \"recid:451647 or arxiv:1207.7214 or doi:10.1016/j.physletb.2012.08.020\". Or a topic (\"t higgs and topcite 500+\"), an author (\"a Edward.Witten.1\"), or citing papers (\"refersto:recid:451647\"). Empty recognized field clauses such as \"a:\" are invalid; other syntax is passed through without complete grammar validation. See cern_inspire_list_reference topic search_syntax."

addedInput schema / properties / subjects

Added value: +{
+  "description": "Restrict to INSPIRE subject categories (up to 4). Multiple values must ALL hold, not either. Values: Astrophysics, Phenomenology-HEP, Theory-HEP, Quantum Physics, Unknown, Gravitation and Cosmology, Experiment-HEP, Theory-Nucl, Accelerators, Instrumentation, General Physics, Experiment-Nucl, Math and Math Physics, Condensed Matter, Computing, Lattice, Other, Data Analysis and Statistics.",
+  "items": {
+    "description": "An INSPIRE subject category.",
+    "enum": [
+      "Astrophysics",
+      "Phenomenology-HEP",
+      "Theory-HEP",
+      "Quantum Physics",
+      "Unknown",
+      "Gravitation and Cosmology",
+      "Experiment-HEP",
+      "Theory-Nucl",
+      "Accelerators",
+      "Instrumentation",
+      "General Physics",
+      "Experiment-Nucl",
+      "Math and Math Physics",
+      "Condensed Matter",
+      "Computing",
+      "Lattice",
+      "Other",
+      "Data Analysis and Statistics"
+    ],
+    "type": "string"
+  },
+  "maxItems": 4,
+  "type": "array"
+}

addedInput schema / properties / year_from

Added value: +{
+  "description": "Earliest year to include (1900–2100, inclusive), matched on the earliest date INSPIRE records for the paper. Omit for no lower bound.",
+  "maximum": 2100,
+  "minimum": 1900,
+  "type": "integer"
+}

addedInput schema / properties / year_to

Added value: +{
+  "description": "Latest year to include (1900–2100, inclusive), matched on the earliest date INSPIRE records for the paper. Omit for no upper bound.",
+  "maximum": 2100,
+  "minimum": 1900,
+  "type": "integer"
+}

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "format",
-      "page",
-      "entries",
-      "truncated",
-      "shown",
-      "cap"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "format",
+      "page",
+      "entries",
+      "appliedFilters",
+      "truncated",
+      "shown",
+      "cap"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / appliedFilters

Added value: +{
+  "description": "Sort and filters applied, or \"none\".",
+  "type": "string"
+}

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `beyond_result_window`: page × size exceeds the 10,000 results INSPIRE serves for one query. `invalid_query`: INSPIRE answered 400 to a parameter value it refuses. `inspire_rate_limited`: INSPIRE returned 429 after the pacer and retries. `pacer_shed`: The server's outbound INSPIRE queue could not start the request within the call's remaining budget. `upstream_unreadable`: The INSPIRE body exceeded the byte ceiling, or was JSON or HTML where citation text was expected. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_year_range`: year_from is later than year_to. `beyond_result_window`: page × size exceeds the 10,000 results INSPIRE serves for one query. `invalid_query`: A recognized field clause has no value, or INSPIRE answered 400 to a parameter value it refuses. `inspire_rate_limited`: INSPIRE returned 429 after the pacer and retries. `pacer_shed`: The server's outbound INSPIRE queue could not start the request within the call's remaining budget. `upstream_unreadable`: The INSPIRE body exceeded the byte ceiling, or was JSON or HTML where citation text was expected. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "beyond_result_window",
-  "invalid_query",
-  "inspire_rate_limited",
-  "pacer_shed",
-  "upstream_unreadable"
-]New value: +[
+  "invalid_year_range",
+  "beyond_result_window",
+  "invalid_query",
+  "inspire_rate_limited",
+  "pacer_shed",
+  "upstream_unreadable"
+]

First observedOct 2, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Beyond the annotations (readOnly/openWorld/idempotent), the description discloses the 10,000-reachable-match cap and that entries are INSPIRE's verbatim text with long author lists abbreviated as 'Name and others'. It does not detail error behavior or the response envelope, but it adds real operational context.

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-loads what is exported and the formats before moving to selection syntax and limits; every sentence carries information. The inline example strings make it dense, but nothing is wasted or redundant.

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?

An output schema exists, so return-value shape need not be explained, and the description still covers formats, selection syntax, pagination limits, and data quirks. Nothing an agent needs to call this correctly is missing.

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 3 is the baseline, but the description contributes extra query-syntax examples ('t higgs and topcite 500+', 'a Edward.Witten.1', 'refersto:recid:451647') and the invalid-clause rule for empty fields like 'a:'. This goes beyond what the schema documents.

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+resource (export INSPIRE citation entries for query-selected papers) and the output formats (BibTeX, LaTeX \bibitem, EU/US style). It is clearly distinct from siblings like cern_inspire_search_literature, which returns records rather than paste-ready citations.

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 selection modes (named paper via recid/arxiv/doi, or a topic/author/citing set via any cern_inspire_search_literature query) and notes the 50-per-page and 10,000-match ceilings. It does not explicitly say when to prefer search_literature or get_paper instead, so routing past the sibling is left partly implicit.

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

All cern-inspire-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.