Skip to main content
Glama
cyanheads

pubchem-mcp-server

by cyanheads
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Remote

Search Assays

pubchem_search_assays
Read-onlyIdempotent

Find PubChem bioassays by biological target using gene symbol, protein name, NCBI Gene ID, or UniProt accession. 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
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 (1-200). 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. "geneid" accepts NCBI Gene IDs. "proteinaccession" accepts UniProt accessions.
targetQueryYesTarget identifier. Examples: "EGFR" (genesymbol), "Epidermal growth factor receptor" (proteinname), "1956" (geneid), "P00533" (proteinaccession).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe maxResults cap that was applied.
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.

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 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"
-]
  2. 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"
+]
  3. 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"
+}
  4. 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"
+]
  5. 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 readOnlyHint, openWorldHint, and idempotentHint, and the description does not contradict them. Beyond those annotations, the description discloses that results are returned as a paginated page of AIDs and that offset/maxResults control access to additional pages, which is useful behavioral context. It does not cover error behavior, but that is not required given the annotation coverage.

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?

The description is compact and front-loaded: it states the main purpose first, then supported query types, then return/pagination behavior in a short second sentence. Every clause carries useful information for an agent, and there is no filler or repetition of obvious details.

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 paginated search tool, the description covers the supported query identifier types, the result shape (AIDs), pagination semantics, and the next step via pubchem_get_summary. The input schema fully documents every parameter and includes examples, while the annotations cover safety characteristics, so an agent has everything needed to select and invoke this tool 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 baseline is 3 because the schema already documents offset, maxResults, targetType, and targetQuery thoroughly. The description restates the identifier types and gives examples such as 'EGFR' and 'P00533', but those same examples appear in the schema's parameter descriptions. It adds little semantic information beyond reinforcing what the schema already provides.

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 a specific verb and resource: 'Find PubChem bioassays associated with a biological target.' It also names the accepted identifier types and states it returns a page of assay IDs, which clearly separates it from sibling compound-search and summary tools. The pointer to pubchem_get_summary further establishes that this is the search stage, not the detail stage.

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 clear context for when this tool is appropriate: when searching by a biological target identifier and wanting assay IDs. It also provides helpful guidance on pagination and names pubchem_get_summary as the follow-up tool. However, it does not explicitly contrast with alternatives like pubchem_search_compounds or state when not to use this tool.

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

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/cyanheads/pubchem-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server