Skip to main content
Glama
cyanheads

pubmed-mcp-server

by cyanheads
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Pubmed Spell Check

pubmed_spell_check
Read-only

Spell-check a PubMed search query against NCBI ESpell and get the corrected query back. Use after a zero-hit or thin pubmed_search_articles result, or when a drug, gene, disease, or author name may be misspelled.

Instructions

Spell-check a PubMed search query against NCBI ESpell and get the corrected query back. Use after a zero-hit or thin pubmed_search_articles result, or when a drug, gene, disease, or author name may be misspelled. Corrections are applied in place, so field tags, operators, spacing, and gene symbols stay as written (alzhiemer diseese treatmnt outcomse → alzheimer disease treatment outcomes). Words in all capitals, with digits or non-ASCII letters, or differing only in case are never changed, words after a number or symbol ESpell skips are left as written, and hasSuggestion is false when no correction was applied. Re-run the search with corrected.

Input Schema

NameRequiredDescriptionDefault
queryYesPubMed search query to spell-check. Must carry a term: a value of only whitespace or invisible characters, such as a zero-width space, is rejected rather than sent to ESpell.

Output Schema

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
originalNoOriginal query
correctedNoThe query with ESpell's accepted corrections applied in place; field tags, operators, spacing, and words in capitals or with digits are kept as written. Same as `original` when `hasSuggestion` is false.
hasSuggestionNoWhether at least one correction was applied to `corrected`

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv2.10.22
    • changedOutput schema / properties / corrected / description
      Previous value: -"Corrected query (same as original if no suggestion)"New value: +"The query with ESpell's accepted corrections applied in place; field tags, operators, spacing, and words in capitals or with digits are kept as written. Same as `original` when `hasSuggestion` is false."
    • changedOutput schema / properties / hasSuggestion / description
      Previous value: -"Whether NCBI suggested a correction"New value: +"Whether at least one correction was applied to `corrected`"
  2. Changed3 schema fields changedv2.10.19
    • changedInput schema / properties / query / description
      Previous value: -"PubMed search query to spell-check. Must carry a term: a blank or whitespace-only value is rejected rather than sent to ESpell."New value: +"PubMed search query to spell-check. Must carry a term: a value of only whitespace or invisible characters, such as a zero-width space, is rejected rather than sent to ESpell."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `queue_full`: The local NCBI request queue shed the call — the queue is full, or the call cannot start before its total deadline (for example behind the cooldown that follows an NCBI 429). `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). `blank_query`: The query holds no search term once whitespace, and anything the tool strips before searching, are removed — so NCBI would receive a blank term. pubmed_search_articles strips markup, bracketed field tags, and parentheses, so a bare field tag such as `[pdat]` or empty parentheses `()` count as blank there. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `queue_full`: The local NCBI request queue shed the call — the queue is full, or the call cannot start before its total deadline (for example behind the cooldown that follows an NCBI 429). `ncbi_unreachable`: NCBI E-utilities failed on every attempt the retry budget allowed — retries ran out, or the next backoff would overrun the total deadline. `ncbi_rate_limited`: NCBI answered HTTP 429 (too many requests) and the call stopped on it — retries ran out, the next backoff would overrun the total deadline, or the Retry-After NCBI named outlasts the time left or the 30-second backoff cap. `ncbi_deadline_exceeded`: The total NCBI request deadline expired before NCBI answered successfully — mid-request, while queued, or during a retry backoff. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). `blank_query`: The query contains no search term: nothing is left once whitespace and invisible characters such as a zero-width space are disregarded. pubmed_search_articles and pubmed_europepmc_search first decode HTML entities and also disregard markup and parentheses, so `()`, `<b></b>`, and `&nbsp;` hold no term there; pubmed_search_articles also disregards bracketed field tags such as `[pdat]`. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
-  "queue_full",
-  "ncbi_unreachable",
-  "ncbi_deadline_exceeded",
-  "ncbi_invalid_response",
-  "ncbi_resource_not_found",
-  "blank_query"
-]New value: +[
+  "queue_full",
+  "ncbi_unreachable",
+  "ncbi_rate_limited",
+  "ncbi_deadline_exceeded",
+  "ncbi_invalid_response",
+  "ncbi_resource_not_found",
+  "blank_query"
+]
  3. Changed1 schema field changedv2.10.18
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `queue_full`: Local NCBI request queue is at capacity. `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). `blank_query`: The query holds no search term once whitespace, and any markup the tool strips first, are removed — so NCBI would receive a blank term. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `queue_full`: The local NCBI request queue shed the call — the queue is full, or the call cannot start before its total deadline (for example behind the cooldown that follows an NCBI 429). `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). `blank_query`: The query holds no search term once whitespace, and anything the tool strips before searching, are removed — so NCBI would receive a blank term. pubmed_search_articles strips markup, bracketed field tags, and parentheses, so a bare field tag such as `[pdat]` or empty parentheses `()` count as blank there. Other values are possible when a failure originates below the handler."
  4. Changed3 schema fields changedv2.10.12
    • changedInput schema / properties / query / description
      Previous value: -"PubMed search query to spell-check"New value: +"PubMed search query to spell-check. Must carry a term: a blank or whitespace-only value is rejected rather than sent to ESpell."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `queue_full`: Local NCBI request queue is at capacity. `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `queue_full`: Local NCBI request queue is at capacity. `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). `blank_query`: The query holds no search term once whitespace, and any markup the tool strips first, are removed — so NCBI would receive a blank term. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
-  "queue_full",
-  "ncbi_unreachable",
-  "ncbi_deadline_exceeded",
-  "ncbi_invalid_response",
-  "ncbi_resource_not_found"
-]New value: +[
+  "queue_full",
+  "ncbi_unreachable",
+  "ncbi_deadline_exceeded",
+  "ncbi_invalid_response",
+  "ncbi_resource_not_found",
+  "blank_query"
+]
  5. Changed6 schema fields changedv2.10.4
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "original",
+      "corrected",
+      "hasSuggestion"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]
    • addedOutput schema / properties / error
      Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `queue_full`: Local NCBI request queue is at capacity. `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "queue_full",
