scopus-mcp

Overview Schema Source Related Servers Discussions Admin

scopus_get_citations_overview

Read-onlyIdempotent

Retrieve a year-by-year citation timeline for a paper to track research impact and citation trends over time. Requires a Scopus ID and optional start and end years.

Instructions

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.

Prefer scopus_get_citation_count when you only need one total - it is a single cheap lookup. Use this when the shape of the citation curve over time matters.

Access depends on your Elsevier endpoint entitlement. An institutional token or approved network may be required; use scopus_check_access to diagnose access before retrying authorization failures.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "scopus_id": "<scopus_id>"
    },
    "name": "scopus_get_citations_overview"
  }
}

Input Schema

Name	Required	Description
`end_year`	No	Last year of citation range; defaults to current year
`scopus_id`	Yes	Scopus numeric ID of the paper
`start_year`	No	First year of citation range

Output Schema

Name	Required	Default
`source`	No	scopus
`served_at`	No
`retrieved_at`	No
`total_citations`	Yes
`citations_by_year`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedNov 6, 2026

addedInput schema / properties / end_year / anyOf

Added value: +[
+  {
+    "minimum": 1960,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / end_year / default
```
Previous value: -2025New value: +null
```

changedInput schema / properties / end_year / description

Previous value: -"Last year of citation range"New value: +"Last year of citation range; defaults to current year"

removedInput schema / properties / end_year / maximum
```
Removed value: -2030
```
removedInput schema / properties / end_year / minimum
```
Removed value: -1960
```
removedInput schema / properties / end_year / type
```
Removed value: -"integer"
```
removedInput schema / properties / start_year / maximum
```
Removed value: -2030
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "citations_by_year": {
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "title": "Citations By Year",
+      "type": "object"
+    },
+    "retrieved_at": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Retrieved At"
+    },
+    "served_at": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Served At"
+    },
+    "source": {
+      "default": "scopus",
+      "title": "Source",
+      "type": "string"
+    },
+    "total_citations": {
+      "anyOf": [
+        {
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Total Citations"
+    }
+  },
+  "required": [
+    "total_citations",
+    "citations_by_year"
+  ],
+  "title": "CitationsOverviewResult",
+  "type": "object"
+}

First observedv0.1.0Jun 23, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the read-only/idempotent/non-destructive safety profile, and the description adds context they cannot express: the entitlement dependency on the Elsevier endpoint, that an institutional token or approved network may be needed, and the recommended diagnostic path (scopus_check_access) before retrying authorization failures. That is meaningful operational disclosure beyond structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then prerequisites, alternatives, and access notes in logical order with no redundancy. The 'Useful for tracking research impact and citation trends' line is mild justification padding but supports the usage decision.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter read tool with an output schema already describing return values, the description covers everything an agent needs: what it returns, prerequisites for obtaining the ID, when to choose it over the cheaper sibling, and how to resolve authorization failures.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description reinforces that a Scopus ID is required and that results are bounded by the date range, but adds no format or edge-case detail (e.g., behavior when start_year exceeds end_year). Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Get a year-by-year citation timeline for a paper') and immediately clarifies the return shape (citation counts per calendar year). It is clearly distinguished from the total-count sibling by the explicit note about 'shape of the citation curve' mattering.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use guidance ('Use this when the *shape* of the citation curve over time matters'), names the alternative to prefer for a total (scopus_get_citation_count, described as 'a single cheap lookup'), and states a prerequisite workflow (scopus_search or scopus_get_abstract first to obtain the scopus_id).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server