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 "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@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
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"]
}
}
}Option A: Using the CLI
# Project scope (default)
gemini mcp add inspirehep uvx inspirehep-mcp
# User/global scope
gemini mcp add -s user inspirehep uvx inspirehep-mcpOption B: Manual configuration
Add to ~/.gemini/settings.json (user scope) or .gemini/settings.json (project scope):
{
"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 |
| Monitor cache hit rates and API performance |
All settings via environment variables (prefix INSPIREHEP_):
Variable | Default | Description |
|
| API rate limit |
|
| Cache TTL in seconds (24h) |
|
| Max cached entries |
|
| Enable SQLite persistent cache |
|
| SQLite cache file path |
|
| HTTP request timeout (seconds) |
|
| 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.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 |
|---|---|---|---|
| author_name | No | ||
| author_id | No | ||
| sort | No | mostrecent | |
| size | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses the return structure (list of papers plus aggregate metrics like h-index) and parameter constraints (sort options, size range). It does not explicitly state read-only nature or potential side effects, but the details provided are sufficient for a retrieval tool.
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 yet informative, with a clear first sentence stating purpose, followed by a structured explanation of parameters using bullets and examples. Every sentence adds value without redundancy.
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 for an agent to select and invoke the tool correctly. It covers the resource, action, parameter details, and high-level return value. The presence of an output schema (indicated by signals) further reduces the need for detailed return explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain all parameters. It does so effectively: author_name format ('Last, First'), author_id format (InspireHEP BAI), sort options ('mostrecent' or 'mostcited'), and size range (1-100, default 20).
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 explicitly states 'Retrieve publication history and citation metrics for an author,' providing a clear verb and resource. It also distinguishes the tool's output (papers plus metrics) and mentions sort and size parameters, which helps differentiate it from siblings like 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 provides clear guidance on how to use the two identifier parameters (author_name and author_id), including format examples. However, it does not explicitly state when not to use this tool or mention alternative tools for similar tasks, such as search_papers.
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 |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it resolves various identifier formats and returns BibTeX entry, title, texkey, and resolved ID. No annotations provided, so description carries full burden; covers key behaviors well.
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?
Concise and well-structured with bullet list and Args section. Front-loaded with purpose, no redundant sentences.
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?
Covers input and output well given 1 parameter and output schema exists. Lacks error handling or format details but sufficient for a retrieval 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?
Schema coverage is 0% so description must compensate. Description clearly explains identifier parameter with examples for DOI, arXiv ID, and Inspire ID, adding significant meaning.
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?
Clearly states 'Retrieve the BibTeX citation entry for a paper.' verb and resource are specific. Distinguishes from siblings like get_citations, get_paper_details by focusing on BibTeX format.
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?
Lists accepted identifier formats but no explicit guidance on when to use this vs alternatives. Usage is implied but not explicitly stated.
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 |
|---|---|---|---|
| inspire_id | Yes | ||
| direction | No | citing | |
| size | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool returns a citation list with metadata, total count, and a year-by-year timeline. It also specifies constraints like inspire_id as numeric, direction default, and size range. Behavior is well described.
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 extremely concise, using only 8 lines. It starts with a clear purpose, then bullet-lists arguments with explanations. Every sentence adds unique value, no fluff.
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 tool has 3 parameters with 1 required, and an output schema exists, the description covers input parameters thoroughly and mentions return structure (citation list, total count, timeline). No gaps remain for an agent to understand usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description adds full meaning: explains inspire_id as InspireHEP record ID (numeric), direction with values and meanings ('citing' or 'cited_by'), and size range (1–250, default 50). This far exceeds what the schema names and defaults provide.
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 'Retrieve citation graph data for a paper.' It distinguishes from siblings like get_references by specifying 'citation graph data' and direction options (citing/cited_by), but could be more explicit about how it differs from get_references which might also return citations.
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 usage context by listing required and optional parameters and their defaults. However, it does not explicitly state when to use this tool versus alternatives like get_references or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 |
|---|---|---|---|
| inspire_id | No | ||
| arxiv_id | No | ||
| doi | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool returns title, authors, abstract, citations, references count, publication info, keywords, URLs, and more. There is no mention of destructive behavior, authentication, or rate limits, but for a read-only retrieval tool, the description is sufficient.
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, with a clear front-loaded purpose sentence followed by parameter details in a bullet-like list. Every sentence adds value, and the structure is easy 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?
Given that an output schema exists, the description does not need to explain return values. It fully covers the input parameters and their formats. For a tool with three optional parameters and no annotations, this is complete and well-rounded.
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 schema has 0% description coverage, so the description must compensate. It thoroughly explains each parameter with concrete examples of accepted formats (e.g., arxiv_id: 'arxiv:2301.12345' or full URL). This goes well beyond the schema's minimal type information.
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 retrieves detailed metadata for a specific paper, distinguishing it from sibling tools like get_citations or get_references. It specifies the verb ('retrieve') and resource ('detailed metadata for a specific paper'), making the 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 explicitly instructs the user to provide at least one identifier and details the accepted formats. While it does not explicitly state when not to use this tool or mention alternatives, the context is clear enough for an agent to decide when to use it.
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 |
|---|---|---|---|
| inspire_id | No | ||
| arxiv_id | No | ||
| doi | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description fully discloses behavior: it returns title, inspire url, and a list of figures with captions, descriptions, and download URLs. Nothing is hidden about side effects or state changes (none expected).
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 three sentences plus clear bullet-like examples. It front-loads the purpose and then gives parameter specifics. No extraneous 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?
Given the tool has an output schema and the description covers inputs and outputs (title, url, figures list), the description is complete for an agent to correctly invoke and understand the response. All necessary context is provided.
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 has 0% description coverage; the description compensates fully by providing concrete formatting examples for each identifier type (e.g., 'arxiv:2301.12345', '10.1103/PhysRevLett.123.456789'). This adds essential meaning 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 the tool retrieves figures for a specific paper, listing the returned elements (title, url, figures with captions etc.). It distinguishes itself from sibling tools like get_paper_details and search_papers by focusing on figures specifically.
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 says 'Provide at least one identifier' and gives examples of accepted formats (inspire_id, arxiv_id, doi). While not listing when NOT to use it, the guidance is clear and context-driven.
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 |
|---|---|---|---|
| inspire_id | Yes | ||
| format | No | bibtex |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns the reference list in the requested format along with total count and title, but does not mention any side effects, rates, or permissions. It is transparent about the output but not about other behavioral traits.
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 (5 lines) and well-structured with a clear 'Args:' section. The main purpose is front-loaded, and every sentence adds value without excess.
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 simple tool (2 params, no nested objects, output schema exists), the description adequately covers the inputs and outputs. It could be more complete by mentioning that the inspire_id must be valid, but overall it provides sufficient context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining that inspire_id is a numeric InspireHEP record ID and that format accepts specific values ('bibtex', 'json', 'latex-us', 'latex-eu'). This adds essential meaning beyond the raw 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 the tool generates a formatted reference list for a paper, specifying the resource (paper via inspire_id) and the action. It distinguishes from siblings like get_bibtex by indicating it returns additional fields (total reference count, paper title) and supports multiple formats.
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 explains what the tool does and its arguments, but does not explicitly state when to use it over alternatives (e.g., get_bibtex). It implies it is for a more comprehensive reference list, but lacks direct guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
No annotations are provided, so the description carries the burden. It states a read-only check but does not disclose response nature (e.g., returns pong) or no side effects. More detail would benefit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is front-loaded and perfectly concise for the tool's simplicity.
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 zero parameters and the existence of an output schema (not shown), the description is adequate. It could add 'returns a simple success response' but remains sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so no parameter information is needed. Baseline for 0 params is 4, and the description correctly provides no param details.
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: 'Check that the InspireHEP MCP server is running.' It uses a specific verb ('check') and resource ('server is running'), distinguishing it from sibling tools that retrieve data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage to verify server connectivity. It lacks explicit when-not or alternatives, but for a standard health-check ping, the context is clear enough.
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 |
|---|---|---|---|
| collaboration_name | Yes | ||
| sort | No | mostrecent | |
| size | No | ||
| year | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It describes input parameters and return fields (publication list, year distribution, total citations, top-cited papers). Does not disclose error handling or rate limits, but adequate for a search tool.
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?
Well-structured, concise: first sentence states purpose, then parameter details. No fluff.
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 4 parameters, no annotations, and existence of output schema, description covers inputs and output summary completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but description adds value explaining each parameter: collaboration_name (type), sort (values), size (range and default), year (optional). Exceeds schema detail.
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?
Description clearly states it finds publications from a specific experimental collaboration, with examples of name variations. This distinguishes it from siblings like 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?
Implies usage when collaboration name is known, but no explicit guidance on when not to use or alternatives like search_papers.
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 |
|---|---|---|---|
| query | Yes | ||
| sort | No | bestmatch | |
| size | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as rate limits, authentication requirements, or side effects. The read-only nature is implied but not explicitly stated.
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 reasonably concise and front-loaded with the main purpose, though the 'Args:' section somewhat redundantly repeats information from 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 search scope, query examples, and parameter details adequately for a simple search tool. However, it does not mention output format or pagination, though an output schema exists.
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?
With 0% schema description coverage, the description adds significant value by explaining each parameter (query with examples, sort with allowed values, size with range and default) beyond the minimal 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 it searches InspireHEP for papers and provides multiple example queries, but does not explicitly differentiate from sibling tools like get_author_papers or search_by_collaboration.
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 examples of queries, implying usage for general paper search, but does not specify when to use this tool versus alternatives or mention any prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return cache and request performance statistics for the server.
Useful for monitoring cache hit rates, request counts, and average response times. No parameters required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description adequately discloses the tool's read-only behavioral nature by listing the metrics it returns. It does not mention potential performance impact or data freshness, but for a simple stats retrieval tool, this is sufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states the action, second explains usefulness and parameter count. No wasted words, front-loaded with the core 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?
Given the low complexity (no parameters, simple output), the description is complete: it states what is returned, the use case, and that no parameters are needed. The presence of an output schema further reduces the need to explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline score is 4. The description correctly notes 'No parameters required', adding no additional semantics beyond the schema (which is empty).
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 returns cache and request performance statistics, with a specific verb ('Return') and resource ('server stats'). It distinguishes from sibling tools which are all paper-related.
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 (monitoring cache hit rates, request counts, response times). It doesn't explicitly state when not to use it, but the use case is well-defined and no alternatives are needed given the uniqueness of this stats tool among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool serves a distinct purpose without overlap: author retrieval, paper details, figures, citations, references, BibTeX export, general search, collaboration search, and server utilities. Clear boundaries prevent confusion.
Tool names follow a consistent verb_noun pattern, primarily 'get_' for data retrieval and 'search_' for queries. Even 'ping' and 'server_stats' are standard utility names, maintaining overall coherence.
With 10 tools, the server covers essential operations for a bibliographic database without being too sparse or bloated. Each tool has a clear role, making the set well-scoped.
The tool set covers the full lifecycle of paper exploration: searching, retrieving metadata, figures, citations, references, and export. Missing features like full-text access are outside the database's scope, so no gaps exist.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/MohamedElashri/inspirehep-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
