scopus-mcp

Overview Schema Source Related Servers Discussions Admin

scopus_analyze_results

Read-onlyIdempotent

Aggregate a bounded Scopus search corpus by cover year, publication source, and affiliation, reporting truncation and continuation so counts reflect only retrieved documents (default 100, max 5000).

Instructions

Aggregate a bounded Scopus search corpus by cover year, publication source and affiliation. Defaults to 100 documents; at most 5000. Reports truncation, continuation and unknown metadata explicitly. Counts describe retrieved documents only; do not extrapolate to all literature. Each institution counts once per document.

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": {
      "query": "<query>"
    },
    "name": "scopus_analyze_results"
  }
}

Input Schema

Name	Required	Default
`view`	No	STANDARD
`query`	Yes
`start`	No
`max_rows`	No

Output Schema

Name	Required	Description	Default
`view`	Yes
`query`	Yes
`source`	Yes
`by_year`	Yes
`unknown`	Yes
`truncated`	Yes
`next_start`	Yes
`started_at`	Yes
`corpus_size`	Yes
`limitations`	Yes
`start_index`	Yes
`stop_reason`	Yes
`completed_at`	Yes
`retrieved_at`	Yes
`total_results`	Yes
`by_affiliation`	Yes
`by_publication`	Yes
`complete_corpus`	Yes
`duplicate_count`	Yes
`retrieval_times`	Yes
`requested_max_rows`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 6, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so safety is covered. The description adds real behavioral context on top: the 100/5000 size bound, explicit truncation/continuation/unknown-metadata reporting, and the semantic constraint that an institution counts once per document. It does not describe output shape or what happens at the 5000 boundary.

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?

Five short sentences, front-loaded with the core action, then bounds, then reporting caveats. Dense and largely waste-free, though the telegraphic phrasing ('Reports truncation, continuation and unknown metadata explicitly') is terse enough to be slightly ambiguous.

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?

An output schema exists, so return-value explanation is not required. The description supplies the caveats an agent needs to interpret aggregates honestly (retrieved-only counts, per-document institution dedup, truncation reporting) and is nearly complete, with the main gap being what 'view' and 'start' do.

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 0%, so the description must carry parameter meaning. It partially does: it restates the 100 default and 5000 cap for max_rows and alludes to continuation (start), but leaves 'start' and the STANDARD/COMPLETE 'view' enum entirely unexplained, which matters since view likely changes result richness.

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

Purpose4/5

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

The first sentence names a specific verb ('Aggregate') and specific grouping dimensions (cover year, publication source, affiliation) over a 'bounded Scopus search corpus', which distinguishes it from the raw-retrieval siblings like scopus_search. It lacks an explicit contrast naming the sibling, but the analyze-vs-search split is inferable.

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

Usage Guidelines3/5

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

It gives implied context (bounded corpus, defaults and caps) and a clear prohibition against extrapolating counts to all literature, which effectively tells the agent when not to use the output. It never says when to choose this over scopus_search or how the 'continuation' path should be driven via start.

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

Deploy Server