pubchem-mcp-server

Search Assays

pubchem_search_assays

Read-onlyIdempotent

Search PubChem for bioassays linked to a biological target using gene symbols, protein names, gene IDs, or UniProt accessions. Returns paginated assay IDs 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

TableJSON Schema

Name	Required	Description
`offset`	No	Zero-based index of the first AID to return. Pass the nextOffset from a previous call to read the following page. Default: 0.
`maxResults`	No	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.
`targetType`	Yes	Target identifier type. "genesymbol" and "proteinname" accept text names. "geneid" accepts NCBI Gene IDs. "proteinaccession" accepts UniProt accessions.
`targetQuery`	Yes	Target identifier. Examples: "EGFR" (genesymbol), "Epidermal growth factor receptor" (proteinname), "1956" (geneid), "P00533" (proteinaccession).

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	The maxResults cap that was applied.
`aids`	No	PubChem Assay IDs.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	AIDs returned on this page.
`notice`	No	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.
`offset`	No	Zero-based index of the first AID returned.
`truncated`	No	True when matching AIDs remain past this page.
`nextOffset`	No	Offset to pass on the next call to continue past this page. Omitted when no further AIDs match.
`targetType`	No	Target identifier type used: genesymbol, proteinname, geneid, or proteinaccession.
`totalFound`	No	Total AIDs found for this target, across all pages.
`targetQuery`	No	Target identifier searched.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.6.3Sep 20, 2026

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."

Changed6 schema fields changedv0.6.1Aug 28, 2026

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"
-]

Changed10 schema fields changedv0.6.0Jul 30, 2026

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"
+]

Changed3 schema fields changedv0.2.4Jun 21, 2026

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"
+}

Changed4 schema fields changedv0.1.22May 31, 2026

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"
+]

First observedv0.1.11Apr 4, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering safety and idempotency. The description adds value by disclosing the paginated return ('page of assay IDs'), how to page with offset, and the maxResults limit, which are behavioral details not present in the annotations. No contradictions exist.

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?

Two sentences with no redundancy. The purpose is front-loaded, the identifier types are listed, and the pagination/next-step info is concise. Every sentence earns its place.

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?

The description covers the tool's purpose, the input identifier types, the output (AIDs), pagination behavior, and the natural next step. An output schema exists, so detailed return fields are not needed. No critical gap remains for an agent to call it correctly.

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%, so the schema already documents all four parameters with examples and ranges. The description reinforces the accepted target types but does not add substantive meaning beyond the schema. Baseline 3 is appropriate.

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 states a specific verb ('Find'), a clear resource ('PubChem bioassays'), and the criteria ('associated with a biological target'), distinguishing it from sibling compound search tools. It also lists the accepted identifier types, making the tool's scope unambiguous.

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 gives workflow context by noting returned AIDs 'can be explored further with pubchem_get_summary', implicitly indicating when to use this tool versus that one. However, it does not explicitly contrast it with sibling search tools like pubchem_search_compounds, so it falls just short of full exclusion guidance.

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

Deploy Server