Provides category-aware academic paper search over arXiv, including sorting by newest for fresh preprints, with paper IDs normalized from arXiv identifiers and URLs.
Provides academic literature search, paper details, citation and reference retrieval, related-paper discovery, bounded citation-graph construction, and BibTeX export using Semantic Scholar's Graph and Recommendations APIs.
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., "@scholar-mcp Find recent papers on graph neural networks and export BibTeX for the top 5"
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 gives LLM agents grounded access to academic literature: paper search over arXiv and Semantic Scholar, citation graphs, related-paper discovery, and BibTeX export, plus prompt templates that make the model write related-work summaries only from retrieved evidence.
Design rule: tools fetch and compute; the LLM reasons and writes. Search, graph construction, ranking and BibTeX happen in code (reproducible, testable). Summaries are written by the client model from tool output, guided by MCP prompts, so every claim traces back to a paper the server actually returned.
flowchart LR
A[LLM client<br/>Claude Desktop / Claude Code / agent.py] -- MCP: stdio or HTTP --> B[scholar-mcp server]
B --> C[Tools<br/>8 typed tools]
B --> D[Resources<br/>paper://id, cache stats]
B --> E[Prompts<br/>related_work_review, literature_map]
C --> F[HttpClient<br/>rate limit + retry + backoff]
F --> G[(SQLite TTL cache)]
F --> H[arXiv API]
F --> I[Semantic Scholar<br/>Graph + Recommendations]Related MCP server: PapersFlow
Tool | Purpose | Source |
| Keyword search with year / min-citation filters, sortable by citations | Semantic Scholar |
| Category-aware search; | arXiv |
| Full abstract, authors, venue, citation counts, links | Semantic Scholar |
| Forward citations, optionally influential-only, ranked | Semantic Scholar |
| A paper's bibliography, ranked | Semantic Scholar |
| Similar papers from a seed (recommendation model) | Semantic Scholar |
| Bounded BFS graph (depth 1-2); returns nodes, edges, | Semantic Scholar |
| Deterministic BibTeX, per-paper failure reporting | Semantic Scholar |
Resources: paper://{id} (Markdown paper card), scholar://cache/stats.
Prompts: related_work_review(topic, num_papers, year_from), literature_map(seed_paper).
All tools are annotated read-only. Paper ids can be arXiv ids (1706.03762, arXiv:...v3, URLs),
DOIs, or Semantic Scholar ids; they are normalised automatically.
Typed schemas via Pydantic Field constraints (limit 1-50, depth 1-2, ...); invalid calls
are rejected by the protocol layer before any network call.
Rate limiting & resilience: per-host throttling (arXiv 1 req / 3 s, Semantic Scholar 1 req / 1.6 s, safely under its 1 req/s key limit),
retries with exponential backoff, honours Retry-After, distinct errors for 404 / 429 / 5xx.
Caching: SQLite TTL cache (search 1 h, paper 24 h, citations 6 h) so agent loops don't burn quota.
LLM-readable errors: failures say what went wrong and what to try next. Errors subclass the SDK's
ToolError, because the SDK hides the text of unexpected exceptions from the client.
Bounded outputs: abstracts trimmed in lists, graphs capped by nodes / per-node / per-level
limits, with a truncated flag, so responses fit in a context window.
MCP SDK compatibility: developed and tested on mcp 2.x (where FastMCP became MCPServer); a small import shim keeps 1.x working, but 1.x is not covered by CI.
git clone https://github.com/raovivek02/scholar-mcp.git && cd scholar-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,agent]"
pytest -q # unit tests use mocked HTTP, no network needed
python scripts/live_smoke.py # one-off check against the real APIs
mcp dev src/scholar_mcp/server.py # opens the MCP Inspector (needs Node.js)Optional but recommended: a free Semantic Scholar API key
in SEMANTIC_SCHOLAR_API_KEY for reliable rate limits.
Claude Desktop: copy examples/claude_desktop_config.json into your config and fix the path.
Claude Code: claude mcp add scholar -- /path/to/.venv/bin/python -m scholar_mcp
python -m scholar_mcp --transport streamable-http --host 127.0.0.1 --port 8000export ANTHROPIC_API_KEY=...
python client/agent.py "Write a related-work paragraph on LiDAR moving object segmentation"No paid API? Use a free local model through Ollama (or any OpenAI-compatible endpoint such as Groq, Gemini or OpenRouter):
ollama pull qwen2.5:32b # or qwen2.5:7b on a smaller GPU
python client/agent_openai.py "Write a related-work paragraph on LiDAR moving object segmentation"
python eval/run_eval.py --provider openai --model qwen2.5:32bFree hosted option: a Google AI Studio key (free tier) works through Gemini's OpenAI-compatible
endpoint - set LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/,
LLM_API_KEY, and LLM_MODEL (see the docstring in client/agent_openai.py).
client/agent.py connects over MCP, lists the tools, passes them to the model, executes tool calls
and loops until the model produces a final answer.
eval/run_eval.py runs the agent on the questions in eval/cases.json and reports:
Metric | Meaning |
| Required tools were called |
| Fraction of known key papers that appeared in tool output |
| Every arXiv id in the final answer was returned by a tool (no invented citations) |
| Every "(Author et al., Year)" citation matches a paper a tool returned |
| A nonexistent paper is reported as not found, not hallucinated |
python eval/run_eval.py --model claude-sonnet-5-5 # writes eval/results.mdResults (eval/results.md):
Model: gemini-3.5-flash-lite - 8 cases
metric | score |
tool_selection | 1.0 |
retrieval_recall | 0.889 |
grounded | 1.0 |
citation_support | 1.0 |
graceful_failure | 1.0 |
case | tools ok | recall | grounded | turns |
lookup-details | True | 1.0 | True | 3 |
recent-preprints | True | None | True | 2 |
forward-citations | True | None | True | 3 |
foundations-graph | True | None | True | 3 |
bibtex | True | 1.0 | True | 2 |
related-work | True | 0.667 | True | 3 |
similar-papers | True | None | True | 4 |
missing-paper | True | None | True | 3 |
Single run on 8 hand-written queries (eval/cases.json). A small sample, so treat it as a smoke-level evaluation, not a benchmark.
Variable | Purpose |
| Semantic Scholar key (strongly recommended) |
| Cache file path (default |
| For |
| For |
src/scholar_mcp/ server.py (tools/resources/prompts) · semantic_scholar.py · arxiv_client.py
graph.py · bibtex.py · http.py · cache.py · ids.py · models.py · errors.py
client/agent.py tool-calling agent loop eval/ evaluation harness + cases
tests/ unit + stdio protocol tests scripts/ live API smoke testCoverage and citation counts are whatever the two APIs return; Semantic Scholar's citation list is fetched in a 200-paper window, so very highly cited papers are sampled, not exhaustive.
Citation graphs are bounded samples of top-cited neighbours, not complete networks.
Abstracts only; full-text retrieval is not implemented.
The evaluation is small: 8 hand-written queries, one run, one model (Gemini 3.5 Flash-Lite via its free tier).
Semantic Scholar occasionally returns HTTP 429 even within the key's limit. The client retries with backoff (up to 5 times); a call that still fails reaches the model as a tool error it can react to (in one eval run the agent fell back to arXiv search).
Full-text PDF extraction tool · OpenAlex as a third source · author-centric tools · Docker image + auth for remote hosting.
MIT
Build a bounded citation graph around a seed paper.
Returns nodes, edges (source cites target), and key_papers ranked by how often they are cited within the graph - a quick way to find foundational work in a subfield. The graph is a top-cited sample, not the full network (see the 'truncated' flag).
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | 1 = direct neighbours, 2 = neighbours of neighbours | |
| paper_id | Yes | arXiv id (1706.03762), arXiv URL, DOI (10.xxxx/...) or Semantic Scholar id | |
| direction | No | both | |
| max_nodes | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent, and openWorld, so the bar is lower, and the description still adds genuinely non-obvious context: the result is a top-cited sample rather than the complete network, and a 'truncated' flag signals incompleteness. It also defines edge direction (source cites target), which matters for interpreting results. It does not mention cost, latency, or rate limits for a potentially expensive traversal.
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?
Front-loaded with the action and the return shape, with no filler sentences. Slight redundancy between 'top-cited sample, not the full network' and the 'truncated' flag note, which restate the same caveat.
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 return-value detail is mostly covered, and the description still usefully explains edge direction and the key_papers ranking. For a 4-parameter, open-world traversal tool the main omission is routing guidance against get_citations/get_references.
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 50%: depth and paper_id are documented in the schema, while direction and max_nodes have none. The description's 'bounded' language gestures at max_nodes/depth but adds no meaning for the direction enum or for how max_nodes trades off against truncation, so it does not compensate for the gap.
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 verb and resource — 'Build a bounded citation graph around a seed paper' — and names the returned artifacts (nodes, edges, key_papers). It implies, but never states, how this differs from siblings like get_citations or get_references, so it stops short of 5.
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?
Usage is only implied: 'a quick way to find foundational work in a subfield' hints at the use case, but there is no explicit when-to-use or when-to-prefer-a-sibling guidance despite four closely related sibling tools (get_citations, get_references, find_related_papers).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate BibTeX entries for papers. Done in code, so entries are exact and reproducible.
| Name | Required | Description | Default |
|---|---|---|---|
| paper_ids | Yes | Paper ids to export |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds one genuine piece of context beyond that: entries are generated in code, so output is exact and reproducible. It says nothing about the maximum of 20 ids or how invalid ids are handled.
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 short sentences, zero filler, with the purpose front-loaded and the reproducibility note second. Every sentence earns its place.
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 return values need not be explained, and annotations cover the safety profile. What remains missing is modest but real: batching limits, error behavior on unknown ids, and any hint about when to reach for this over the sibling tools.
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 100% with a single, well-documented `paper_ids` array, so the schema does the heavy lifting. The description adds no format hints (e.g. where ids come from) and does not mention the 20-item cap, so it does not exceed the baseline.
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 verb and resource: "Generate BibTeX entries for papers." That is clearly distinct from the discovery-oriented siblings (search_papers, get_citations), though the description never names a sibling or explicitly contrasts itself. The purpose is unambiguous without opening the schema.
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?
There is no when-to-use guidance and no alternatives named. The reader must infer that this is the export/citation-format step from the tool name alone; nothing says what happens with unknown or duplicate ids, or when another tool (e.g. get_paper_details) would be the better choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Papers that cite the given paper (forward citations), from a window of up to 200.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results | |
| sort_by | No | citations | |
| paper_id | Yes | arXiv id (1706.03762), arXiv URL, DOI (10.xxxx/...) or Semantic Scholar id | |
| influential_only | No | Only citations marked influential |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety and repeatability are covered. The description adds the citation direction and an unspecified 'window of up to 200', but says nothing about result ordering, whether the window is a candidate pool vs. a result cap, or what the response contains.
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?
A single front-loaded sentence with no filler; the parenthetical clarification is well placed. The trailing 'from a window of up to 200' clause is the only part that would benefit from rewording.
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 and annotations carry much of the load, so a one-line description is defensible for a read-only retrieval tool. However, the unexplained 200-vs-50 discrepancy and the absence of any note on sort_by or ordering leave real gaps for correct invocation.
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 75% and the schema already documents limit, paper_id, and influential_only, so the description adds little. Worse, 'a window of up to 200' conflicts with the schema's limit maximum of 50, leaving an agent unsure whether 200 is a result cap or an underlying candidate pool, and sort_by's semantics remain undocumented in both places.
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 gives a specific resource (papers citing a paper) and explicitly disambiguates direction with '(forward citations)', which contrasts with the backward-looking sibling get_references. It stops short of naming that sibling or any other alternative, so differentiation is implied rather than stated.
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?
'Forward citations' implicitly tells an agent this is the complement of reference lookup, but there is no explicit when-to-use/when-not guidance and no mention of find_related_papers or build_citation_graph as alternatives. The agent must infer routing from the phrase alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full metadata for one paper: complete abstract, authors, venue, citation counts, links.
| Name | Required | Description | Default |
|---|---|---|---|
| paper_id | Yes | arXiv id (1706.03762), arXiv URL, DOI (10.xxxx/...) or Semantic Scholar id |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered without description help. The description adds the field inventory, which is mild added context, but says nothing about failure behavior for malformed or unknown identifiers, or about how external-source lookups may vary. With annotations carrying the main burden, a 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?
A single sentence that front-loads the scope ('Full metadata for one paper') and then lists the payload. No filler, no repetition of the tool name, nothing that could be cut.
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 one fully documented parameter, a present output schema, and annotations covering read-only/idempotent behavior, the definition covers what an agent needs to call it correctly. It falls short of 5 only because there is no routing guidance against the seven sibling tools.
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 100% and the paper_id field already documents every accepted identifier form (arXiv id, arXiv URL, DOI, Semantic Scholar id). The description adds no meaning beyond the schema for this single required parameter, so the baseline of 3 applies.
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 resource and scope: 'Full metadata for one paper', then enumerates the fields returned (abstract, authors, venue, citation counts, links). The 'one paper' phrasing distinguishes it from the sibling list/search tools, though it never names search_papers or get_citations explicitly.
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?
Usage is only implied: an agent can infer this is the single-record lookup to use once a paper_id is known, versus search_papers for discovery. There is no explicit when-to-use statement, no mention of when to prefer get_citations or find_related_papers, and no note on what happens with an unresolvable id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Papers the given paper cites (its bibliography), from a window of up to 200.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results | |
| sort_by | No | citations | |
| paper_id | Yes | arXiv id (1706.03762), arXiv URL, DOI (10.xxxx/...) or Semantic Scholar id |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds a cap ('window of up to 200'), but that number conflicts with the schema's limit maximum of 50 and is not explained, leaving the truncated-result behavior unclear.
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?
It is a single front-loaded sentence with no filler. The trailing 'from a window of up to 200' is the one weak spot because it is ambiguous and raises a question it does not answer.
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 carries the return shape and annotations carry the safety profile, so the description only needs to fix the direction of the lookup, which it does. The unexplained 200-versus-50 discrepancy is the remaining 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?
Schema coverage is 67%: paper_id and limit are documented in the schema, while sort_by has only an enum. The description adds nothing about accepted id formats, limit behavior, or what the 'window of up to 200' means relative to the limit parameter, so it stays at the baseline.
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 names a specific resource and direction: 'papers the given paper cites (its bibliography)'. That wording implicitly separates it from get_citations, which covers the opposite direction, though it never names that sibling.
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?
Usage is inferable from the phrase 'cites (its bibliography)', so an agent can tell this is a backward-reference lookup. But there is no explicit when-to-use statement and no mention of alternatives such as get_citations or find_related_papers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search arXiv directly. Use sort_by='newest' to find the latest preprints in a category.
Results have no citation counts; call get_paper_details for those.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results | |
| query | Yes | Keywords or an arXiv field query like 'ti:transformer' | |
| sort_by | No | relevance | |
| year_to | No | Publication year bound | |
| category | No | arXiv category such as cs.CV, cs.RO, cs.LG | |
| year_from | No | Publication year bound |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety and side-effect profile is fully covered. The description adds useful output context — that results carry no citation counts — which is genuinely beyond the annotations, but it says nothing about result limits, pagination or coverage of arXiv's corpus.
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?
Three short sentences, front-loaded with the core action, then a usage tip, then a pointer to a sibling. Every sentence carries information and there is no filler.
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 rich annotations, an output schema, and near-complete parameter documentation, the description needs only to add routing and output caveats, which it does. The missing piece is an explicit statement of how this differs from search_papers.
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 83%, so parameters are largely self-documenting; the description only adds meaning to sort_by by tying 'newest' to recency-oriented browsing. It adds nothing about query syntax, year bounds or category filtering beyond what the schema states.
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 verb and resource: 'Search arXiv directly.' The word 'directly' hints that this is arXiv-only, implicitly distinguishing it from the sibling search_papers, but that contrast is never made explicit.
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?
Gives a concrete usage tip ('Use sort_by="newest" to find the latest preprints in a category') and routes the agent to get_paper_details when citation counts are needed. It stops short of saying when this tool is preferable to the sibling search_papers, so alternatives are only partially addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search papers on Semantic Scholar (all venues, with citation counts and abstracts).
Best for finding established or influential work. Use search_arxiv for brand-new preprints.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results | |
| query | Yes | Keywords, e.g. 'LiDAR moving object segmentation' | |
| sort_by | No | relevance | |
| year_to | No | Publication year bound | |
| year_from | No | Publication year bound | |
| min_citations | No | Minimum citation count |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds value by disclosing result content (citation counts, abstracts) and venue breadth (all venues). No mention of rate limits, pagination, or result caps, but an output schema exists to carry return structure, so a 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?
Two short sentences, zero filler, with the core purpose front-loaded and the disambiguation immediately after. Every sentence earns its place.
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 6-parameter read-only search tool with an output schema, the description covers purpose, source scope, and the main alternative. Sort and citation-filter behavior is left entirely to the schema, which is acceptable given high coverage, but a hint on sorting or result shape would complete it.
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 83%, with query, limit, year bounds, and min_citations documented in the schema; only sort_by lacks a description there. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.
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 verb (search), resource (papers), and source (Semantic Scholar), plus scope details: all venues, citation counts, abstracts. The second sentence distinguishes it from search_arxiv by naming the sibling and the condition that selects it.
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?
Explicit guidance: 'Best for finding established or influential work' and 'Use search_arxiv for brand-new preprints' gives a clear when-to-use plus an alternative. Doesn't address the other siblings (get_paper_details, find_related_papers) or when-not-to-use beyond the arxiv split, so not quite exhaustive.
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.1.0build_citation_graphexport_bibtexfind_related_papersget_citationsget_paper_detailsget_referencessearch_arxivsearch_papersScored across 8 tools
Each tool targets a distinct operation: discovery (search_papers vs search_arxiv, explicitly differentiated by venue and citation availability), metadata retrieval, forward/backward citation traversal, recommendation, graph construction, and export. The descriptions actively disambiguate the one potentially confusable pair (search_papers / search_arxiv) and cross-reference get_paper_details for missing data.
Uniform snake_case verb_noun pattern (search_*, get_*, find_*, build_*, export_*) with verbs that accurately signal the action type. No mixing of conventions, and the small verb variety reflects genuinely different operations rather than stylistic drift.
Eight tools is a tight, well-scoped surface for an academic literature server, with no redundant entries. Each tool covers a distinct step in the research workflow and none appear to be filler.
The surface covers the core scholarly lifecycle: discovery, metadata, forward/backward citation traversal, recommendation, graph analysis, and citation export. Minor gaps remain—no author-centric tools (search/list papers by author, author profiles) and no batch multi-paper details fetch, which agents must work around with repeated calls.
Search arXiv/Semantic Scholar/OpenAlex + medical evidence (PubMed/Europe PMC) + LaTeX/PDF tools.
Academic paper search, scientific literature, citation analysis, arXiv & semantic related-work.
Search arXiv and ACL Anthology, retrieve citations and references, and browse web sources to accel…
Research paper search with real citations and reference formatting for AI assistants