Skip to main content
Glama
u9401066

pubmed-search-mcp

by u9401066
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

diagnose_institutional_access

Read-onlyIdempotent

Diagnose why institutional fulltext access fails or succeeds for an article by probing direct fetch, EZproxy, and OpenURL paths and reporting each outcome.

Instructions

Diagnose why institutional fulltext access succeeds or fails for an article.

Runs up to three probes and reports each path's outcome:

  1. Direct fetch (Phase 1, IP-aware) — follows https://doi.org/<doi> and classifies whether the publisher served fulltext, a paywall, or a login page. Works automatically when your network IP is on the publisher's institutional allow-list (campus / VPN).

  2. EZproxy fetch (Phase 2, BYO-cookie) — rewrites the publisher hostname to your library's EZproxy host and replays your exported browser session cookie. Configured via env vars:

    • EZPROXY_HOST (e.g. ezproxy.lib.ntu.edu.tw)

    • EZPROXY_COOKIE_FILE (path to browser-exported cookies.json)

    • EZPROXY_ENABLED=1

  3. OpenURL handoff — generated for you to open manually in a browser when the automated paths fail.

Usage: diagnose_institutional_access( source={"kind": "doi", "value": "10.1097/ALN.0000000000003599"} )

diagnose_institutional_access(
    source={"kind": "pmid", "value": "38353755"},
    try_ezproxy=False
)

Args: source: Exactly one PMID or DOI. A PMID is resolved to a DOI when possible so direct and EZproxy probes can run. try_direct: Run the Phase 1 direct probe (default True). try_ezproxy: Run the Phase 2 EZproxy probe (default True).

Returns: Markdown report listing every probe's status, classification, and advice on the next action to take.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sourceYes
try_directNo
try_ezproxyNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.7.2
    • addedInput schema / $defs
      Added value: +{
+  "DOISource": {
+    "additionalProperties": false,
+    "description": "An explicit DOI.",
+    "properties": {
+      "kind": {
+        "const": "doi",
+        "title": "Kind",
+        "type": "string"
+      },
+      "value": {
+        "maxLength": 512,
+        "minLength": 7,
+        "pattern": "^10\\.[0-9]{4,9}/",
+        "title": "Value",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "value"
+    ],
+    "title": "DOISource",
+    "type": "object"
+  },
+  "PMIDSource": {
+    "additionalProperties": false,
+    "description": "An explicit PubMed identifier.",
+    "properties": {
+      "kind": {
+        "const": "pmid",
+        "title": "Kind",
+        "type": "string"
+      },
+      "value": {
+        "maxLength": 20,
+        "pattern": "^[1-9][0-9]{0,19}$",
+        "title": "Value",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "value"
+    ],
+    "title": "PMIDSource",
+    "type": "object"
+  }
+}
    • addedInput schema / additionalProperties
      Added value: +false
    • removedInput schema / properties / doi
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Doi"
-}
    • removedInput schema / properties / pmid
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Pmid"
-}
    • addedInput schema / properties / source
      Added value: +{
+  "discriminator": {
+    "mapping": {
+      "doi": "#/$defs/DOISource",
+      "pmid": "#/$defs/PMIDSource"
+    },
+    "propertyName": "kind"
+  },
+  "oneOf": [
+    {
+      "$ref": "#/$defs/PMIDSource"
+    },
+    {
+      "$ref": "#/$defs/DOISource"
+    }
+  ],
+  "title": "Source"
+}
    • addedInput schema / required
      Added value: +[
+  "source"
+]
    • changedOutput schema / (root)
      Previous value: -{
-  "properties": {
-    "result": {
-      "title": "Result",
-      "type": "string"
-    }
-  },
-  "required": [
-    "result"
-  ],
-  "title": "diagnose_institutional_accessOutput",
-  "type": "object"
-}New value: +null
  2. First observedv0.5.16

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare read-only/idempotent/open-world, but the description adds substantial operational context beyond them: a three-phase probe strategy, IP-awareness, BYO-cookie EZproxy replay, the specific env vars required, and a manual OpenURL handoff. It also discloses that a PMID is converted to a DOI before probing.

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 the one-line purpose, then a numbered probe list, usage examples, and args/returns sections — well organized and largely waste-free. It is on the long side, but the length is justified by the multi-phase behavior and configuration requirements.

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?

No output schema exists, and the description compensates by describing the return value ('Markdown report listing every probe's status, classification, and advice'). Combined with the phase breakdown and required env vars, an agent has everything needed to invoke and interpret the tool correctly.

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 description coverage is 0%, so the description carries the burden and largely does: 'source' is explained as exactly one PMID or DOI with the PMID-to-DOI resolution note, and try_direct/try_ezproxy are mapped to Phase 1 and Phase 2 with their defaults. Minor gap: it doesn't restate the DOI/PMID value formats already enforced by the schema patterns.

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 ('Diagnose why institutional fulltext access succeeds or fails for an article') and enumerates the three probe phases, which cleanly separates it from siblings like test_institutional_access and configure_institutional_access. An agent can identify the tool's job without opening the schema.

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 conditions under which each probe runs (IP allow-list auto-works; EZproxy requires env vars; OpenURL is a manual fallback) and provides concrete usage examples with try_ezproxy=False. However, it never explicitly routes the agent against alternatives such as test_institutional_access or get_fulltext, leaving that comparison to inference.

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