Enables searching and retrieving scholarly papers using arXiv identifiers or URLs, providing access to metadata, citations, and full-text download links through OpenAlex.
Permits resolving scholarly works by their DOI, returning detailed metadata including title, authors, citations, and download links.
Allows finding authors by ORCID identifier, retrieving their publication lists and profiles via OpenAlex.
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., "@OpenAlex MCP search for recent papers on machine learning"
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.
A standalone Model Context Protocol (MCP) server for scholarly search, paper metadata, citation graphs, author and venue resolution, candidate harvesting, API quota visibility, and guarded full-text downloads through OpenAlex.
It uses the official Python MCP SDK with stdio transport and works with any MCP client that can launch a local command. The server is independent of any note-taking application or agent workflow.
This is a community project and is not affiliated with OpenAlex. Metadata and full-text content remain subject to the terms of OpenAlex and the original publishers.
Tool | Purpose |
| Search titles and abstracts or full text, with date, venue, author, topic, OA, arXiv, citation, sorting, and pagination filters |
| Resolve a paper from an OpenAlex W-id, DOI, arXiv ID/URL, or exact title and return detailed metadata |
| Find later works that cite a paper |
| Hydrate a paper's references and rank them by citation count |
| Find authors by name or ORCID |
| Resolve sources, topics, and institutions from names, ISSNs, or OpenAlex IDs |
| Run recent, backfill, topic, venue, citation, author, and slow-window retrieval, then exclude, deduplicate, and fuse results with RRF |
| Show the official |
| Download OpenAlex-hosted PDF or GROBID XML with root-boundary, size, magic-byte, and atomic-write checks |
The current tool responses are in Chinese while paper titles and technical terms remain in their original language.
Related MCP server: OpenAlex MCP Server
You need:
Python 3.12 or newer
An MCP client that supports local stdio servers
You do not need to install Python separately when using most uv workflows: uv can install and manage a compatible Python interpreter for the project.
Use one of the official installation methods below.
curl -LsSf https://astral.sh/uv/install.sh | shHomebrew is also supported:
brew install uvIn PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Or use WinGet:
winget install --id=astral-sh.uv -eRestart the terminal if the installer updated your PATH, then verify the installation:
uv --version
uv python install 3.12See the official uv installation guide for other package managers and uninstall instructions.
Sign in or create an OpenAlex account.
Create or reveal your API key in the API settings page.
Keep the key in a password manager until you add it to your local MCP client configuration.
The server reads the key only from OPENALEX_API_KEY. Never commit the key, paste it into an issue, or put a URL containing api_key=... in logs. OpenAlex quotas and prices can change; use get_api_quota after setup to see the current values for your account.
This is the shortest installation:
uvx --from git+https://github.com/DeyangLiu123/openalex-mcp.git openalex-mcpuvx creates an isolated environment and runs the command. For a reproducible deployment, pin the Git URL to a commit:
uvx --from git+https://github.com/DeyangLiu123/openalex-mcp.git@<commit-sha> openalex-mcpThe command appears to wait when launched in a terminal because it is a stdio MCP server. Normally your MCP client launches it and communicates over stdin/stdout.
uv tool install git+https://github.com/DeyangLiu123/openalex-mcp.git
openalex-mcpVerify where the executable was installed:
uv tool listTo update a VCS installation later:
uv tool install --force git+https://github.com/DeyangLiu123/openalex-mcp.gitgit clone https://github.com/DeyangLiu123/openalex-mcp.git
cd openalex-mcp
uv sync --locked
uv run pytest -m "not live"The local executable is created at:
.venv/bin/openalex-mcp # macOS/Linux
.venv\Scripts\openalex-mcp.exe # WindowsMany desktop and editor clients accept a JSON configuration shaped like this:
{
"mcpServers": {
"openalex": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/DeyangLiu123/openalex-mcp.git",
"openalex-mcp"
],
"env": {
"OPENALEX_API_KEY": "your-api-key"
}
}
}
}The exact configuration filename and location depend on the client. Keep this file local and out of version control because it contains the API key.
For a cloned installation, replace command with the absolute path to .venv/bin/openalex-mcp on macOS/Linux or .venv\\Scripts\\openalex-mcp.exe on Windows, and set args to an empty array.
Codex CLI, the Codex IDE extension, and the Codex desktop experience share the same MCP configuration in ~/.codex/config.toml. Register the server once with the Codex CLI:
codex mcp add openalex \
--env OPENALEX_API_KEY=<your-api-key> \
-- uvx --from git+https://github.com/DeyangLiu123/openalex-mcp.git openalex-mcpVerify the registration:
codex mcp list
codex mcp get openalexRestart Codex or open a new session after changing MCP configuration. In an interactive Codex session, use /mcp to confirm that openalex is connected and that its nine tools are visible.
The equivalent ~/.codex/config.toml entry is:
[mcp_servers.openalex]
command = "uvx"
args = [
"--from",
"git+https://github.com/DeyangLiu123/openalex-mcp.git",
"openalex-mcp",
]
env = { OPENALEX_API_KEY = "your-api-key" }Keep ~/.codex/config.toml private because this form stores the key locally. If you prefer to manage the secret outside Codex configuration, replace the env line with env_vars = ["OPENALEX_API_KEY"], ensure the variable is present in the environment that launches Codex, and restart Codex.
For more detail, see the official Codex MCP documentation.
With the uvx installation method:
claude mcp add --scope user openalex \
-e OPENALEX_API_KEY=<your-api-key> \
-- uvx --from git+https://github.com/DeyangLiu123/openalex-mcp.git openalex-mcpThen verify that Claude Code sees the server:
claude mcp listIf you do not want the literal key in shell history, read it into a temporary environment variable first and use that variable in the registration command:
read -s OPENALEX_API_KEY
export OPENALEX_API_KEY
claude mcp add --scope user openalex \
-e OPENALEX_API_KEY="$OPENALEX_API_KEY" \
-- uvx --from git+https://github.com/DeyangLiu123/openalex-mcp.git openalex-mcp
unset OPENALEX_API_KEYModern coding agents can inspect the repository, install the package, configure their own MCP client, and verify the result. Copy the prompt below into Codex or Claude Code as-is.
Install the OpenAlex MCP server from https://github.com/DeyangLiu123/openalex-mcp.git for me.
Requirements:
1. Inspect the repository README and pyproject.toml before making changes.
2. Check whether Git and uv are installed. If uv is missing, explain the official installation command for my operating system and ask before running a network installer.
3. Use Python 3.12 or newer. Prefer `uvx --from git+https://github.com/DeyangLiu123/openalex-mcp.git openalex-mcp`; use a local clone only if my MCP client requires an absolute executable path.
4. Run the offline test suite if you clone the repository. Do not run live tests or paid download tests without asking me first.
5. Ask me for my OPENALEX_API_KEY only when you are ready to configure the MCP server. Store it only in my local MCP client environment configuration. Never write it into the repository, a tracked file, a chat response, or a log.
6. Configure this current Codex or Claude Code installation with a user-scoped stdio MCP server named `openalex`.
7. Leave OPENALEX_DOWNLOAD_ROOT unset unless I explicitly opt in to file downloads. If I opt in, set it to an absolute directory I approve.
8. Verify that the MCP server is registered and that its nine tools are visible. Then call get_api_quota and perform one low-cost search for three KV cache papers.
9. Report the installed command, configuration location, verification results, and any API cost incurred. Do not create a GitHub release or modify the OpenAlex MCP source repository.Review an agent's proposed commands before approving them, especially network installers, client configuration changes, and any command that includes credentials.
Start a fresh MCP client session after registration and try:
Use OpenAlex to find three papers about KV cache. Then show the key references of the most-cited result.You can also ask the client to call get_api_quota. A successful result should show the daily budget, usage, remaining quota, reset time, current endpoint prices, and the cost accumulated by this MCP server process.
Environment variable | Default | Description |
| unset | Required. The server can start without it, but tools return setup guidance |
|
| OpenAlex API base URL |
|
| OpenAlex content API base URL |
|
| HTTP timeout in seconds |
| unset | File downloads are disabled until this absolute root is configured |
|
| Maximum downloaded file size, 200 MiB by default |
To enable content downloads, add an approved absolute directory to the MCP process environment:
{
"OPENALEX_API_KEY": "your-api-key",
"OPENALEX_DOWNLOAD_ROOT": "/absolute/path/to/papers"
}The download_work_pdf tool may write only to this root or its descendants.
search_works defaults to the more precise title-and-abstract search and supports:
from_date / to_date, or a publication year
venue_ids, author_ids, and topic_ids
oa_only, arxiv_only, and min_citations
sort=relevance|date|citations
page or cursor pagination
OpenAlex often creates a separate source record for each conference year. To inspect one edition, first call resolve_entity(entity_type="source", query="INFOCOM 2026"), verify the canonical name and year, and pass the resulting source ID to search_works(venue_ids=[...]). Prefer ISSN resolution for journals.
OpenAlex W-ids and URLs are resolved directly.
DOI and arXiv inputs use singleton lookups. A missing identifier is reported as not indexed instead of being silently replaced by fuzzy text search.
A title is accepted automatically only when its normalized form matches exactly. Otherwise the server returns up to three candidates for the caller to choose from.
Lists are deduplicated by normalized DOI first and normalized title second.
harvest_candidates is intended for literature alerts and recommendation workflows. Base queries use {"line": "label", "q": "query"} objects and may be combined with a temporary topic, venue IDs, citation seeds, authors, and JSONL exclusion files.
The output reports route counts, per-query coverage, adaptive backfill pages, exclusions, deduplication, RRF scores, and API cost. The free OpenAlex plan does not expose from_created_date, so the default strategy combines a recent window with an older publication-date backfill. It reduces losses from delayed indexing but cannot guarantee retrieval beyond the configured window or maximum page count.
Use get_api_quota as the runtime source of truth. OpenAlex quotas and endpoint prices may change. Typical current prices are:
singleton lookup: free
filter-only list request: about $0.0001
search request: about $0.001
OpenAlex content download: about $0.01
Every tool reports the cost of that call and the total accumulated by the current MCP process. A target file that already exists with overwrite=false is detected before the billable content request.
The client distinguishes invalid credentials, paid-plan restrictions, daily quota exhaustion, and short rate limits. It retries bounded network/server failures and short Retry-After responses. It also serializes unusually broad Boolean searches when required by the OpenAlex API.
download_work_pdf cannot write files until OPENALEX_DOWNLOAD_ROOT is explicitly configured. When enabled:
dest_dir must resolve to the configured root or one of its descendants.
filename must be a basename; absolute paths, .., slashes, backslashes, and NUL are rejected.
Both Content-Length and the actual streamed byte count are bounded.
PDF content must begin with %PDF; XML must have an XML declaration or a <TEI root.
A random temporary file is validated and then atomically installed.
Failures remove only the temporary file and do not overwrite an existing target.
URLs containing the API key are redacted from logs and errors.
Offline tests do not access the network:
uv run pytest -m "not live"Live smoke tests make low-cost OpenAlex requests:
OPENALEX_API_KEY=... uv run pytest -m "live and not paid"The free-plan canary is opt-in because it intentionally checks that a Premium filter is rejected:
OPENALEX_API_KEY=... OPENALEX_EXPECT_FREE_PLAN=1 \
uv run pytest tests/test_live.py::test_created_date_filter_remains_plan_gatedThe content-download smoke test incurs an additional charge and requires a second explicit opt-in:
OPENALEX_API_KEY=... OPENALEX_RUN_PAID_TESTS=1 \
uv run pytest -m "live and paid"Live tests monitor API syntax, quota payloads, title-and-abstract compatibility, Boolean queries, harvesting, and optional content downloads. Online API behavior and data can change, so these canaries require ongoing maintenance.
uv or uvx is not foundRestart the terminal after installation and run uv --version. If it is still missing, follow the PATH instructions printed by the uv installer or consult the official installation guide linked above.
That is normal for a stdio MCP server waiting for a client. Verify it through your MCP client's server list instead of running it interactively.
Set OPENALEX_API_KEY in the environment of the MCP server entry, not only in an unrelated terminal session. Restart the MCP client after changing its configuration.
401: the key is missing or invalid.
403, or a plan-related message: the requested feature requires a higher OpenAlex plan.
Other 429: the daily quota is exhausted or a request-rate limit was reached. Check get_api_quota and Retry-After.
Set OPENALEX_DOWNLOAD_ROOT to an absolute directory and keep dest_dir inside it. Downloads remain intentionally disabled when the variable is absent.
OpenAlex has deprecated filter=field.search: but currently provides no equivalent non-deprecated title-and-abstract-only query. The top-level search= parameter also searches full text and can be substantially noisier. This project isolates the current behavior in text_search_filter() and monitors it with a live canary so a future migration is limited to one compatibility layer.
See CONTRIBUTING.md for development requirements and SECURITY.md for vulnerability reporting.
从 OpenAlex 内容库安全下载 PDF/GROBID XML，仅能写入配置的论文根目录。
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | ||
| work_id | No | ||
| dest_dir | No | ||
| filename | No | ||
| overwrite | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds some behavioral context (safety, write restriction) but lacks details on authentication, rate limits, or parameter-specific behavior. It partially fills the disclosure gap.
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, succinct sentence conveys the core purpose without unnecessary words.
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?
Despite an output schema, the description omits parameter explanations and error handling, making it incomplete for a tool with 5 parameters and zero schema descriptions.
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% and the description does not mention any parameters. The 5 parameters (format, work_id, dest_dir, filename, overwrite) lack any explanation beyond their names, leaving the agent uninformed about valid values or constraints.
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 the tool downloads PDF/GROBID XML from OpenAlex, with a safety guarantee and write restriction. This distinctively separates it from sibling tools like get_work (which retrieves metadata) and search_works.
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 for file download with a location constraint, but does not explicitly contrast with alternatives. Still, it is clear that this tool is for downloading files, not for searching or retrieving metadata.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
读取官方 /rate-limit 今日预算，并同时报告本 MCP 会话累计成本。
| 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 provided. Description only states the action without disclosing behavioral traits such as idempotency, authorization needs, or side effects. Minimal information beyond the name.
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 concise sentences with no redundancy. Information is front-loaded and every word is meaningful.
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's simplicity and existence of output schema, the description covers the core functionality. However, it lacks behavioral context that annotations would normally provide.
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?
No parameters exist, so baseline is 4. Description adds context about what is reported (session cost) beyond the schema, which provides marginal value.
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 explicitly states it reads today's budget from the official /rate-limit and reports cumulative MCP session cost. Verb+resource is specific and distinct from sibling tools which deal with works, authors, etc.
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?
No guidance on when to use this tool versus alternatives. Does not mention prerequisites, exclusions, or context for usage compared to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出引用某篇论文的工作（前向雪球）。
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | date | |
| limit | No | ||
| work_id | No | ||
| from_date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only states the basic function without revealing ordering, pagination, performance characteristics, or required permissions. The phrase 'forward snowball' adds minimal behavior 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 a single sentence, which is concise, but it is too terse and lacks key information. It is front-loaded but under-specified.
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?
Despite having an output schema, the description fails to cover essential usage context such as parameter roles, typical use cases, or behavior variations. The four optional parameters are undocumented in the description.
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 parameters. It implicitly mentions '某篇论文' (a paper) corresponding to work_id, but provides no details on sort, limit, or from_date. Users are left to infer parameter meanings.
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 verb '列出' (list) and the resource '引用某篇论文的工作' (works citing a paper), with a parenthetical hint '前向雪球' (forward snowball) that distinguishes it from backward reference tools like get_references.
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?
No guidance is provided on when to use this tool versus alternatives such as get_references or search_works. The description does not mention context, constraints, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
批量 hydrate 一篇论文的参考文献，默认按被引数排序。
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | citations | |
| limit | No | ||
| work_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It only mentions sorting and batch hydration, but does not clarify if the operation is read-only, requires authentication, or has side effects.
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 (one sentence) but lacks structure. It is entirely in Chinese, which may hinder non-Chinese agents. It does not front-load key information effectively.
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 and no annotations, the description is incomplete. It does not explain the output, required parameters, or the meaning of 'hydrate'. The output schema exists but is unhelpful without description context.
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%. The description only hints at the default for 'sort' parameter. 'limit' and 'work_id' lack any explanation, leaving the agent without crucial semantic context.
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 the tool hydrates references of a paper and sorts by citations by default, making the purpose clear. However, the term 'hydrate' may be jargon and not immediately obvious to all agents.
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?
No explicit guidance on when to use this tool versus siblings like 'get_work' or 'get_citing_works'. The description does not provide context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
取得单篇详情；支持 W-id、DOI、arXiv ID/URL 和标题，歧义标题不会静默取 top1。
| Name | Required | Description | Default |
|---|---|---|---|
| brief | No | ||
| work_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that ambiguous titles will not silently take the top1 result, which is a useful behavioral detail. However, with no annotations present, the description should also cover other traits like error handling or authentication but does not.
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 with front-loaded purpose. No wasted words, but could benefit from adding parameter explanations without becoming verbose.
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?
Output schema exists so return values are handled. However, the description lacks explanation of the `brief` parameter and behavior when no match found. Adequate for a simple tool but with clear gaps.
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 description must compensate. It mentions supported identifiers but does not explain how `work_id` accepts them nor does it address the `brief` parameter at all.
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 the tool retrieves single work details and lists supported identifiers (W-id, DOI, arXiv ID/URL, title), distinguishing it from sibling `search_works` which returns multiple results.
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 for fetching a single work but does not explicitly state when to use alternatives like `search_works` or when not to use this tool. No exclusions or comparative guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
一次并发执行 A1/A2/T/B/C/D/E 召回、全量排除、去重和 RRF 保底融合。
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| queries | No | ||
| venue_ids | No | ||
| author_ids | No | ||
| exclude_ids | No | ||
| topic_query | No | ||
| venue_query | No | ||
| window_days | No | ||
| backfill_days | No | ||
| cite_seed_ids | No | ||
| exclude_files | No | ||
| last_run_date | No | ||
| use_created_date | No | ||
| venue_window_days | No | ||
| slow_min_citations | No | ||
| slow_window_months | No | ||
| conference_patterns | No | ||
| max_pages_per_query | No | ||
| min_unseen_per_query | No | ||
| topic_min_candidates | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the sole source for behavioral traits. It mentions concurrency, exclusion, dedup, and fusion but lacks details on side effects (e.g., whether it is read-only), auth requirements, rate limits, or the nature of 'concurrent' execution.
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, which is concise but overloaded with jargon (A1/A2/T/B/C/D/E) without explanation. Front-loading is adequate but clarity suffers.
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 complexity (20 parameters, multiple retrieval stages) and no annotations, the description is grossly insufficient. Output schema exists but does not compensate for the lack of parameter and behavioral context.
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%, yet the description does not explain any of the 20 parameters. The meaning of parameters like 'limit', 'queries', 'venue_ids', etc., is left entirely to inference.
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 mentions concurrent execution of multiple retrieval stages (A1/A2/T/B/C/D/E), exclusion, dedup, and RRF fusion, giving a general sense of candidate harvesting. However, it does not explain what the acronyms mean or specify output, and it does not clearly distinguish from sibling tools like search_works.
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?
No guidance on when to use this tool vs alternatives (e.g., search_works). No context on prerequisites or typical scenarios is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
把 source/topic/institution 名称解析成 OpenAlex ID。
期刊优先输入 ISSN；会议应按“会议名+年份”（如 INFOCOM 2026）逐年解析， 并同时核对规范名与年份，歧义时不要自动写入配置。USENIX 系会议通常无 OpenAlex source 记录。盘点会议时先 resolve_entity，再把当年 S-id 传给 search_works(venue_ids=[...])。
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| entity_type | No | source |
| 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 notes that USENIX conferences may not have records and warns against auto-writing on ambiguity. However, it does not clarify whether the tool returns multiple candidates or just one, nor details about rate limits or side effects.
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 moderately detailed but each sentence contributes meaning. It is front-loaded with the core purpose and structured logically. A bit lengthy but not verbose.
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 3 optional parameters and an output schema existing, the description covers key usage scenarios (journals, conferences, institutions). It provides workflow integration with search_works. Minor gaps remain for other entity_types and error handling.
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. It implicitly explains that 'query' should contain ISSN for journals and 'conference name+year' for conferences, but does not explicitly describe 'limit' or 'entity_type' beyond default usage. Adds some value but not full coverage.
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 the tool resolves source/topic/institution names to OpenAlex IDs, which is a specific verb-resource combination. It distinguishes from sibling tools like search_works or get_work by focusing on entity name resolution.
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?
Provides explicit guidance: journals prefer ISSN input, conferences should be queried as 'conference name+year', USENIX often lacks records, and advises when to avoid auto-writing. Includes a workflow linking to search_works.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
按姓名或 ORCID 查作者；两者必须恰有一个非空。
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| limit | No | ||
| orcid | 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 full burden. It discloses the constraint of exactly one non-empty, but omits behavior for invalid inputs, error handling, case sensitivity, or limit usage.
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?
Single sentence with no unnecessary words. Front-loaded with verb and resource.
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?
Output schema exists, but description does not mention it. Provides essential constraint but lacks details on limit and error conditions, making it minimally adequate.
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 description adds meaning for name and orcid parameters via the constraint, but does not explain the limit parameter.
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 the tool searches authors by name or ORCID, with a specific constraint. It distinguishes from siblings like search_works, but lacks mention of what results are returned.
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?
Describes when to use (name or ORCID) and the exact constraint. However, it does not specify when not to use or compare to alternatives like search_works.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
检索论文；主题默认只搜 title+abstract，venue 名称应先 resolve 成 S-id。
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| sort | No | relevance | |
| year | No | ||
| limit | No | ||
| query | No | ||
| cursor | No | ||
| oa_only | No | ||
| to_date | No | ||
| from_date | No | ||
| search_in | No | title_abstract | |
| topic_ids | No | ||
| venue_ids | No | ||
| work_type | No | ||
| arxiv_only | No | ||
| author_ids | No | ||
| min_citations | 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 the full burden. It discloses the default search scope and a requirement for venue resolution, but does not mention pagination behavior (cursor/page), sorting, filtering details, rate limits, or output format. With 16 parameters, many behavioral traits are omitted.
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 concise, front-loaded sentences with no redundant information. Every word serves a 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 16 parameters, no parameter descriptions in the schema, and no annotations, the description is highly incomplete. It does not cover how to use most parameters, the return structure (despite an output schema existing but not described), or edge cases. A complex search tool requires more thorough documentation.
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 compensate. It only clarifies two parameters: 'search_in' defaults to title_abstract and 'venue_ids' should use resolved S-ids. The remaining 14 parameters are not explained, leaving the agent to infer from names and defaults.
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 'Search papers', which is a clear verb+resource. It distinguishes from siblings like get_work (single paper) and search_authors (different resource). However, it could be more specific about the scope and what is returned.
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?
Provides two usage tips: default search scope (title+abstract) and that venue names should be resolved to S-ids first. Does not explicitly state when to use this tool versus alternatives like get_citing_works or get_references, nor 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0download_work_pdfget_api_quotaget_citing_worksget_referencesget_workharvest_candidatesresolve_entitysearch_authorssearch_worksScored across 9 tools
Most tools have distinct purposes, but there is potential overlap between `search_works` and `harvest_candidates` as both retrieve works. However, descriptions clarify that `harvest_candidates` uses multi-strategy recall, reducing ambiguity. Overall, tools are well-differentiated.
All tool names follow a consistent snake_case verb_noun pattern (e.g., `get_work`, `search_works`, `resolve_entity`). No mixed conventions or irregular formatting, making the set highly predictable.
With 9 tools, the server is well-scoped for a research database wrapper. Each tool serves a clear purpose without unnecessary clutter, and the count is appropriate for the domain.
Covers core workflows for works (search, fetch, references, citing, PDF download) and author search, but lacks direct access to institution/source details after entity resolution. Minor gaps that agents can work around.
Academic literature search, retrieval, and private library management on top of OpenAlex.
OpenAlex MCP — wraps the OpenAlex API (scholarly works, free, no auth)
Access the OpenAlex academic research catalog — 270M+ publications.
Scholarly search: OpenAlex, Crossref, arXiv, OpenCitations and PubMed in one endpoint.
