The Scopus MCP server connects AI agents to the Elsevier Scopus academic database, enabling scholarly research tasks across 100+ million records.
Search academic papers (scopus_search): Perform Boolean searches using field codes like TITLE-ABS-KEY, AUTH, AFFIL, PUBYEAR, and DOCTYPE to find relevant scholarly publications.
Retrieve full paper details (scopus_get_abstract): Fetch complete records including title, abstract, authors, affiliations, keywords, subject areas, citation count, DOI, and open-access status — via Scopus ID, DOI, EID, or PubMed ID.
Get researcher profiles (scopus_get_author): Look up an author's h-index, total citations, document count, institutional affiliation, subject areas, ORCID, and publication year range.
Search for authors (scopus_search_authors): Find researchers by name, ORCID, or institution.
Search for institutions (scopus_search_affiliations): Discover affiliation records by name or country to support filtering.
Get citation counts (scopus_get_citation_count): Quickly retrieve a paper's total citation count via Scopus ID or DOI.
Analyze citation trends (scopus_get_citations_overview): Get a year-by-year citation timeline to track a paper's research impact over time.
Pre-defined workflows: Access prompts for systematic literature reviews, author impact analyses, and research trend queries.
Reference resources: Consult Boolean query syntax guides, Scopus subject area codes, and API usage guidelines.
CLI utility: Use as a standalone command-line tool for one-off queries, API key validation, and scripting.
Automatic rate limit handling: The server manages API rate limits, pausing requests as needed to avoid exceeding quotas.
Provides tools to search and retrieve academic papers, author profiles, and citation data from the Scopus database.
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., "@scopus-mcp search for papers on machine learning in cancer from 2020"
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.
Connects any MCP-compatible AI agent to the Elsevier Scopus academic database — search 100+ million scholarly records, retrieve full abstracts, analyze author impact, and track citation trends.
Works with: Claude Desktop · Claude Code · Cursor · VS Code Copilot · Windsurf · Zed · Continue.dev · any MCP client
1. Get your Scopus API key (free) at dev.elsevier.com → Register → Create API Key
2. Install and run — pick one method:
# Option A: uvx (recommended — no environment setup needed)
uvx scopus-mcp
# Option B: pip
pip install scopus-mcp
scopus-mcp3. Add to your AI client — see the Configuration section below.
Related MCP server: MCP-scopus
python --version # needs 3.11 or higher
# Install if missing: https://python.org/downloads# Windows
winget install astral-sh.uv
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh# Install and run in a single command
uvx scopus-mcp
# Upgrade later
uv tool upgrade scopus-mcppip install scopus-mcp
# Verify installation
scopus-mcp --helpgit clone https://github.com/JOSETRA44/scopus-mcp.git
cd scopus-mcp
uv sync # installs all dependencies
cp .env.example .env # edit .env with your API key
uv run scopus-mcp # run directly from sourceBesides running as an MCP server, scopus-mcp also installs three equivalent commands — scopus-mcp, scopus, and the short alias scps — as a standalone command-line tool for one-off lookups, testing your API key, or scripting, no MCP client required.
# Install globally as a uv tool (adds scopus / scps / scopus-mcp to PATH)
uv tool install --editable /path/to/scopus-mcp
scopus --help # list all subcommands
scopus check # validate your API key live against each endpoint
scopus search 'TITLE-ABS-KEY("machine learning")' --count 5
scps abstract 85180904906 --type scopus_id
scopus author 7401234567
scopus search-authors "AUTHLASTNAME(Smith)"
scopus search-affiliations "AFFIL(MIT)"
scopus citation-count --doi 10.1016/j.cell.2023.01.001
scopus citations 85180904906 --start-year 2020 --end-year 2024Add --json to any subcommand for raw structured output (useful for piping into jq or scripts).
Running any of the three commands with no subcommand starts the MCP stdio server instead — the mode MCP clients (Claude Desktop, Claude Code, etc.) use. It will sit waiting for input on stdin; that's expected, not a hang.
Subcommand | Equivalent MCP tool |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| (CLI-only) diagnostic — live-checks your key against every endpoint |
Variable | Required | Default | Description |
| Yes | — | Your Elsevier API key |
| No | — | Institutional token (for off-campus / full-text access) |
| No |
| Response cache duration in seconds (0 = disabled) |
| No |
| Retries on rate-limit errors (HTTP 429) |
| No |
| Verbosity: |
Using a
.envfile? Copy.env.example→.envand fill in your key. Never commit it.
Replace YOUR_API_KEY_HERE with your actual Elsevier API key in every config block below.
Config file:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"scopus": {
"command": "uvx",
"args": ["scopus-mcp"],
"env": {
"SCOPUS_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}Restart Claude Desktop after saving. A hammer icon (🔨) in the input bar confirms tools are loaded.
Add to your project's .mcp.json (or .antigravity.json):
{
"mcpServers": {
"scopus": {
"command": "uvx",
"args": ["scopus-mcp"],
"env": {
"SCOPUS_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}From source (local development):
{
"mcpServers": {
"scopus": {
"command": "uv",
"args": [
"--directory", "/absolute/path/to/scopus-mcp",
"run", "scopus-mcp"
],
"env": {
"SCOPUS_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}Run /mcp in the Claude Code prompt to verify — you should see scopus with 7 tools.
Global config: %APPDATA%\Cursor\User\globalStorage\cursor.mcp\mcp.json (Windows)
{
"mcpServers": {
"scopus": {
"command": "uvx",
"args": ["scopus-mcp"],
"env": {
"SCOPUS_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}Create .vscode/mcp.json in your workspace:
{
"servers": {
"scopus": {
"type": "stdio",
"command": "uvx",
"args": ["scopus-mcp"],
"env": {
"SCOPUS_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}Config: %APPDATA%\Codeium\windsurf\mcp_config.json (Windows)
{
"mcpServers": {
"scopus": {
"command": "uvx",
"args": ["scopus-mcp"],
"env": {
"SCOPUS_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}Edit ~/.config/zed/settings.json:
{
"context_servers": {
"scopus": {
"command": {
"path": "uvx",
"args": ["scopus-mcp"],
"env": {
"SCOPUS_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
}Edit .continue/config.yaml:
mcpServers:
- name: scopus
command: uvx
args:
- scopus-mcp
env:
SCOPUS_API_KEY: "YOUR_API_KEY_HERE"command: uvx
args: ["scopus-mcp"]
env: SCOPUS_API_KEY=YOUR_API_KEY_HERE# Interactive setup (auto-detects installed clients)
python setup_mcp.py
# Non-interactive
python setup_mcp.py --key YOUR_API_KEY_HERE --yes
# Dry-run preview
python setup_mcp.py --key YOUR_API_KEY_HERE --dry-run --yesTool | Description |
| Search papers with Boolean queries — TITLE-ABS-KEY, AUTH, AFFIL, PUBYEAR, DOCTYPE… |
| Full paper record by Scopus ID, DOI, EID, or PubMed ID |
| Researcher profile: h-index, total citations, document count, affiliation, ORCID |
| Find researchers by name, ORCID, or institution |
| Find institution records by name or country |
| Quick citation count by Scopus ID or DOI |
| Year-by-year citation timeline for a paper |
Prompts are reusable research workflows that generate structured query strategies.
Prompt | Arguments | Description |
|
| Generates a PICO-framed SLR search strategy with Boolean queries and PRISMA flow template |
|
| Step-by-step plan to evaluate a researcher's h-index, citation trends, and collaboration network |
|
| Decade-by-decade publication trend queries with document type breakdown and OA analysis |
Resources are reference documents agents can read at any time.
Resource URI | Contents |
| Complete Boolean query reference — field codes, operators, wildcards, examples |
| All |
| Tool quota costs, identifier formats, and recommended workflow patterns |
# Find recent papers on a topic
TITLE-ABS-KEY("machine learning" AND cancer) AND PUBYEAR > 2020
# Reviews only
TITLE-ABS-KEY("federated learning") AND DOCTYPE(re)
# By author ID
AU-ID(7401234567) AND SUBJAREA(COMP)
# From a specific institution
AF-ID(60022195) AND TITLE-ABS-KEY("robotics")
# Open access papers in a specific journal
SRCTITLE("Nature Medicine") AND OPENACCESS(1) AND PUBYEAR > 2022
# Cross-disciplinary topic
TITLE-ABS-KEY("climate change") AND (SUBJAREA(ECON) OR SUBJAREA(ENVI))The server tracks rate limits from response headers and sleeps automatically before making calls when quota is exhausted.
Endpoint | Weekly Quota |
Scopus Search | 20,000 |
Abstract Retrieval | 5,000 |
Author Retrieval | 5,000 |
Citation Count | 50,000 |
Citations Overview | 5,000 |
Tip: Use
scopus_get_citation_count(50K quota) for bulk citation checks. Reservescopus_get_abstract(5K quota) for the papers you actually need in detail.
# Fastest check: validates your API key live against every endpoint
scopus check
# Interactive browser UI (recommended for MCP-specific debugging)
npx @modelcontextprotocol/inspector uvx scopus-mcp
# Quick smoke test (server starts and exits cleanly)
echo "" | SCOPUS_API_KEY=your_key uvx scopus-mcp
# Unit tests (from source)
uv sync --group dev
uv run pytest tests/ -v
# Expected: 19 passedcommand not found: uvx
Install uv: https://docs.astral.sh/uv/getting-started/installation/
Configuration error: Missing required environment variable: SCOPUS_API_KEY
Make sure your config's "env" block has "SCOPUS_API_KEY": "your_actual_key" — not a placeholder.
Tools fail with HTTP 401 API key is invalid or expired. Regenerate at dev.elsevier.com.
Tools fail with HTTP 403
Your key may lack Scopus access. An institutional subscription is required for most endpoints. Ask your librarian about SCOPUS_INST_TOKEN.
First run is slow uv downloads and caches the package on first run. Subsequent starts take ~0.2s.
Tools appear but return empty results
Try broadening your query: replace TITLE(...) with TITLE-ABS-KEY(...) or remove PUBYEAR constraints.
scopus-mcp/
├── src/scopus_mcp/
│ ├── server.py # Entry point — dispatches to CLI or FastMCP stdio server
│ ├── cli.py # Terminal CLI (scopus / scps): subcommands + check diagnostic
│ ├── config.py # Env var configuration (pydantic-settings)
│ ├── client.py # Async HTTP client + TTL cache + rate limiter
│ ├── exceptions.py # Error hierarchy
│ ├── formatters.py # Raw Scopus JSON → clean AI-friendly dicts
│ ├── tools/ # 7 MCP tools (search, abstract, author, citations)
│ ├── prompts/ # 3 MCP prompts (SLR, author analysis, trend query)
│ └── resources/ # 3 MCP resources (syntax, subject areas, API reference)
├── scopus-researcher/ # Agent skill (npx skills add JOSETRA44/scopus-mcp@scopus-researcher)
│ ├── SKILL.md
│ └── references/
├── tests/ # Unit tests (19 cases, no network required)
├── setup_mcp.py # Automated config installer for all clients
├── .env.example # Environment variable template
└── pyproject.toml # Package definitionMIT — © 2026 JOSETRA44
Retrieve full paper details from Scopus using any supported identifier.
Identifier types:
scopus_id — Scopus internal numeric ID (e.g. "85123456789")
doi — Digital Object Identifier (e.g. "10.1016/j.labeco.2024.102505")
eid — Electronic ID (e.g. "2-s2.0-85123456789")
pubmed_id — PubMed/MEDLINE numeric ID
Returns: title, full abstract, authors with affiliations, keywords, subject areas, citation count, DOI, and open access status.
| Name | Required | Description | Default |
|---|---|---|---|
| identifier_type | Yes | Type of identifier being provided | |
| identifier | Yes | The identifier value (strip any 'SCOPUS_ID:' prefix from scopus_id) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the return payload in detail (title, abstract, authors, affiliations, keywords, subject areas, citation count, DOI, open access status). With no annotations, the description carries the full burden, and it adequately communicates that this is a read operation with comprehensive output.
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 no fluff, front-loading the core action. The two sections (identifier types and return fields) are clearly separated. Slightly more structured formatting could improve readability but overall efficient.
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 absence of an output schema, the description sufficiently enumerates returned fields. Usage tips (strip prefix) add completeness. No mention of pagination, rate limits, or errors, but for a straightforward retrieval tool, this is 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 coverage is 100%, yet the description adds significant meaning by listing identifier types and noting the stripping of 'SCOPUS_ID:' prefix. This goes beyond the schema's basic descriptions, helping agents construct valid calls.
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 action: 'Retrieve full paper details from Scopus using any supported identifier.' It lists identifier types and what is returned, distinguishing it from sibling tools that search or retrieve other entities.
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 on identifier value formatting (strip 'SCOPUS_ID:' prefix) and lists supported identifier types, helping agents use the correct input. However, does not explicitly state when to use this tool versus siblings like scopus_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a researcher's full Scopus profile by their Scopus Author ID.
Returns: h-index, total citation count, document count, current institutional affiliation, subject areas, ORCID (if available), and publication year range.
To find an author's ID, first use scopus_search_authors. Example author IDs: '7401234567' or '57209123456'.
| Name | Required | Description | Default |
|---|---|---|---|
| author_id | Yes | Scopus Author ID (numeric string, without 'AUTHOR_ID:' prefix) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavior. It lists the return fields (h-index, citation count, etc.) and gives example IDs. However, it does not mention rate limits, authentication needs, or potential error scenarios. The description is adequate but not comprehensive.
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 (3 sentences) with front-loaded purpose, a clear list of return values, and a usage hint. Every sentence adds value.
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 (single parameter, no output schema), the description covers all necessary information: what the tool does, what it returns, and how to obtain the required input. It is complete for an agent to select and invoke correctly.
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 single parameter 'author_id' is documented in the schema (100% coverage). The description adds value by clarifying it is a numeric string, specifying to not include the 'AUTHOR_ID:' prefix, and providing example IDs.
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 action ('Retrieve a researcher's full Scopus profile') and specifies the resource (by Scopus Author ID). It distinguishes from sibling tools by directing users to first use scopus_search_authors to find the ID.
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 states when to use this tool (to get a profile given an ID) and provides a clear alternative (scopus_search_authors) for finding the ID first. While it doesn't list negative cases, the guidance is sufficient for a retrieval tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current total citation count for a paper.
Provide either a Scopus ID or a DOI — at least one is required. This endpoint is lightweight and cached; use it for quick citation lookups without fetching the full abstract.
| Name | Required | Description | Default |
|---|---|---|---|
| scopus_id | No | Scopus numeric ID of the paper | |
| doi | No | DOI of the paper |
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 endpoint is lightweight and cached, indicating performance characteristics. However, it does not mention authentication requirements, rate limits, or any potential 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?
Three sentences with no extraneous information. The purpose is front-loaded, and every word contributes to understanding.
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 simple tool with no output schema, the description covers the key aspects: what it does, how to use it (identifiers), and when to use it. It could be improved by mentioning behavior when both identifiers are provided or error cases.
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%, but the description adds value by clarifying the conditional requirement that at least one of the two parameters must be provided, which is not captured in the schema itself.
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 the current total citation count for a paper, specifying the action and resource. It is distinct from sibling tools like scopus_get_abstract or scopus_get_author.
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 guidance on when to use the tool ('for quick citation lookups without fetching the full abstract') and explains that at least one identifier (Scopus ID or DOI) is required. However, it does not explicitly exclude situations or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a year-by-year citation timeline for a paper.
Returns how many times the paper was cited in each calendar year within the specified date range. Useful for tracking research impact and citation trends over time.
Requires a Scopus ID. Use scopus_search or scopus_get_abstract first to obtain the scopus_id.
| Name | Required | Description | Default |
|---|---|---|---|
| scopus_id | Yes | Scopus numeric ID of the paper | |
| start_year | No | First year of citation range | |
| end_year | No | Last year of citation range |
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 output (citations per year within a date range) and implies a read-only operation. However, it does not explicitly state that the tool is read-only or mention any potential side effects, rate limits, or error conditions. Still, the main behavior is transparent.
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 very concise: two sentences for the main function plus a separate sentence for prerequisites. It is front-loaded with the primary action, and every sentence adds value.
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?
Although there is no output schema, the description adequately explains the return value (citations per year within date range). Combined with the parameter descriptions, the tool is fully understandable for an AI agent to invoke correctly.
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%, so the baseline is 3. The description adds context on how to obtain the scopus_id, which is value beyond the schema definitions for the parameters.
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 gets a year-by-year citation timeline for a paper, with specific verb 'Get' and resource 'citation timeline'. It distinguishes from sibling tools like scopus_get_citation_count by emphasizing the yearly breakdown.
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 explicit guidance: requires a Scopus ID and directs to scopus_search or scopus_get_abstract to obtain it. This tells the agent when to use this tool and what prerequisites are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the Scopus academic database for papers using Boolean query syntax.
Common field codes:
TITLE-ABS-KEY(term) — search title, abstract, and keywords (most useful)
TITLE(term) — title only
AUTH(name) — author name, e.g. AUTH("Smith J")
AFFIL(institution) — author affiliation
PUBYEAR > 2020 — filter by publication year
DOCTYPE(ar) — document type: ar=article, re=review, cp=conference paper
Boolean operators: AND, OR, AND NOT Example: TITLE-ABS-KEY("machine learning" AND cancer) AND PUBYEAR > 2020
Read the scopus://search-syntax resource for the full syntax reference.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Scopus Boolean search query | |
| count | No | Number of results to return (1–25) | |
| start | No | Pagination offset (0-based) | |
| view | No | Response detail: STANDARD or COMPLETE | STANDARD |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as rate limits, authentication requirements, error handling, side effects, or what happens when a query is malformed or returns no results. This is a significant gap 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?
The description is reasonably concise and front-loaded with the main purpose. It uses line breaks for readability and groups related information. A minor improvement could be trimming redundant phrasing, but overall it is efficient.
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 4 parameters, no output schema, and no annotations, the description covers query usage well but lacks information on return values, pagination metadata, error messages, or practical limits. It is complete enough for basic use but not for robust agent decision-making.
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%, so baseline is 3. The description adds value for the 'query' parameter by explaining field codes and syntax, but for other parameters (count, start, view) it offers no additional meaning beyond the schema. It is adequate but not exceptional.
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 'Search the Scopus academic database for papers using Boolean query syntax.' It specifies the action (search), the resource (Scopus academic database), and the method (Boolean query syntax), effectively distinguishing it from sibling tools like scopus_get_abstract and scopus_search_authors.
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 detailed guidance on query syntax, including common field codes, Boolean operators, and an example. It also references a full syntax resource. However, it does not explicitly state when to use this tool vs. alternatives (e.g., scopus_search_authors for author searches), leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for institution and affiliation records in Scopus.
Query examples:
AFFIL(MIT) — by name keyword
AFFIL(Harvard) AND COUNTRY(United States)
AFFIL-ID(60027950) — by Scopus affiliation ID
Returns affiliation_id needed for author searches and filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Affiliation/institution search query | |
| count | No | Number of results (1–25) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description implies read-only behavior with 'search' terminology but does not explicitly confirm safety or disclose any side effects. Adequate for a simple 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?
Very concise; includes query examples and purpose in a few lines. Front-loaded with key action and examples. No redundant 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?
For a simple search tool with two parameters and full schema coverage, the description is complete. It explains query format, parameters, and the significance of the output (affiliation_id). No output schema needed for understanding.
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?
Input schema covers 100% of parameters with descriptions. Description adds value by providing query examples and clarifying that the result is an affiliation_id, which aids understanding beyond schema definitions.
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 'Search for institution and affiliation records in Scopus.' Provides query examples and mentions output purpose (affiliation_id). Distinguishes from sibling tools like scopus_search_authors or scopus_search by focus on affiliations.
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 query examples and explains that output is needed for author searches. Implicitly guides when to use (for affiliations) but does not explicitly exclude alternative tools or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for author profiles in the Scopus author index.
Query field codes:
AUTHLASTNAME(Smith) — last name
AUTHFIRST(John) — first name or initials
ORCID(0000-0002-1234-5678) — ORCID identifier
AF-ID(60027950) — affiliation ID
Example: AUTHLASTNAME(Smith) AND AUTHFIRST(J) AND AFFIL(MIT)
Use scopus_get_author with the returned author_id to fetch full metrics.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Author search query | |
| count | No | Number of results (1–25) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the burden of behavioral disclosure. It describes the search operation and query syntax but lacks details on rate limits, authentication, pagination, or error handling. The schema already covers count constraints, but the description does not add beyond that.
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 only a few sentences. It front-loads the main purpose, then provides key details (field codes, example) and a usage hint. There is no redundancy, and every sentence adds value.
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 lacks an explanation of the return values (output fields). Since there is no output schema, the description should at least mention what information is returned (e.g., author IDs, names). It also does not address authentication or error scenarios. Given the simple nature of the tool, it is adequate but incomplete.
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%, but the query parameter's schema description is generic ('Author search query'). The description adds significant value by listing supported field codes (AUTHLASTNAME, AUTHFIRST, ORCID, AF-ID) and providing an example, which is not present in the schema. This enhances the agent's understanding of how to construct queries.
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 for author profiles in the Scopus author index. It provides query field codes and an example, distinguishing it from sibling tools like scopus_search (general search) and scopus_get_author (retrieves full metrics from an author ID).
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 guides the user to use scopus_get_author with the returned author_id to fetch full metrics, indicating when to switch to an alternative. It also includes query construction guidance with field codes and an example, making usage clear.
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.0scopus_get_abstractscopus_get_authorscopus_get_citation_countscopus_get_citations_overviewscopus_searchscopus_search_affiliationsscopus_search_authorsScored across 7 tools
Each tool targets a distinct operation: paper retrieval, author profiles, citation count, citation timeline, paper search, affiliation search, and author search. No two tools overlap in purpose.
All tools follow the consistent pattern 'scopus_<verb>_<noun>' (e.g., scopus_get_abstract, scopus_search_authors). No mixing of styles or irregular names.
7 tools is a reasonable number for a Scopus API wrapper, covering search, retrieval, and citation tracking without being overwhelming or insufficient.
The tool set covers core Scopus operations (search, retrieve abstracts/authors, citation info). Minor gaps like pagination for large result sets or listing citing papers are absent but not critical for basic use.
Search GitHub, npm, PyPI, StackOverflow, ArXiv from one MCP — built for coding agents.
Scrape, crawl and search the web for AI agents via MCP.
Academic research MCP server for paper search, citation checks, graphs, and deep research.
Web search, scraping, RAG answers with citations, and translation as MCP tools.
