Skip to main content
Glama
u9401066

pubmed-search-mcp

by u9401066
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

build_citation_tree

Read-onlyIdempotent

Construct a citation tree from a single PubMed ID, mapping who cites it and what it references. Set depth and direction, then export to Cytoscape, GraphML, Mermaid, or other graph formats.

Instructions

Build a citation tree (network) from a single article.

🌳 Creates a visual citation network showing research lineage:

  • Forward (citing): Who cites this paper? (newer research)

  • Backward (references): What does this paper cite? (foundational work)

⚠️ IMPORTANT: Only accepts ONE PMID at a time to control API load. For multiple papers, call this tool separately for each.

đź“Š Output Formats (output_format parameter):

  • "cytoscape": Cytoscape.js format (default, academic standard)

  • "g6": AntV G6 format (modern, high-performance)

  • "d3": D3.js force graph format (flexible, Observable)

  • "vis": vis-network format (simple, quick prototypes)

  • "graphml": GraphML XML (desktop tools: Gephi, yEd, VOSviewer)

  • "mermaid": Mermaid diagram (VS Code preview, Markdown)

Args: pmid: Single PubMed ID (e.g., "12345678"). Only ONE PMID accepted - do NOT pass multiple. depth: How many levels to traverse (1-3, default 2). - depth=1: Direct citations/references only - depth=2: Also get citations of citations (recommended) - depth=3: Maximum depth (can be slow, ~100+ API calls) direction: Which direction to build the tree: - "forward": Only citing articles (who cites this) - "backward": Only references (what this cites) - "both": Both directions (default, recommended) limit_per_level: Max articles to fetch per node per level (default 5) output_format: Graph format for visualization (default "cytoscape") - "cytoscape": Cytoscape.js (academic standard, bioinformatics) - "g6": AntV G6 (modern, TypeScript, great for large graphs) - "d3": D3.js force layout (most flexible, Observable notebooks) - "vis": vis-network (simple and easy) - "graphml": GraphML XML (Gephi, VOSviewer, yEd, Pajek) - "mermaid": Mermaid diagram (preview in VS Code Markdown)

Returns: Markdown summary followed by JSON with graph data in the requested format. Includes metadata and statistics regardless of format.

Example usage: # Build 2-level tree for a paper (default Cytoscape.js format) build_citation_tree(pmid="33475315", depth=2, direction="both")

# Use AntV G6 format for modern web visualization
build_citation_tree(pmid="33475315", depth=2, output_format="g6")

# Export GraphML for Gephi analysis
build_citation_tree(pmid="33475315", depth=2, output_format="graphml")

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pmidYes
depthNo
directionNoboth
output_formatNocytoscape
limit_per_levelNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed17 schema fields changedv0.7.2
    • addedInput schema / additionalProperties
      Added value: +false
    • removedInput schema / properties / depth / anyOf
      Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "string"
-  }
-]
    • addedInput schema / properties / depth / maximum
      Added value: +3
    • addedInput schema / properties / depth / minimum
      Added value: +1
    • addedInput schema / properties / depth / type
      Added value: +"integer"
    • addedInput schema / properties / direction / enum
      Added value: +[
+  "forward",
+  "backward",
+  "both"
+]
    • removedInput schema / properties / include_details
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "boolean"
-    },
-    {
-      "type": "string"
-    }
-  ],
-  "default": true,
-  "title": "Include Details"
-}
    • removedInput schema / properties / limit_per_level / anyOf
      Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "string"
-  }
-]
    • addedInput schema / properties / limit_per_level / maximum
      Added value: +20
    • addedInput schema / properties / limit_per_level / minimum
      Added value: +1
    • addedInput schema / properties / limit_per_level / type
      Added value: +"integer"
    • addedInput schema / properties / output_format / enum
      Added value: +[
+  "cytoscape",
+  "g6",
+  "d3",
+  "vis",
+  "graphml",
+  "mermaid"
+]
    • removedInput schema / properties / pmid / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "integer"
-  }
-]
    • addedInput schema / properties / pmid / maxLength
      Added value: +512
    • addedInput schema / properties / pmid / minLength
      Added value: +1
    • addedInput schema / properties / pmid / type
      Added value: +"string"
    • changedOutput schema / (root)
      Previous value: -{
-  "properties": {
-    "result": {
-      "title": "Result",
-      "type": "string"
-    }
-  },
-  "required": [
-    "result"
-  ],
-  "title": "build_citation_treeOutput",
-  "type": "object"
-}New value: +null
  2. First observedv0.5.16

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral detail: API load control via single-PMID restriction, performance caveats for depth=3 ('~100+ API calls'), return format (Markdown summary followed by JSON graph data), and the guarantee that metadata and statistics are included regardless of format. This goes well beyond what annotations provide.

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?

The description is well-organized with clear headers, bullet lists, and practical examples, and the critical single-PMID warning is front-loaded. However, it is somewhat redundant: the output_format options are listed twice—once in the overview and again in the Args section—with overlapping wording. Some trimming would make it tighter without losing value.

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 tool with five parameters, no output schema, and multiple dependent concepts, the description is remarkably complete. It covers input constraints, parameter semantics, performance behavior, output structure, format options, and example invocations. An agent has everything needed to select and invoke the tool correctly, including how to interpret the returned data.

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

Parameters5/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 the full burden of explaining parameters, and it does. Each parameter—pmid, depth, direction, limit_per_level, output_format—receives meaningful semantics including examples, default values, allowed ranges, and format-specific use cases. The description fully compensates for the empty schema descriptions.

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 opens with 'Build a citation tree (network) from a single article,' a specific verb-resource pairing that clearly defines the tool's function. It further distinguishes itself from siblings like find_citing_articles and get_article_references by emphasizing the visual network/lineage aspect across both citing and referenced directions, making the tool's unique purpose unmistakable.

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?

The description provides clear usage context: it accepts only one PMID at a time, explains multi-paper usage, and recommends defaults like depth=2 and direction='both'. However, it does not explicitly instruct when to prefer this tool over sibling tools such as find_citing_articles or get_article_references, nor does it state exclusions beyond the single-PMID constraint.

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