+            "ncbi_unreachable",
+            "ncbi_deadline_exceeded",
+            "ncbi_invalid_response",
+            "ncbi_resource_not_found"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}
    • removedOutput schema / required
      Removed value: -[
-  "original",
-  "corrected",
-  "hasSuggestion"
-]
  6. Addedv2.7.6
  7. Removedv2.7.4
  8. Addedv2.3.2

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare readOnlyHint and openWorldHint, but the description discloses real behavioral detail: corrections are applied in place preserving tags/operators/spacing, capitals and digit/non-ASCII tokens are never altered, tokens after numbers or symbols ESpell skips are left as written, and hasSuggestion is false when nothing changed. This is unusually rich context beyond the structured fields.

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?

Purpose and trigger are front-loaded in the first two sentences, which is exactly right. The middle sentence is dense and packs many edge-case rules into one breath, but every clause conveys actionable behavior, so nothing is wasted.

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?

An output schema exists, so return values need not be enumerated; the description instead supplies the one output field agents must key on (hasSuggestion) and the corrected payload to re-use. For a single-parameter read tool, nothing an agent needs to call it correctly is missing.

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 100% and the single query parameter is fully documented in the schema, including the whitespace/zero-width rejection rule. The description adds the illustrative example ('alzhiemer diseese treatmnt outcomse') but no syntax or format information beyond what the schema already carries, so baseline 3 applies.

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?

Names a specific verb and resource ('Spell-check a PubMed search query') and the backend ('NCBI ESpell'), plus the outcome ('get the corrected query back'). It is immediately distinguishable from siblings like pubmed_search_articles or pubmed_lookup_mesh without opening any 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?

Explicitly names the trigger condition and the sibling to check ('Use after a zero-hit or thin pubmed_search_articles result') plus a second scenario ('when a drug, gene, disease, or author name may be misspelled'). It even tells the agent the follow-up action ('Re-run the search with corrected'), closing the loop.

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