Skip to main content
Glama
cyanheads

pubchem-mcp-server

by cyanheads
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Search Assays

pubchem_search_assays
Read-onlyIdempotent

Search PubChem bioassays by gene symbol, protein name, NCBI Gene ID, or UniProt accession to get assay IDs (AIDs) for a biological target. Page results with offset for further exploration.

Instructions

Find PubChem bioassays associated with a biological target. Search by gene symbol (e.g. "EGFR"), protein name, NCBI Gene ID, or UniProt accession. Returns a page of assay IDs (AIDs) — page past maxResults with offset — which can be explored further with pubchem_get_summary.

Input Schema

NameRequiredDescriptionDefault
offsetNoZero-based index of the first AID to return. Pass the nextOffset from a previous call to read the following page. Default: 0.
maxResultsNoMax AIDs to return per page. The per-call cap is 200: a larger value (up to 1000) returns a page of 200 and is reported in cappedInputs. Popular targets may have thousands of assays; use offset to reach the ones past this page. Default: 50.
targetTypeYesTarget identifier type. "genesymbol" and "proteinname" accept text names; a genesymbol matches the symbol case-insensitively across species, so a human symbol also returns assays on other species' orthologs. "geneid" accepts NCBI Gene IDs. "proteinaccession" accepts UniProt accessions. "geneid" and "proteinaccession" each pin one protein, but return overlapping, different assay sets for it, since PubChem records some assays under only one of the two identifiers; for a complete list for one protein, union both.
targetQueryYesTarget identifier. Examples: "EGFR" (genesymbol), "Epidermal growth factor receptor" (proteinname), "1956" (geneid), "P00533" (proteinaccession; uppercased before lookup, except a PDB chain ID such as the "A" in "1ZHH_A", which is kept as given).

Output Schema

NameRequiredDescriptionDefault
capNoThe page size applied: maxResults, or the per-call cap when maxResults exceeds it.
aidsNoPubChem Assay IDs.
errorNoPresent when the call failed. Absent on success.
shownNoAIDs returned on this page.
noticeNoRecovery guidance when no assays matched, when the offset runs past the result set, or when further pages remain. Absent when this page is complete and non-empty.
offsetNoZero-based index of the first AID returned.
truncatedNoTrue when matching AIDs remain past this page.
nextOffsetNoOffset to pass on the next call to continue past this page. Omitted when no further AIDs match.
targetTypeNoTarget identifier type used: genesymbol, proteinname, geneid, or proteinaccession.
totalFoundNoTotal AIDs found for this target, across all pages.
targetQueryNoTarget identifier searched.
cappedInputsNoInputs that asked for more than their per-call cap, with the value requested and the value served. An ID batch lists the IDs past the cap in unprocessed. Omitted when every input was within its cap.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.8.0
    • changedInput schema / properties / targetType / description
      Previous value: -"Target identifier type. \"genesymbol\" and \"proteinname\" accept text names. \"geneid\" accepts NCBI Gene IDs. \"proteinaccession\" accepts UniProt accessions."New value: +"Target identifier type. \"genesymbol\" and \"proteinname\" accept text names; a genesymbol matches the symbol case-insensitively across species, so a human symbol also returns assays on other species' orthologs. \"geneid\" accepts NCBI Gene IDs. \"proteinaccession\" accepts UniProt accessions. \"geneid\" and \"proteinaccession\" each pin one protein, but return overlapping, different assay sets for it, since PubChem records some assays under only one of the two identifiers; for a complete list for one protein, union both."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `blank_target_query`: targetQuery is empty or whitespace-only. `invalid_geneid_query`: targetType is \"geneid\" but targetQuery contains characters other than digits. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `blank_target_query`: targetQuery is empty or whitespace-only. `invalid_geneid_query`: targetType is \"geneid\" but targetQuery contains characters other than digits. `target_query_rejected`: PubChem refused the target lookup with HTTP 400 — its answer for a targetQuery carrying a line break, another C0 control character other than tab and NUL, or DEL. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
