Skip to main content
Glama

run_s3_analysis

Runs the S3 pipeline on a Scopus CSV/Excel export to detect research communities, best threshold, and outliers from title and abstract embeddings.

Instructions

Run the S3 pipeline on a Scopus CSV/Excel export (needs Title and Abstract; Year, Cited by, Authors, Author Keywords, References and EID are used if present).

Follows the published S3 method: embeds Title+Abstract (all-mpnet-base-v2), builds the time-ordered S3 graph, scans thresholds 0.75-0.85 and keeps the Leiden (directed modularity) partition with the highest SII (silhouette x retained papers). Set threshold (e.g. 0.78) to reproduce a published run, or community_method="louvain" to reproduce the S3 web app. embedding_model is a key from list_embedding_models or any sentence-transformers model name (ask the user first; default mpnet). Records without title and abstract are dropped and duplicates (same DOI/EID/text, or S3 >= 0.98) are removed unless remove_duplicates=False. map_relations chooses the map, and every answer and report follows it: "text" (default; S3 text similarity, the published method), "hybrid" when the user asks for a hybrid map (screens text plus each citation relation at 5-40% weight, as compare_maps does, and uses the best hybrid if it raises both silhouette and QI, else text), or a specific hybrid the user names: "text+coupling", "text+cocitation", "text+direct" (75%/25%) or weights such as "s3=0.8,coupling=0.2". strict_citations=True stops short titles such as "Introduction" from matching unrelated references. significant_ties_only=True keeps only coupling, co-citation and co-authorship ties that are significant under a degree-preserving null model (in the map and Q35-Q37). Can take several minutes for thousands of papers the first time; embeddings are cached afterwards.

Returns a run_id plus a summary: best threshold, communities, outlier count.

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": {
      "csv_path": "<csv_path>"
    },
    "name": "run_s3_analysis"
  }
}

Input Schema

NameRequiredDescriptionDefault
seedNo
rerunNo
csv_pathYes
end_yearNo
thresholdNo
start_yearNo
map_relationsNotext
embedding_modelNompnet
community_methodNoleiden
strict_citationsNo
remove_duplicatesNo
significant_ties_onlyNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.12.2

TDQS

A4.5/5.0
Behavior5/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 so: it discloses silent data drops (records lacking title/abstract, duplicates by DOI/EID/text or S3 >= 0.98, overridden by remove_duplicates=False), the multi-minute cost on first run with embedding caching afterwards, and that a run_id plus summary is produced. This is exactly the side-effect and cost context an agent needs before invoking a long-running pipeline.

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-loads purpose before configuration, then behaviour, then return value – a logical order. The map_relations sentence is very long and packs three formats into one block, which hurts scannability, but no sentence is pure filler.

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 a 12-parameter, annotation-free pipeline tool this covers the pipeline mechanics, deduplication policy, runtime cost, and output, and an output schema exists so return details are already covered. The omission is year filtering (start_year/end_year) and the rerun/seed semantics, which an agent must otherwise guess.

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 0%, so the description must compensate, and it explains the semantically hard parameters: threshold, community_method, embedding_model (key from list_embedding_models or any sentence-transformers name), the full map_relations vocabulary with weight syntax, strict_citations, significant_ties_only, and remove_duplicates. It leaves seed, rerun, start_year and end_year entirely undiscussed, which is a real gap for four of twelve parameters, though those are comparatively self-evident.

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?

Opens with a specific verb and resource ("Run the S3 pipeline on a Scopus CSV/Excel export") and names the exact required inputs (Title and Abstract) plus optional columns. The published-method framing (mpnet embeddings, time-ordered graph, threshold scan 0.75-0.85, Leiden directed-modularity with SII selection) makes it unmistakable against neighbours like compare_maps or build_report.

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?

Gives concrete selection rules: set threshold to reproduce a published run, community_method="louvain" to match the S3 web app, and choose "hybrid" when the user requests a hybrid map, with compare_maps named as the analogue. It does not state when to prefer this tool over a full alternative workflow (e.g. when a user only wants a threshold scan or a report), so the routing guidance is strong but incomplete.

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