This server provides an MCP interface to search and retrieve high-energy physics literature, papers, authors, citations, figures, and references from InspireHEP.
Check server status: Use ping to verify the server is running.
View server statistics: Use server_stats to inspect cache hit rates, request counts, and response times.
Search papers: Use search_papers with free text or field-specific queries (author, title, collaboration) and sort by best match, recency, or citations.
Get paper details: Retrieve metadata (title, authors, abstract, citation/reference counts, publication info, keywords, URLs) by Inspire ID, arXiv ID, or DOI.
Get paper figures: Fetch figure captions, descriptions, and direct download URLs for a paper.
Get author publications: Retrieve an author’s papers and citation metrics (total citations, h-index, average citations) by name or InspireHEP BAI ID.
Explore citation graphs: Use get_citations to see citing or cited papers, total citation counts, and year-by-year timelines.
Search by collaboration: Find publications from specific experiments (e.g., ATLAS, CMS, LHCb, Belle-II) with optional year filtering and citation summaries.
Generate references: Produce formatted reference lists (BibTeX, JSON, LaTeX US/EU) for a paper.
Get BibTeX entries: Retrieve a ready-to-use BibTeX citation from DOI, arXiv ID, or InspireHEP record ID.
Provides tools for searching high-energy physics literature on InspireHEP, retrieving paper details, author metrics, citation graphs, and generating formatted references in BibTeX, LaTeX, or JSON.
Click on "Deploy 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., "@InspireHEP MCP Server Search for papers about dark matter"
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.
An MCP server that integrates InspireHEP high-energy physics literature with LLMs. Search papers, explore citations, retrieve author metrics, and generate formatted references.
# Using pip
pip install inspirehep-mcp
# Or run directly with uvx (no install needed)
uvx inspirehep-mcpgit clone https://github.com/MohamedElashri/inspirehep-mcp.git
cd inspirehep-mcp
uv sync
uv run inspirehep-mcpRelated MCP server: Crossref Academic MCP Server
The installed command remains a stdio server by default, so existing desktop configurations continue to work. To run it natively as a remote MCP endpoint, select the Streamable HTTP transport:
INSPIREHEP_ALLOWED_HOSTS="mcp.example.org" \
INSPIREHEP_HTTP_RATE_LIMIT=60 \
inspirehep-mcp --transport streamable-http --host 0.0.0.0 --port 8000The MCP endpoint is http://localhost:8000/mcp and the unauthenticated health
probe is http://localhost:8000/health. PORT is also honored when a hosting
platform injects it. Put the service behind HTTPS for internet deployment.
Release tags publish a container to the GitHub Container Registry. The image uses Streamable HTTP by default:
docker run --rm -p 8000:8000 \
ghcr.io/mohamedelashri/inspirehep-mcp:latestFor a public hostname, add it to the host allowlist:
docker run --rm -p 8000:8000 \
-e INSPIREHEP_ALLOWED_HOSTS="mcp.example.org" \
-e INSPIREHEP_HTTP_RATE_LIMIT=60 \
ghcr.io/mohamedelashri/inspirehep-mcp:latestThe image runs as a non-root user, has a built-in health check, and uses stateless JSON responses so replicas do not need shared MCP session state.
The included docker-compose.yml can build the current
checkout or run the published image:
# Local deployment
docker compose up --build -d
# Add the public hostname when deploying behind a domain
INSPIREHEP_ALLOWED_HOSTS="mcp.example.org" docker compose up -dThe Compose service is read-only, drops Linux capabilities, enables
no-new-privileges, and retains the image health check.
Streamable HTTP requests are limited per client IP with a token bucket. The
default is 60 requests per minute with a burst of 20; /health is exempt. Set
INSPIREHEP_HTTP_RATE_LIMIT=0 to disable it.
Requests to /mcp are limited to 256 KiB. The native server also accepts at
most 100 concurrent connections or tasks, closes idle keep-alive connections
after 5 seconds, and admits at most 32 pending INSPIRE API cache misses. Excess
upstream work fails fast instead of accumulating in memory.
By default, the limiter uses the direct peer address and ignores forwarded
headers. Only enable INSPIREHEP_TRUST_PROXY_HEADERS when a trusted reverse
proxy overwrites X-Forwarded-For; otherwise clients can choose their own
rate-limit identity. The limiter is in-memory and per process, so multi-replica
deployments should also enforce a shared limit at the proxy or gateway.
Read-only tools avoid mutation risk, but a public endpoint can still be used
to consume your compute and upstream API allowance. This server does not add
authentication. Use an authenticating reverse proxy if the endpoint should
not be open to everyone, and retain an edge rate limit for distributed
deployments. Keep DNS-rebinding protection enabled and setINSPIREHEP_ALLOWED_ORIGINS for clients that send an Origin header.
Add to your MCP client config:
{
"mcpServers": {
"inspirehep": {
"command": "uvx",
"args": ["inspirehep-mcp"]
}
}
}Option A: Using the CLI
# Global scope (available across all projects)
claude mcp add --scope user inspirehep -- uvx inspirehep-mcp
# Project scope (shared via .mcp.json, checked into source control)
claude mcp add --scope project inspirehep -- uvx inspirehep-mcpOption B: Manual configuration
For global scope, add to ~/.claude.json:
{
"mcpServers": {
"inspirehep": {
"command": "uvx",
"args": ["inspirehep-mcp"]
}
}
}For project scope, create .mcp.json in your project root:
{
"mcpServers": {
"inspirehep": {
"command": "uvx",
"args": ["inspirehep-mcp"]
}
}
}Open the interactive MCP manager with /mcp, or configure the server manually.
Antigravity reads global MCP servers from ~/.gemini/config/mcp_config.json
and workspace-local servers from .agents/mcp_config.json:
{
"mcpServers": {
"inspirehep": {
"command": "uvx",
"args": ["inspirehep-mcp"]
}
}
}Tool | Description |
| Search papers by topic, author, collaboration, or free text |
| Get full metadata for a paper by Inspire ID, arXiv ID, or DOI |
| Retrieve an author's publications and citation metrics |
| Explore citation graph — who cites a paper, or what it cites |
| Find publications from ATLAS, CMS, LHCb, etc. |
| Retrieve figures and download URLs for a paper |
| Generate BibTeX, LaTeX, or JSON reference lists |
| Retrieve BibTeX citation entry by DOI, arXiv ID, or Inspire ID |
All settings via environment variables (prefix INSPIREHEP_):
Variable | Default | Description |
|
| API rate limit |
|
| Maximum admitted INSPIRE API cache misses |
|
| Cache TTL in seconds (24h) |
|
| Max cached entries |
|
| Enable SQLite persistent cache |
|
| SQLite cache file path |
|
| HTTP request timeout (seconds) |
|
|
|
|
| HTTP bind address |
|
| HTTP port; falls back to |
|
| Streamable HTTP endpoint path |
|
| Disable server-side MCP session state |
|
| Prefer JSON responses over SSE streams |
|
| Inbound requests per minute per client; |
|
| Maximum immediate requests per client |
|
| Maximum in-memory client buckets |
|
| Maximum |
|
| Maximum concurrent HTTP connections or tasks |
|
| Idle HTTP keep-alive timeout in seconds |
|
| Trust the first |
|
| Maximum general text input characters |
|
| Maximum identifier input characters |
|
| Maximum serialized tool-result bytes |
|
| Maximum references returned per tool call |
|
| Maximum figures returned per tool call |
|
| Comma-separated valid HTTP Host headers |
| empty | Comma-separated valid browser origins |
|
| Validate Host and Origin headers |
|
| Logging level |
# Run tests
uv run pytest tests/ -v
# Run with coverage
uv run pytest tests/ --cov=inspirehep_mcp --cov-report=term-missing
# Unit tests only (no network)
uv run pytest tests/test_utils.py tests/test_cache.py tests/test_errors.py \
tests/test_config.py tests/test_rate_limit.py tests/test_server.py \
tests/test_api_client_safety.py tests/test_tools_safety.pyThis project is licensed under the AGPL-3.0 License - see the LICENSE file for details.
Retrieve publication history and citation metrics for an author.
Provide either author_name or author_id:
author_name: "Weinberg, Steven" (Last, First format)
author_id: "S.Weinberg.1" (InspireHEP BAI)
Returns a list of papers plus aggregate metrics including total citations, h-index, and average citations per paper.
Args: author_name: Author name in "Last, First" format. author_id: InspireHEP author identifier (BAI). sort: Sort order — "mostrecent" or "mostcited". size: Number of papers to return (1-100, default 20).
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | ||
| sort | No | mostrecent | |
| author_id | No | ||
| author_name | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnly and idempotent behavior, and the description is consistent with that. It adds useful behavioral details such as returning aggregate metrics (total citations, h-index, average citations) and the paper list, while not contradicting the 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?
The description is well-structured with an intro and an Args block, but it repeats author_name and author_id details in prose and again in the Args list. This minor redundancy is not harmful but prevents a perfect conciseness score.
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 all parameters described and return values summarized, the description is sufficient for typical usage. It does not specify behavior when both author_name and author_id are omitted or both provided, but this is a minor gap given the clear parameter guidance.
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?
Although the input schema has no per-parameter descriptions, the tool description explains all four parameters: author_name (format), author_id (BAI format), sort (allowed values), and size (range and default). This fully compensates for the schema's lack of 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 a specific action ('Retrieve publication history and citation metrics for an author') and identifies the resource (an author). This distinguishes it from sibling tools like search_papers or get_paper_details, which have different scopes.
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 clear context for when to use the tool: retrieving papers and metrics for a specific author. It also explains how to supply the author (either by name or BAI) and includes sort/size options. It does not explicitly compare against sibling tools, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the BibTeX citation entry for a paper.
Accepts any common identifier format:
Inspire ID: "3456"
arXiv ID: "arxiv:2301.12345", "arxiv:hep-ph/0123456", or full URL
DOI: "10.1103/PhysRevLett.123.456789" or full URL
Args: identifier: A DOI, arXiv ID, or InspireHEP record ID.
Returns the BibTeX entry along with paper title, texkey, and the resolved Inspire record ID.
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds behavioral context by specifying the return payload (BibTeX, paper title, texkey, resolved Inspire record ID) and clarifying accepted identifier formats. It does not contradict annotations and provides useful detail beyond them.
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 well-organized: a one-sentence purpose statement, a bulleted list of accepted formats, and a separate Args section. It is front-loaded with the core function and avoids verbosity. Every sentence contributes value, and the format is scannable for an agent.
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?
The tool is simple with a single required parameter, and an output schema exists (as indicated by context signals). The description covers the input formats and the return contents, leaving nothing essential missing. The presence of an output schema means return values don't need further elaboration.
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 provides only a bare 'identifier' string with no description, leaving 0% schema coverage. The description fully compensates by detailing the three accepted identifier formats and giving concrete examples for each. This adds meaning that the schema lacks entirely.
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's purpose: 'Retrieve the BibTeX citation entry for a paper.' It specifies a concrete verb and resource, and the accepted identifier formats (Inspire ID, arXiv ID, DOI) make it distinct from sibling tools like search_papers or get_paper_details. No ambiguity about what it does.
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—when you need a BibTeX entry—but it does not explicitly compare itself to alternatives or state when not to use it. It does not mention that get_citations or get_paper_details might be better for other needs. The guidance is functional but not explicit about selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve citation graph data for a paper.
Args: inspire_id: InspireHEP record ID (numeric). direction: "citing" (papers that cite this) or "cited_by" (papers this cites). size: Number of results to return (1–250, default 50).
Returns citation list with metadata, total count, and a year-by-year citation timeline.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | ||
| direction | No | citing | |
| inspire_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare read-only and idempotent behavior, which the description does not contradict. The description adds a brief note about the return format (citation list, metadata, count, timeline), but this is more about output than behavioral traits. With the annotations covering safety, the description adds only marginal behavioral context.
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 well-structured with an 'Args' section and a 'Returns' section, front-loading the core purpose. It is concise without unnecessary fluff, and each sentence serves a clear informative purpose.
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?
The tool is simple with three parameters, and the description explains all of them along with the return shape. Since an output schema exists, the summary of the return is sufficient context. No critical usage information 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?
The description adds substantial meaning to each parameter beyond the raw schema. It explains that inspire_id is a numeric record ID, defines the two valid values for 'direction', and clarifies that size is a result count with a range and default. This greatly aids correct invocation.
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's purpose with a specific verb ('Retrieve') and resource ('citation graph data for a paper'). It is distinct from sibling tools like 'get_references' or 'get_paper_details' by focusing on citation graphs, making its purpose 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 provides clear context on what the tool does and explains the parameters, especially the 'direction' option (citing vs cited_by). However, it does not explicitly mention when to use it instead of related tools like 'get_references', so it lacks explicit alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve detailed metadata for a specific paper.
Provide at least one identifier. Accepts multiple formats:
inspire_id: "3456"
arxiv_id: "arxiv:2301.12345", "arxiv:hep-ph/0123456", or full URL
doi: "10.1103/PhysRevLett.123.456789" or full URL
Returns title, authors, abstract, citations, references count, publication info, keywords, URLs, and more.
| Name | Required | Description | Default |
|---|---|---|---|
| doi | No | ||
| arxiv_id | No | ||
| inspire_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and idempotentHint annotations already disclose the safe, non-mutating nature, and the description adds what data is returned (title, authors, abstract, citations, references count, publication info, keywords, URLs). It does not describe error behavior or rate limits, but annotations cover the key behavioral safety aspects.
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 well-structured and concise, using a short introductory sentence, a clear bulleted list of identifier formats, and a brief enumeration of return fields. It avoids unnecessary jargon or redundant details while remaining informative.
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 output schema exists and the description lists key return fields, the core usage context is complete. It could mention behavior when multiple identifiers are provided or when no identifier resolves, but for a metadata retrieval tool with clear identifier requirements, it is adequately 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?
Despite the schema having no descriptions, the description fully explains each parameter's expected format: inspire_id, arxiv_id (including variations and URLs), and doi (including full URLs). It also conveys the 'at least one' constraint, which is meaningful context beyond the optional schema fields.
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's verb ('Retrieve') and resource ('detailed metadata for a specific paper'), making the primary purpose unmistakable. It also differentiates itself from siblings like search_papers by focusing on a single paper via identifiers.
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 explicitly instructs to 'provide at least one identifier' and details the accepted formats for each parameter. It does not name sibling alternatives or conditions for choosing this tool over them, but the identifier-focused usage is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve figures for a specific paper.
Provide at least one identifier. Accepts multiple formats:
inspire_id: "3456"
arxiv_id: "arxiv:2301.12345", "arxiv:hep-ph/0123456", or full URL
doi: "10.1103/PhysRevLett.123.456789" or full URL
Returns title, inspire url, and a list of figures with their captions, descriptions and direct download URLs.
| Name | Required | Description | Default |
|---|---|---|---|
| doi | No | ||
| arxiv_id | No | ||
| inspire_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and idempotentHint annotations already cover side-effect expectations. The description adds useful behavioral context by specifying the required identifier condition and the shape of the returned data, though it does not discuss error cases if no identifier is provided.
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 concise, well-structured, and free of unnecessary detail. The identifier formats are presented as a clear bullet list, and the return value summary is direct.
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?
The description is complete enough for a low-complexity tool. It covers all three parameters, explains the identifier requirement, and describes the output despite the presence of an output schema. No critical usage context 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?
The input schema provides no descriptions for the parameters, but the description compensates fully by explaining the accepted formats for doi, arxiv_id, and inspire_id, including concrete examples and the requirement to provide at least one identifier.
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 that the tool retrieves figures for a specific paper and lists the returned data (title, INSPIRE URL, figures with captions/descriptions/download URLs). This is specific enough to distinguish it from sibling tools like get_paper_details or search_papers.
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 good input guidance by explaining identifier formats and requiring at least one identifier, but it does not explicitly say when to prefer this tool over alternatives or when not to use it. The usage is implied rather than directly contrasted with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a formatted reference list for a paper.
Args: inspire_id: InspireHEP record ID (numeric). format: Output format — "bibtex", "json", "latex-us", or "latex-eu".
Returns the reference list in the requested format along with total reference count and paper title.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | bibtex | |
| inspire_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and idempotentHint annotations cover side effects, and the description adds what is returned (reference list, total count, paper title). It does not mention error behavior, but that is not required given 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?
The description is compact and front-loaded with the core purpose in the first sentence. The parameter explanations and return summary add necessary detail 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?
For a two-parameter read-only tool, the description covers inputs and return shape, and an output schema exists. It could slightly clarify how get_references differs from the sibling get_bibtex, but overall it is sufficiently 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?
Although schema descriptions are absent, the description fully explains inspire_id as a numeric InspireHEP record ID and format with all allowed output values. This provides more meaning than the bare 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?
States a specific action: generate a formatted reference list for a paper. It is distinct enough from siblings like get_paper_details and get_bibtex, although it does not explicitly say it returns the works cited by the paper.
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 when to use the tool based on the need for a paper's reference list, but it does not explicitly compare or exclude sibling tools such as get_bibtex. No explicit when-to-use/when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check that the InspireHEP MCP server is running.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and idempotentHint annotations already establish that the tool is safe and side-effect-free. The description adds the behavior of checking server status but does not elaborate on the response format or potential errors. Since the annotations cover the primary behavioral transparency needs, a score of 3 is appropriate.
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, concise sentence with no redundant words. It front-loads the action verb 'Check' and immediately names the resource, making it maximally efficient for an agent to parse.
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?
An output schema exists, so the description need not detail return values. The description provides enough context (server readiness) for an agent to know the purpose and likely outcome. It is slightly incomplete in not mentioning the exact success/failure signal, but for a ping, the common convention suffices.
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?
There are no parameters, so schema coverage is trivially complete. The description adds no parameter-specific information because none exist. The baseline of 3 applies as there is nothing to clarify 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 verb 'Check' and a specific resource 'InspireHEP MCP server', making its purpose unmistakable. It clearly stands apart from sibling tools that retrieve papers, authors, or citations, so an agent can easily select it for server health verification.
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 use as a preliminary health check before calling data-fetching tools, and its contrast with siblings (all data retrieval) reinforces this. While not explicitly stating 'use this before other calls', the intent is clear from the verb 'Check' and the noun 'server running'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find publications from a specific experimental collaboration.
Handles common name variations (e.g. "lhcb" → "LHCb").
Args: collaboration_name: Collaboration name (e.g. "ATLAS", "CMS", "LHCb", "Belle-II"). sort: Sort order — "mostrecent" or "mostcited". size: Number of results to return (1–100, default 20). year: Optional year filter (e.g. 2024).
Returns publication list, year distribution, total citations, and top-cited papers from the returned set.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | ||
| sort | No | mostrecent | |
| year | No | ||
| collaboration_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and idempotentHint already cover safety characteristics, and the description goes beyond by noting normalization behavior and the returned set (publication list, year distribution, total citations, top-cited papers). This gives the agent a good sense of what to expect without needing to infer from schema alone.
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 with the core purpose. The parameter list is concise, each line adding meaningful detail without unnecessary verbosity or restating obvious type information already in the schema.
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?
The description covers the primary input parameters and the expected return contents, which is sufficient for a read-only search tool. It does not mention error cases or pagination, but given the output schema is present and the operation is straightforward, this is a minor gap.
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?
Since the schema has no parameter descriptions, the description compensates thoroughly by documenting all four parameters. It adds concrete examples for collaboration_name, valid sort values, the size range (1–100), and the optional nature of year, providing meaning well beyond the bare 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 clearly states 'Find publications from a specific experimental collaboration', identifying both the action and the resource scope. It does not explicitly name a sibling tool to contrast with, but the collaboration-specific scope distinguishes it from general search or author-based 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 no explicit guidance on when to use this tool versus alternatives like search_papers or get_author_papers. The normalization example ('lhcb' → 'LHCb') hints at one use case, but there is no clear when-to-use/when-not-to-use direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search InspireHEP for papers matching a query.
Supports free-text and field-specific queries such as:
"dark matter direct detection"
"author:ellis title:higgs"
"collaboration:ATLAS supersymmetry"
"find a weinberg and t electroweak"
Args: query: Search query string. sort: Sort order — "bestmatch", "mostrecent", or "mostcited". size: Number of results to return (1-100, default 10).
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | ||
| sort | No | bestmatch | |
| query | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint and idempotentHint, so the description does not need to restate those. The description adds no further behavioral details beyond the act of searching, which is consistent with the annotations. 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?
The description is concise and well structured: a clear opening sentence, illustrative query examples, and a straightforward argument list. It avoids unnecessary detail and stays focused on actionable 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?
The description provides all necessary information for calling the tool: query syntax, sort options, size limits, and defaults. Since an output schema is present, return-value details are not required. Minor omissions such as error behavior or empty-result handling are not significant for this simple search 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 input schema provides no descriptions, but the tool description fully compensates by explaining query, sort, and size, including allowed sort values, the size range, and defaults. The query examples additionally clarify expected syntax.
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's function: 'Search InspireHEP for papers matching a query.' It provides concrete query examples and distinguishes this general search tool from more specific sibling tools like get_paper_details or get_author_papers.
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 useful context by showing supported free-text and field-specific query formats, making it clear when this tool is appropriate. It does not explicitly contrast it with search_by_collaboration or other sibling tools, but the examples and general-purpose framing provide sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0get_author_papers4 fields changedOutput schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "title": "Result",
- "type": "string"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / titlePrevious value: -"get_author_papersOutput"New value: +"get_author_papersDictOutput"get_bibtex4 fields changedOutput schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "title": "Result",
- "type": "string"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / titlePrevious value: -"get_bibtexOutput"New value: +"get_bibtexDictOutput"get_citations4 fields changedOutput schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "title": "Result",
- "type": "string"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / titlePrevious value: -"get_citationsOutput"New value: +"get_citationsDictOutput"get_paper_details4 fields changedOutput schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "title": "Result",
- "type": "string"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / titlePrevious value: -"get_paper_detailsOutput"New value: +"get_paper_detailsDictOutput"get_paper_figures4 fields changedOutput schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "title": "Result",
- "type": "string"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / titlePrevious value: -"get_paper_figuresOutput"New value: +"get_paper_figuresDictOutput"get_references4 fields changedOutput schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "title": "Result",
- "type": "string"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / titlePrevious value: -"get_referencesOutput"New value: +"get_referencesDictOutput"search_by_collaboration4 fields changedOutput schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "title": "Result",
- "type": "string"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / titlePrevious value: -"search_by_collaborationOutput"New value: +"search_by_collaborationDictOutput"search_papers4 fields changedOutput schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "title": "Result",
- "type": "string"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / titlePrevious value: -"search_papersOutput"New value: +"search_papersDictOutput"server_statsv0.1.4get_author_papersget_bibtexget_citationsget_paper_detailsget_paper_figuresget_referencespingsearch_by_collaborationsearch_papersserver_statsScored across 9 tools
Most tools are clearly distinct, targeting specific resources like papers, authors, figures, or citations. However, search_papers and search_by_collaboration both return publication lists and could be confused, though their scopes are described clearly enough to guide an agent.
The majority of tools follow a consistent get_/search_ prefix pattern. Minor deviations include the standalone 'ping' and the prepositional 'search_by_collaboration', which break the otherwise uniform verb_noun convention without causing confusion.
With 9 tools, the server is well-scoped for a literature database API. Each tool serves a meaningful purpose—searching, retrieving metadata, figures, citations, references, and BibTeX—without redundant bloat or excessive granularity.
The tool surface covers the core workflows for interacting with InspireHEP: general search, collaboration-filtered search, paper details, figures, author publication history, citation graphs, references, and BibTeX export. No significant gaps are apparent for a read-only literature search service.
Academic research MCP server for paper search, citation checks, graphs, and deep research.
INSPIRE-HEP high-energy physics literature database
MCP server for Altmetric APIs - track research attention across news, policy, social media, and more