-  "blank_target_query",
-  "invalid_geneid_query"
-]New value: +[
+  "blank_target_query",
+  "invalid_geneid_query",
+  "target_query_rejected"
+]
  2. Changed6 schema fields changedv0.7.0
    • changedInput schema / properties / maxResults / description
      Previous value: -"Max AIDs to return per page (1-200). Popular targets may have thousands of assays; use offset to reach the ones past this page. Default: 50."New value: +"Max AIDs to return per page. The per-call cap is 200: a larger value (up to 1000) returns a page of 200 and is reported in cappedInputs. Popular targets may have thousands of assays; use offset to reach the ones past this page. Default: 50."
    • changedInput schema / properties / maxResults / maximum
      Previous value: -200New value: +1000
    • changedInput schema / properties / targetQuery / description
      Previous value: -"Target identifier. Examples: \"EGFR\" (genesymbol), \"Epidermal growth factor receptor\" (proteinname), \"1956\" (geneid), \"P00533\" (proteinaccession)."New value: +"Target identifier. Examples: \"EGFR\" (genesymbol), \"Epidermal growth factor receptor\" (proteinname), \"1956\" (geneid), \"P00533\" (proteinaccession; uppercased before lookup, except a PDB chain ID such as the \"A\" in \"1ZHH_A\", which is kept as given)."
    • changedOutput schema / properties / cap / description
      Previous value: -"The maxResults cap that was applied."New value: +"The page size applied: maxResults, or the per-call cap when maxResults exceeds it."
    • addedOutput schema / properties / cappedInputs
      Added value: +{
+  "description": "Inputs that asked for more than their per-call cap, with the value requested and the value served. An ID batch lists the IDs past the cap in unprocessed. Omitted when every input was within its cap.",
+  "items": {
+    "additionalProperties": false,
+    "description": "One input served at its per-call cap.",
+    "properties": {
+      "input": {
+        "description": "Input name, e.g. \"maxResults\" or \"cids\".",
+        "type": "string"
+      },
+      "requested": {
+        "description": "Value requested: the page size, or the number of IDs in the batch.",
+        "type": "number"
+      },
+      "served": {
+        "description": "Value served: the per-call cap.",
+        "type": "number"
+      },
+      "unprocessed": {
+        "description": "ID batches only: IDs past the cap, listed in unprocessed in input order.",
+        "type": "number"
+      }
+    },
+    "required": [
+      "input",
+      "requested",
+      "served"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `blank_target_query`: targetQuery is empty or whitespace-only. `invalid_geneid_query`: targetType is \"geneid\" but targetQuery is not a positive integer. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `blank_target_query`: targetQuery is empty or whitespace-only. `invalid_geneid_query`: targetType is \"geneid\" but targetQuery contains characters other than digits. Other values are possible when a failure originates below the handler."
  3. Changed1 schema field changedv0.6.3
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `blank_target_query`: targetQuery is empty or whitespace-only `invalid_geneid_query`: targetType is \"geneid\" but targetQuery is not a positive integer Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `blank_target_query`: targetQuery is empty or whitespace-only. `invalid_geneid_query`: targetType is \"geneid\" but targetQuery is not a positive integer. Other values are possible when a failure originates below the handler."
  4. Changed6 schema fields changedv0.6.1
    • 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": [
+      "aids",
+      "targetType",
+      "targetQuery",
+      "totalFound",
+      "offset"
+    ]
+  },
+  {
+    "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: `blank_target_query`: targetQuery is empty or whitespace-only `invalid_geneid_query`: targetType is \"geneid\" but targetQuery is not a positive integer Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "blank_target_query",
+            "invalid_geneid_query"
+          ],
+          "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: -[
-  "aids",
-  "targetType",
-  "targetQuery",
-  "totalFound",
-  "offset"
-]
  5. Changed10 schema fields changedv0.6.0
    • changedInput schema / properties / maxResults / description
      Previous value: -"Max AIDs to return (1-200). Popular targets may have thousands of assays. Default: 50."New value: +"Max AIDs to return per page (1-200). Popular targets may have thousands of assays; use offset to reach the ones past this page. Default: 50."
    • changedInput schema / properties / maxResults / type
      Previous value: -"number"New value: +"integer"
    • addedInput schema / properties / offset
      Added value: +{
+  "default": 0,
+  "description": "Zero-based index of the first AID to return. Pass the nextOffset from a previous call to read the following page. Default: 0.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}
    • addedOutput schema / properties / nextOffset
      Added value: +{
+  "description": "Offset to pass on the next call to continue past this page. Omitted when no further AIDs match.",
+  "type": "number"
+}
    • changedOutput schema / properties / notice / description
      Previous value: -"Recovery guidance when no assays matched — echoes the target and suggests alternative search types. Absent when assays were returned."New value: +"Recovery guidance when no assays matched, when the offset runs past the result set, or when further pages remain. Absent when this page is complete and non-empty."
    • addedOutput schema / properties / offset
      Added value: +{
+  "description": "Zero-based index of the first AID returned.",
+  "type": "number"
+}
    • changedOutput schema / properties / shown / description
      Previous value: -"AIDs returned after the maxResults cap."New value: +"AIDs returned on this page."
    • changedOutput schema / properties / totalFound / description
      Previous value: -"Total AIDs found before the maxResults cap."New value: +"Total AIDs found for this target, across all pages."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when AIDs were capped at maxResults — more assays exist than returned."New value: +"True when matching AIDs remain past this page."
    • changedOutput schema / required
      Previous value: -[
-  "aids",
-  "targetType",
-  "targetQuery",
-  "totalFound"
-]New value: +[
+  "aids",
+  "targetType",
+  "targetQuery",
+  "totalFound",
+  "offset"
+]
  6. Changed3 schema fields changedv0.2.4
    • addedOutput schema / properties / cap
      Added value: +{
+  "description": "The maxResults cap that was applied.",
+  "type": "number"
+}
    • addedOutput schema / properties / shown
      Added value: +{
+  "description": "AIDs returned after the maxResults cap.",
+  "type": "number"
+}
    • addedOutput schema / properties / truncated
      Added value: +{
+  "description": "True when AIDs were capped at maxResults — more assays exist than returned.",
+  "type": "boolean"
+}
  7. Changed4 schema fields changedv0.1.22
    • addedOutput schema / properties / notice
      Added value: +{
+  "description": "Recovery guidance when no assays matched — echoes the target and suggests alternative search types. Absent when assays were returned.",
+  "type": "string"
+}
    • changedOutput schema / properties / targetType / description
      Previous value: -"Target identifier type used."New value: +"Target identifier type used: genesymbol, proteinname, geneid, or proteinaccession."
    • changedOutput schema / properties / totalFound / description
      Previous value: -"Total AIDs found."New value: +"Total AIDs found before the maxResults cap."
    • changedOutput schema / required
      Previous value: -[
-  "targetType",
-  "targetQuery",
-  "totalFound",
-  "aids"
-]New value: +[
+  "aids",
+  "targetType",
+  "targetQuery",
+  "totalFound"
+]
  8. First observedv0.1.11

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, open-world, so the bar is lower; the description adds real value by disclosing pagination mechanics ("page past maxResults with offset") and the shape of the return (a page of AIDs). It does not mention the 200-result cap, but that quirk is documented in the schema, so the remaining gap is small.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences: purpose, accepted inputs, return/pagination plus follow-up. Front-loaded with the verb and no redundant restatement of the title.

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 4-parameter, annotated, output-schema-backed search tool, the description covers purpose, input forms, result shape, and the pagination/follow-up path. Nothing an agent needs before calling it is absent.

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 coverage is 100% and the schema already documents targetType semantics, the cross-identifier overlap, and the 200 cap in detail. The description restates the four accepted identifier forms with an EGFR example but adds no syntax or behavior beyond what the schema supplies, 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?

States a specific verb and resource — "Find PubChem bioassays associated with a biological target" — and immediately constrains the identifier space (gene symbol, protein name, Gene ID, UniProt). An agent can tell this apart from pubchem_get_bioactivity and pubchem_search_compounds from the description alone.

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 clear entry conditions (search by one of four target identifier forms) and names the logical next step ("explored further with pubchem_get_summary"). It stops short of explicitly excluding alternatives, e.g. when to prefer this over fetching bioactivity for a known AID, but the intended flow is unambiguous.

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