Skip to main content
Glama

compare_maps

Compares text-only and citation-weighted maps using hidden citation links, coherence, stability, and coverage to recommend a map for S3 community analysis.

Instructions

Before the full analysis: which map should S3 use for this corpus? Compares the text map (the published method) with text plus bibliographic coupling, co-citation or direct citation at 5%, 10%, ... 40% weight; citations count only for pairs already close in content (the text floor). extended=True adds the same grid without the floor. 20% of the in-corpus citation links are hidden while the maps are built; each map is scored on the hidden links inside its communities (gain over random communities of the same sizes), on text coherence (TCI gain over random), stability (ARI across seeds and 90% samples) and coverage. A rule fixed in advance recommends a map. Show the user the table and the recommendation, then pass the chosen map to run_s3_analysis as map_relations. Takes a few minutes; embeddings are cached for the run. With run_id instead of csv_path, compares on that run's papers and citation links: use this after enrich_citations, so the comparison uses the exact Scopus reference lists.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "compare_maps"
  }
}

Input Schema

NameRequiredDescriptionDefault
seedNo
run_idNo
csv_pathNo
end_yearNo
extendedNo
start_yearNo
embedding_modelNompnet
strict_citationsNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.16.1

TDQS

A4.5/5.0
Behavior5/5

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

With no annotations supplied, the description carries the full burden and does so: it discloses the held-out-link validation design (20% of in-corpus links hidden), the four scoring axes, that the recommendation rule is fixed in advance, the requirement to show the user the table, and the runtime/caching profile ('takes a few minutes; embeddings are cached for the run'). These are non-obvious operational facts an agent could not infer from the schema.

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?

It opens with the decision it supports, which is the right front-loading, and most clauses carry real information. The middle sentence is an unusually long run-on that bundles weights, the text floor, the held-out protocol, and all four metrics, so it is dense to the point of being hard to scan, but little of it is genuinely expendable.

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 values need not be described, and the description still tells the agent what the result means and what to do with it. For an 8-parameter tool the gap is the undocumented year-range, embedding-model, and strict_citations controls, which leaves some invocation detail to schema inspection.

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 compensate and it only partly does. It explains extended=True (same grid without the text floor) and the run_id-instead-of-csv_path tradeoff, but start_year, end_year, embedding_model, strict_citations, and seed are never mentioned — seed is only obliquely implied by 'stability (ARI across seeds and 90% samples).' Three of eight parameters remain semantically opaque.

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 names a concrete operation (compare the plain text map against text-plus-citation maps at 5%–40% weight), the scoring basis, and the deliverable (a table plus an advance-fixed recommendation). It explicitly separates itself from run_s3_analysis ('then pass the chosen map to run_s3_analysis as map_relations'), so an agent can route between the two without opening either schema.

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?

Timing is stated twice and concretely: 'Before the full analysis' and 'use this after enrich_citations, so the comparison uses the exact Scopus reference lists.' The downstream handoff is spelled out ('pass the chosen map to run_s3_analysis as map_relations'), and the run_id-vs-csv_path branch gives an explicit alternative mode rather than leaving the agent to guess.

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