Skip to main content
Glama
michalhron

Scopus Plus MCP

by michalhron
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

thematic_evolution

Map how research themes evolve across periods: cluster keywords, place themes on strategic diagrams, and track continuations, splits, merges, appearances, disappearances, or a construct’s drift.

Instructions

Themes of a corpus and how they change over time (Cobo et al. 2011; as in bibliometrix's thematic map and thematic evolution). Per period: keyword co-occurrence clusters, each placed in the strategic diagram by Callon centrality and density (motor, basic, niche, emerging or declining); between periods: which themes continue, split, merge, appear or vanish (inclusion index). With construct_terms it follows a construct through the periods: the theme that holds it, where that theme sits, and the keywords it keeps company with, i.e. whether the construct stays central, drifts or dissolves into another. Give ids or a query. Writes JSON, CSV and a PNG of the strategic diagrams. Cost: one abstract request per paper (cached).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idsNoThe papers (Scopus IDs/EIDs; with source='openalex', DOIs or OpenAlex IDs). Use this or query.
queryNoSearch query defining the set, instead of ids.
scopeNoRestrict to journals, by ISSN: a list of ISSNs, or a basket name ('basket_of_eight' / 'ais8': the AIS Senior Scholars' Basket of Eight). ISSNs are used rather than journal names, which Scopus spells inconsistently.
termsNo'author_keywords' (default; papers without them fall back to Scopus index terms), 'all_keywords' (author keywords plus index terms), 'title_abstract' (phrases from title and abstract; for corpora with few keywords). With source='openalex', keywords are OpenAlex's own.author_keywords
sourceNoData source. 'scopus' (default) needs subscriber entitlement for search, citations and references. 'openalex' needs none: IDs may be DOIs, OpenAlex work IDs (W...), or Scopus IDs (resolved to a DOI via Scopus metadata), and results carry OpenAlex IDs. Never mix sources within one analysis.scopus
min_freqNoKeywords must appear in at least this many papers of a period (default 2).
cut_yearsNoFirst years of the later periods, e.g. [2005, 2012] gives up to 2004, 2005-2011 and 2012 on. Default: n_periods of similar size.
n_periodsNoPeriods of similar paper counts when cut_years is not given (default 3).
corpus_fileNoA corpus file from import_records, instead of ids or query.
max_resultsNoWith query: how many papers to include (default 300).
construct_termsNoA construct to follow, e.g. ['organizing vision'].

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses outputs written (JSON, CSV, a strategic-diagram PNG), and a cost/rate note ('one abstract request per paper (cached)'). It also flags entitlement requirements for source='scopus'. It stops short of describing failure modes or how caching resolves, but the key operational traits are present.

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?

Purpose is front-loaded and the paragraph is information-dense, with each clause covering a distinct facet (mechanism, transition types, construct mode, inputs, outputs, cost). It is long, but almost every sentence earns its place; minor compression is possible.

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

Completeness4/5

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

For an 11-parameter analysis tool with no annotations and no output schema, the description covers inputs, the produced artifacts, data-source entitlement, and cost, which is close to sufficient. Authentication details and period-selection edge cases remain implicit.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: how construct_terms behaves ('the theme that holds it, where that theme sits, and the keywords it keeps company with'), why ISSNs are used over journal names, and the prohibition on mixing sources within one analysis. That is value beyond the schema text.

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?

States a specific verb+resource with scope: themes of a corpus and their change over time, decomposed into per-period co-occurrence clusters on the strategic diagram (Callon centrality/density) and between-period transitions via the inclusion index. This is clearly distinguishable from siblings like topic_landscape or research_fronts, and the construct_terms variant is spelled out.

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

Usage Guidelines4/5

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

Explains the input alternatives ('Give ids or a query') and when to use construct_terms ('follows a construct through the periods'). It gives context for the terms enum ('for corpora with few keywords'), but never explicitly names a sibling alternative or states when-not to use this tool, so a 5 is not warranted.

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

Deploy Server

Other Tools