pubchem_search_compounds - pubchem-mcp-server

Search Compounds

pubchem_search_compounds

Read-onlyIdempotent

Search PubChem for chemical compounds using names, SMILES, InChIKeys, or molecular formulas. Find structurally related compounds through substructure, superstructure, or Tanimoto similarity searches with optional property retrieval.

Instructions

Search PubChem for chemical compounds. Five search modes:

identifier: Resolve compound names, SMILES, or InChIKeys to CIDs (batch up to 25)
formula: Find compounds by molecular formula (Hill notation, e.g. "C6H12O6")
substructure: Find compounds containing a substructure (SMILES or CID)
superstructure: Find compounds that are substructures of the query
similarity: Find structurally similar compounds by 2D Tanimoto similarity

Optionally hydrate results with properties to avoid a follow-up details call.

Input Schema

TableJSON Schema

Name	Required	Description
`searchType`	Yes	Search strategy: "identifier" (name/SMILES/InChIKey lookup), "formula", "substructure", "superstructure", or "similarity".
`identifierType`	No	Required for identifier search. Type of chemical identifier: "name", "smiles", or "inchikey".
`identifiers`	No	Required for identifier search. Array of identifiers to resolve (1-25). Examples: ["aspirin", "ibuprofen"] for name, ["CC(=O)OC1=CC=CC=C1C(=O)O"] for SMILES.
`formula`	No	Required for formula search. Molecular formula in Hill notation (e.g. "C6H12O6", "CaH2O2").
`allowOtherElements`	No	Formula search only. When true, includes compounds with additional elements beyond the formula.
`query`	No	Required for substructure/superstructure/similarity searches. A SMILES string or PubChem CID (as string) for the query structure.
`queryType`	No	Required for structure/similarity searches. Format of the query: "smiles" or "cid".
`threshold`	No	Similarity search only. Minimum Tanimoto similarity (70-100). 90+ for close analogs, 70-80 for scaffold hops. Default: 90.
`maxResults`	No	Maximum CIDs to return (1-200). Default: 20.
`properties`	No	Optional: fetch these properties for each result, avoiding a follow-up details call. E.g. ["MolecularFormula", "MolecularWeight", "CanonicalSMILES"].

Output Schema

TableJSON Schema

Name	Required	Description
`searchType`	Yes	The search strategy used.
`totalFound`	Yes	Total CIDs found (before maxResults cap).
`results`	Yes	Matching compounds.

Tool Definition Quality

A4.5/5.0

Behavior4/5

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

Adds valuable operational constraints beyond annotations: batch limit (up to 25), Hill notation standard for formulas, 2D Tanimoto similarity method, and hydration behavior. Annotations cover safety/idempotency; description adds domain-specific mechanics. Does not mention rate limits or pagination.

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?

Efficiently structured with front-loaded purpose, scannable bullet points for five complex modes, and a final sentence on optional hydration. Every line conveys essential information; no redundancy with schema or annotations.

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?

Appropriate for complexity (10 parameters, conditional requirements, 5 modes). With full schema coverage and output schema present, description successfully conveys high-level search semantics and cross-tool workflow (hydration vs. details call) without duplicating structured data.

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?

With 100% schema coverage (baseline 3), the description enriches understanding by providing concrete examples (e.g., 'C6H12O6' for Hill notation, 'batch up to 25') and explaining the 'properties' parameter's purpose (avoiding follow-up calls). Adds meaningful context beyond raw schema definitions.

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?

Specific verb ('Search') + resource ('PubChem chemical compounds') + clear scope (five distinct search modes). The detailed enumeration of identifier, formula, substructure, superstructure, and similarity modes effectively distinguishes this from sibling 'get_' retrieval tools and pubchem_search_assays.

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?

Provides clear context for when to use each search mode and hints at optimization via 'hydrate results... to avoid a follow-up details call,' implicitly guiding toward pubchem_get_compound_details. Lacks explicit contrast with pubchem_search_assays or explicit 'when not to use' guidance.

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

Install Server

pubchem-mcp-server

Search Compounds

Instructions

Input Schema

Output Schema

Tool Definition Quality

Other Tools

Latest Blog Posts

MCP directory API