@inflexa-ai/harness 0.1.1

package/dist/tools/bio/lookup-go-term.js

@@ -0,0 +1,116 @@
+/**
+ * lookupGoTerm — look up Gene Ontology terms via the QuickGO API (EBI).
+ *
+ * Supports direct ID lookup, keyword search, and gene annotation retrieval.
+ * Multiple modes can be combined in a single call.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
+const QUICKGO_BASE = "https://www.ebi.ac.uk/QuickGO/services";
+const HEADERS = { Accept: "application/json" };
+// QuickGO term response, validated at the fetch boundary. The `.transform`
+// carries the (context-free) rename from the raw wire fields to the `GoTerm[]`
+// we return, so parsing IS both the validation and the normalization — there
+// is no separate raw interface or mapper to keep in sync.
+const GoTermResponseSchema = z
+    .object({
+    results: z
+        .array(z.object({
+        id: z.string().optional(),
+        name: z.string().optional(),
+        definition: z.object({ text: z.string().optional() }).nullable().optional(),
+        aspect: z.string().optional(),
+    }))
+        .optional(),
+})
+    .transform((res) => (res.results ?? []).map((t) => ({
+    id: t.id ?? "",
+    name: t.name ?? "",
+    definition: t.definition?.text ?? undefined,
+    aspect: t.aspect ?? undefined,
+})));
+const GoAnnotationResponseSchema = z
+    .object({
+    results: z
+        .array(z.object({
+        geneProductId: z.string().optional(),
+        goId: z.string().optional(),
+        goName: z.string().optional(),
+        goAspect: z.string().optional(),
+        goEvidence: z.string().optional(),
+        qualifier: z.string().optional(),
+    }))
+        .optional(),
+})
+    .transform((res) => (res.results ?? []).map((a) => ({
+    geneProductId: a.geneProductId ?? "",
+    goId: a.goId ?? "",
+    goName: a.goName ?? "",
+    aspect: a.goAspect ?? undefined,
+    evidenceCode: a.goEvidence ?? undefined,
+    qualifier: a.qualifier ?? undefined,
+})));
+export const lookupGoTermTool = defineTool({
+    id: "lookup_go_term",
+    description: "Look up Gene Ontology terms from QuickGO (EBI). " +
+        "Can look up a term by GO ID, search by keyword, or retrieve GO annotations " +
+        "for a specific gene/protein. At least one of goId, query, or geneProductId must be provided.",
+    inputSchema: z
+        .object({
+        goId: z
+            .string()
+            .regex(/^GO:\d{7}$/)
+            .optional()
+            .describe("Specific GO term ID (e.g. 'GO:0008150')"),
+        query: z.string().optional().describe("Free-text search for GO terms (e.g. 'apoptotic process')"),
+        limit: z.number().int().min(1).max(100).default(10).describe("Maximum number of results per query type"),
+        geneProductId: z.string().optional().describe("UniProt ID to get annotations for (e.g. 'P04637')"),
+        taxonId: z.number().int().optional().describe("NCBI Taxon ID to filter annotations (9606 = human, 10090 = mouse)"),
+    })
+        .refine((d) => d.goId || d.query || d.geneProductId, {
+        message: "At least one of goId, query, or geneProductId is required",
+    }),
+    execute: async ({ goId, query, limit, geneProductId, taxonId }) => {
+        const tasks = [];
+        let terms;
+        let annotations;
+        if (goId) {
+            tasks.push((async () => {
+                const res = await apiFetchValidated(`${QUICKGO_BASE}/ontology/go/terms/${encodeURIComponent(goId)}`, GoTermResponseSchema, {
+                    headers: HEADERS,
+                });
+                if (res.isErr())
+                    throw new Error(`GO lookup: ${describeApiError(res.error)}`);
+                terms = res.value;
+            })());
+        }
+        if (query) {
+            tasks.push((async () => {
+                const params = new URLSearchParams({ query, limit: String(limit) });
+                const res = await apiFetchValidated(`${QUICKGO_BASE}/ontology/go/search?${params}`, GoTermResponseSchema, { headers: HEADERS });
+                if (res.isErr())
+                    throw new Error(`GO search: ${describeApiError(res.error)}`);
+                const searchTerms = res.value;
+                terms = terms ? [...terms, ...searchTerms] : searchTerms;
+            })());
+        }
+        if (geneProductId) {
+            tasks.push((async () => {
+                const params = new URLSearchParams({
+                    geneProductId,
+                    limit: String(limit),
+                });
+                if (taxonId)
+                    params.set("taxonId", String(taxonId));
+                const res = await apiFetchValidated(`${QUICKGO_BASE}/annotation/search?${params}`, GoAnnotationResponseSchema, { headers: HEADERS });
+                if (res.isErr())
+                    throw new Error(`Annotations: ${describeApiError(res.error)}`);
+                annotations = res.value;
+            })());
+        }
+        await Promise.all(tasks);
+        return ok({ terms, annotations });
+    },
+});

package/dist/tools/bio/search-bgee-expression.d.ts

@@ -0,0 +1,10 @@
+/**
+ * searchBgeeExpression tool — cross-species baseline gene expression.
+ */
+import { SUPPORTED_SPECIES, bucketRank, parseExpressionResponse } from "../lib/bgee-client.js";
+export type { SupportedSpecies } from "../lib/bgee-client.js";
+export { SUPPORTED_SPECIES, bucketRank, parseExpressionResponse };
+export declare const searchBgeeExpressionTool: import("../define-tool.js").Tool<{
+    geneSymbol: string;
+    species: ("homo_sapiens" | "mus_musculus" | "rattus_norvegicus" | "canis_lupus_familiaris" | "macaca_mulatta")[];
+}, import("../lib/bgee-client.js").MultiSpeciesExpression>;

package/dist/tools/bio/search-bgee-expression.js

@@ -0,0 +1,24 @@
+/**
+ * searchBgeeExpression tool — cross-species baseline gene expression.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { SUPPORTED_SPECIES, bucketRank, getMultiSpeciesExpression, parseExpressionResponse } from "../lib/bgee-client.js";
+export { SUPPORTED_SPECIES, bucketRank, parseExpressionResponse };
+export const searchBgeeExpressionTool = defineTool({
+    id: "search_bgee_expression",
+    description: "Get baseline gene expression across species (human, mouse, rat, dog, macaque) from Bgee. " +
+        "Returns per-species tissue × expression-rank tables. Use to assess whether a target is " +
+        "expressed in tissues of interest, and whether model organisms are suitable surrogates. " +
+        "NOT for differential expression — use the analysis pipeline for that.",
+    inputSchema: z.object({
+        geneSymbol: z.string().min(1).describe("Human gene symbol, e.g. 'BRCA1'."),
+        species: z
+            .array(z.enum(SUPPORTED_SPECIES))
+            .min(1)
+            .default([...SUPPORTED_SPECIES])
+            .describe("Species to fetch. Defaults to all five supported: homo_sapiens, mus_musculus, " + "rattus_norvegicus, canis_lupus_familiaris, macaca_mulatta."),
+    }),
+    execute: async ({ geneSymbol, species }) => ok(await getMultiSpeciesExpression(geneSymbol, species)),
+});

package/dist/tools/bio/search-clinical-trials.d.ts

@@ -0,0 +1,12 @@
+/**
+ * searchClinicalTrials — search ClinicalTrials.gov for clinical trials.
+ */
+export declare const searchClinicalTrialsTool: import("../define-tool.js").Tool<{
+    query: string;
+    limit: number;
+    phase?: "EARLY_PHASE1" | "PHASE1" | "PHASE2" | "PHASE3" | "PHASE4" | undefined;
+    status?: "RECRUITING" | "ACTIVE_NOT_RECRUITING" | "COMPLETED" | "NOT_YET_RECRUITING" | undefined;
+}, {
+    totalFound: number;
+    trials: import("../lib/clinical-trials-client.js").ClinicalTrial[];
+}>;

package/dist/tools/bio/search-clinical-trials.js

@@ -0,0 +1,21 @@
+/**
+ * searchClinicalTrials — search ClinicalTrials.gov for clinical trials.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { searchTrials } from "../lib/clinical-trials-client.js";
+export const searchClinicalTrialsTool = defineTool({
+    id: "search_clinical_trials",
+    description: "Search ClinicalTrials.gov for clinical trials by condition, intervention (drug/gene therapy), or target gene. Use to understand the clinical landscape for a therapeutic target or disease indication.",
+    inputSchema: z.object({
+        query: z.string().describe("Search term: condition name, drug name, gene symbol, or NCT ID"),
+        phase: z.enum(["EARLY_PHASE1", "PHASE1", "PHASE2", "PHASE3", "PHASE4"]).optional().describe("Filter by trial phase"),
+        status: z.enum(["RECRUITING", "ACTIVE_NOT_RECRUITING", "COMPLETED", "NOT_YET_RECRUITING"]).optional().describe("Filter by recruitment status"),
+        limit: z.number().int().min(1).max(50).default(20).describe("Max trials to return"),
+    }),
+    execute: async ({ query, phase, status, limit = 20 }) => {
+        const result = await searchTrials(query, { phase, status, limit });
+        return ok({ totalFound: result.totalFound, trials: result.trials });
+    },
+});

package/dist/tools/bio/search-clinvar.d.ts

@@ -0,0 +1,13 @@
+/**
+ * searchClinvar — search NCBI ClinVar for clinical significance of variants.
+ */
+export declare function createSearchClinvarTool(deps: {
+    ncbiApiKey?: string;
+}): import("../define-tool.js").Tool<{
+    query: string;
+    limit: number;
+    clinicalSignificance?: "pathogenic" | "likely-pathogenic" | "benign" | "likely-benign" | "uncertain" | undefined;
+}, {
+    totalFound: number;
+    variants: import("../lib/clinvar-client.js").ClinvarVariant[];
+}>;

package/dist/tools/bio/search-clinvar.js

@@ -0,0 +1,28 @@
+/**
+ * searchClinvar — search NCBI ClinVar for clinical significance of variants.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { searchClinvar } from "../lib/clinvar-client.js";
+export function createSearchClinvarTool(deps) {
+    return defineTool({
+        id: "search_clinvar",
+        description: "Search NCBI ClinVar for clinical significance of genetic variants. Returns pathogenicity classifications, associated conditions, and review status. Use to assess whether variants identified in omics data have known clinical significance.",
+        inputSchema: z.object({
+            query: z.string().describe("Gene symbol (e.g. BRCA1), variant (e.g. NM_007294.4:c.5266dupC), dbSNP rsID (e.g. rs80357906), or condition name"),
+            clinicalSignificance: z
+                .enum(["pathogenic", "likely-pathogenic", "benign", "likely-benign", "uncertain"])
+                .optional()
+                .describe("Filter by clinical significance"),
+            limit: z.number().int().min(1).max(100).default(20).describe("Max results to return"),
+        }),
+        execute: async ({ query, clinicalSignificance, limit = 20 }) => {
+            const { totalFound, variants } = await searchClinvar(deps.ncbiApiKey, query, {
+                clinicalSignificance,
+                limit,
+            });
+            return ok({ totalFound, variants });
+        },
+    });
+}

package/dist/tools/bio/search-compounds.d.ts

@@ -0,0 +1,22 @@
+/**
+ * searchCompounds tool — search ChEMBL for compounds by target, name, or SMILES.
+ *
+ * Supports three search modes:
+ * - "target": resolves target ChEMBL ID, fetches activities, extracts unique molecules
+ * - "compound": free-text search on molecule names
+ * - "smiles": flexmatch on canonical SMILES
+ */
+export declare const searchCompoundsTool: import("../define-tool.js").Tool<{
+    query: string;
+    searchType: "target" | "smiles" | "compound";
+    limit: number;
+}, {
+    compounds: {
+        chemblId: string;
+        preferredCompoundName: string | null;
+        canonicalSmiles: string | null;
+        molecularWeight: number | null;
+        alogp: number | null;
+        molecularFormula: string | null;
+    }[];
+}>;

package/dist/tools/bio/search-compounds.js

@@ -0,0 +1,160 @@
+/**
+ * searchCompounds tool — search ChEMBL for compounds by target, name, or SMILES.
+ *
+ * Supports three search modes:
+ * - "target": resolves target ChEMBL ID, fetches activities, extracts unique molecules
+ * - "compound": free-text search on molecule names
+ * - "smiles": flexmatch on canonical SMILES
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
+import { CHEMBL_BASE, CHEMBL_HEADERS as HEADERS } from "../lib/chembl-config.js";
+// A single schema that both validates and normalizes one ChEMBL molecule
+// record: the `.object(...)` half is the snake_case wire shape (every field
+// optional — ChEMBL omits absent values), the `.transform(...)` half maps it to
+// the camelCase `Compound` we return. Parsing IS the validation, and because
+// the transform rides on the schema, `z.infer` below is the OUTPUT type — no
+// separate raw interface or mapper.
+const MoleculeSchema = z
+    .object({
+    molecule_chembl_id: z.string().optional(),
+    // ChEMBL sends explicit `null` (not omission) for an unnamed compound, and
+    // `null` for the whole structures/properties blocks on biologics/antibodies
+    // — `.nullable()` so those rows parse instead of failing the `molecules` array.
+    pref_name: z.string().nullable().optional(),
+    molecule_structures: z
+        .object({
+        canonical_smiles: z.string().nullable().optional(),
+    })
+        .nullable()
+        .optional(),
+    molecule_properties: z
+        .object({
+        full_mwt: z.string().nullable().optional(),
+        alogp: z.string().nullable().optional(),
+        molecular_formula: z.string().nullable().optional(),
+    })
+        .nullable()
+        .optional(),
+})
+    .transform((raw) => ({
+    chemblId: raw.molecule_chembl_id ?? "",
+    preferredCompoundName: raw.pref_name ?? null,
+    canonicalSmiles: raw.molecule_structures?.canonical_smiles ?? null,
+    molecularWeight: raw.molecule_properties?.full_mwt ? parseFloat(raw.molecule_properties.full_mwt) : null,
+    alogp: raw.molecule_properties?.alogp ? parseFloat(raw.molecule_properties.alogp) : null,
+    molecularFormula: raw.molecule_properties?.molecular_formula ?? null,
+}));
+const TargetSearchResponseSchema = z.object({
+    targets: z.array(z.object({ target_chembl_id: z.string().optional() })).optional(),
+});
+const ActivityResponseSchema = z.object({
+    activities: z.array(z.object({ molecule_chembl_id: z.string().optional() })).optional(),
+});
+const MoleculeResponseSchema = z.object({
+    molecules: z.array(MoleculeSchema).optional(),
+});
+async function searchByTarget(query, limit) {
+    // Step 1: Search targets to resolve ChEMBL ID
+    const targetRes = await apiFetchValidated(`${CHEMBL_BASE}/target/search.json?q=${encodeURIComponent(query)}&limit=1`, TargetSearchResponseSchema, {
+        headers: HEADERS,
+    });
+    if (targetRes.isErr()) {
+        if (targetRes.error.type === "http_status" && targetRes.error.status === 404)
+            return [];
+        throw new Error(describeApiError(targetRes.error));
+    }
+    if (!targetRes.value.targets?.length)
+        return [];
+    const targetChemblId = targetRes.value.targets[0].target_chembl_id;
+    if (!targetChemblId)
+        return [];
+    // Step 2: Fetch activities for that target
+    const activityRes = await apiFetchValidated(`${CHEMBL_BASE}/activity.json?target_chembl_id=${targetChemblId}&limit=${limit}`, ActivityResponseSchema, {
+        headers: HEADERS,
+    });
+    if (activityRes.isErr()) {
+        if (activityRes.error.type === "http_status" && activityRes.error.status === 404)
+            return [];
+        throw new Error(describeApiError(activityRes.error));
+    }
+    if (!activityRes.value.activities?.length)
+        return [];
+    // Step 3: Extract unique molecule IDs
+    const uniqueIds = new Set();
+    for (const act of activityRes.value.activities) {
+        if (act.molecule_chembl_id)
+            uniqueIds.add(act.molecule_chembl_id);
+    }
+    // Step 4: Fetch molecule details for unique compounds
+    const compounds = [];
+    const idArray = [...uniqueIds];
+    // Fetch in batches of 50 to avoid overly long URLs
+    const batchSize = 50;
+    for (let i = 0; i < idArray.length; i += batchSize) {
+        const batch = idArray.slice(i, i + batchSize);
+        const idsParam = batch.join(";");
+        const molRes = await apiFetchValidated(`${CHEMBL_BASE}/molecule/set/${idsParam}.json`, MoleculeResponseSchema, { headers: HEADERS });
+        if (molRes.isErr()) {
+            if (!(molRes.error.type === "http_status" && molRes.error.status === 404)) {
+                throw new Error(describeApiError(molRes.error));
+            }
+            continue;
+        }
+        if (molRes.value.molecules) {
+            for (const mol of molRes.value.molecules) {
+                compounds.push(mol);
+            }
+        }
+    }
+    return compounds;
+}
+async function searchByCompound(query, limit) {
+    const res = await apiFetchValidated(`${CHEMBL_BASE}/molecule/search.json?q=${encodeURIComponent(query)}&limit=${limit}`, MoleculeResponseSchema, {
+        headers: HEADERS,
+    });
+    if (res.isErr()) {
+        if (res.error.type === "http_status" && res.error.status === 404)
+            return [];
+        throw new Error(describeApiError(res.error));
+    }
+    return res.value.molecules ?? [];
+}
+async function searchBySmiles(smiles, limit) {
+    const res = await apiFetchValidated(`${CHEMBL_BASE}/molecule.json?molecule_structures__canonical_smiles__flexmatch=${encodeURIComponent(smiles)}&limit=${limit}`, MoleculeResponseSchema, { headers: HEADERS });
+    if (res.isErr()) {
+        if (res.error.type === "http_status" && res.error.status === 404)
+            return [];
+        throw new Error(describeApiError(res.error));
+    }
+    return res.value.molecules ?? [];
+}
+export const searchCompoundsTool = defineTool({
+    id: "search_compounds",
+    description: "Search ChEMBL for compounds by target name/ChEMBL ID, compound name, or SMILES. " +
+        "Returns compound metadata including ChEMBL IDs, SMILES, molecular weight, and LogP. " +
+        "Use searchType='target' to find compounds active against a target, " +
+        "'compound' for name search, 'smiles' for structure matching.",
+    inputSchema: z.object({
+        query: z.string().min(1).describe("Search term: target name/ID, compound name, or SMILES string"),
+        searchType: z
+            .enum(["target", "compound", "smiles"])
+            .describe("What to search by: 'target' (find active compounds), 'compound' (name search), 'smiles' (structure match)"),
+        limit: z.number().int().min(1).max(500).default(500).describe("Maximum number of results to return"),
+    }),
+    execute: async ({ query, searchType, limit = 500 }) => {
+        let compounds;
+        if (searchType === "target") {
+            compounds = await searchByTarget(query, limit);
+        }
+        else if (searchType === "smiles") {
+            compounds = await searchBySmiles(query, limit);
+        }
+        else {
+            compounds = await searchByCompound(query, limit);
+        }
+        return ok({ compounds });
+    },
+});

package/dist/tools/bio/search-ctx-chemical.d.ts

@@ -0,0 +1,50 @@
+/**
+ * searchCtxChemical — look up chemical details and physicochemical
+ * properties from EPA's CompTox Chemicals Dashboard (CTX API).
+ */
+interface ChemicalDetail {
+    dtxsid: string;
+    dtxcid: string;
+    casrn: string | null;
+    preferredName: string;
+    iupacName: string;
+    molFormula: string;
+    smiles: string;
+    inchikey: string;
+    monoisotopicMass: number | null;
+    averageMass: number | null;
+    qcLevel: number | null;
+    totalAssays: number | null;
+    activeAssays: number | null;
+    percentAssays: number | null;
+    pubchemCid: number | null;
+    pubmedCount: number | null;
+    sourcesCount: number | null;
+}
+interface PropertySummary {
+    propName: string;
+    unit: string;
+    experimentalCount: number | null;
+    experimentalMedian: number | null;
+    experimentalMin: number | null;
+    experimentalMax: number | null;
+    predictedCount: number | null;
+    predictedMedian: number | null;
+    predictedMin: number | null;
+    predictedMax: number | null;
+}
+type CtxChemicalOutput = {
+    found: false;
+    query: string;
+} | {
+    found: true;
+    detail: ChemicalDetail;
+    properties?: PropertySummary[];
+};
+export declare function createSearchCtxChemicalTool(deps: {
+    apiKey: string;
+}): import("../define-tool.js").Tool<{
+    query: string;
+    includeProperties: boolean;
+}, CtxChemicalOutput>;
+export {};

package/dist/tools/bio/search-ctx-chemical.js

@@ -0,0 +1,130 @@
+/**
+ * searchCtxChemical — look up chemical details and physicochemical
+ * properties from EPA's CompTox Chemicals Dashboard (CTX API).
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
+import { EPA_CCTE_BASE, getEpaCcteHeaders } from "../lib/toxcast-config.js";
+// The chemical-search endpoint returns rows the code reads `[0].dtxsid` from
+// after a length guard, so `dtxsid` stays required — a row missing it is a
+// contract break surfaced as `invalid_response`, not a silent `undefined`.
+const CtxChemicalSearchRowSchema = z.object({
+    dtxsid: z.string(),
+});
+// Raw CTX chemical-detail wire shape, validated at the fetch boundary. Every
+// field is optional (the API omits absent values); the mapper below normalizes
+// it into `ChemicalDetail`, folding in the resolved `dtxsid` fallback.
+const RawChemicalDetailSchema = z.object({
+    dtxsid: z.string().optional(),
+    dtxcid: z.string().nullable().optional(),
+    casrn: z.string().nullable().optional(),
+    preferredName: z.string().nullable().optional(),
+    iupacName: z.string().nullable().optional(),
+    molFormula: z.string().nullable().optional(),
+    smiles: z.string().nullable().optional(),
+    inchikey: z.string().nullable().optional(),
+    monoisotopicMass: z.number().nullable().optional(),
+    averageMass: z.number().nullable().optional(),
+    qcLevel: z.number().nullable().optional(),
+    totalAssays: z.number().nullable().optional(),
+    activeAssays: z.number().nullable().optional(),
+    percentAssays: z.number().nullable().optional(),
+    pubchemCid: z.number().nullable().optional(),
+    pubmedCount: z.number().nullable().optional(),
+    sourcesCount: z.number().nullable().optional(),
+});
+const RawPropertySummarySchema = z.object({
+    propName: z.string().nullable().optional(),
+    unit: z.string().nullable().optional(),
+    experimentalCount: z.number().nullable().optional(),
+    experimentalMedian: z.number().nullable().optional(),
+    experimentalMin: z.number().nullable().optional(),
+    experimentalMax: z.number().nullable().optional(),
+    predictedCount: z.number().nullable().optional(),
+    predictedMedian: z.number().nullable().optional(),
+    predictedMin: z.number().nullable().optional(),
+    predictedMax: z.number().nullable().optional(),
+});
+export function createSearchCtxChemicalTool(deps) {
+    return defineTool({
+        id: "search_ctx_chemical",
+        description: "Look up chemical details and physicochemical properties from EPA's CompTox Chemicals Dashboard (CTX API). " +
+            "Returns chemical identifiers (DTXSID, CASRN, SMILES, InChIKey), molecular formula, mass, " +
+            "and a summary of predicted and experimental properties (logP, water solubility, vapor pressure, " +
+            "melting/boiling point, bioconcentration factor, Henry's law constant). " +
+            "Use for ADMET property assessment, compound characterization, and safety-relevant physicochemical profiling. " +
+            "Requires EPA_CCTE_API_KEY environment variable.",
+        inputSchema: z.object({
+            query: z
+                .string()
+                .describe("Chemical identifier: DTXSID (e.g. DTXSID7020182), CASRN (e.g. 80-05-7), " + "chemical name (e.g. bisphenol A), or InChIKey"),
+            includeProperties: z.boolean().default(true).describe("Include predicted/experimental property summaries (logP, solubility, etc.)"),
+        }),
+        execute: async ({ query, includeProperties = true }) => {
+            const headers = getEpaCcteHeaders(deps.apiKey);
+            const resolved = await resolveDtxsid(query, headers);
+            // "No chemical found" is an expected outcome — a data variant, not an error.
+            if (!resolved)
+                return ok({ found: false, query });
+            const { dtxsid } = resolved;
+            const detailUrl = `${EPA_CCTE_BASE}/chemical/detail/search/by-dtxsid/${dtxsid}?projection=chemicaldetailstandard`;
+            const detailRes = await apiFetchValidated(detailUrl, RawChemicalDetailSchema, { headers });
+            if (detailRes.isErr())
+                throw new Error(describeApiError(detailRes.error));
+            const d = detailRes.value ?? {};
+            const detail = {
+                dtxsid: d.dtxsid ?? dtxsid,
+                dtxcid: d.dtxcid ?? "",
+                casrn: d.casrn ?? null,
+                preferredName: d.preferredName ?? "",
+                iupacName: d.iupacName ?? "",
+                molFormula: d.molFormula ?? "",
+                smiles: d.smiles ?? "",
+                inchikey: d.inchikey ?? "",
+                monoisotopicMass: d.monoisotopicMass ?? null,
+                averageMass: d.averageMass ?? null,
+                qcLevel: d.qcLevel ?? null,
+                totalAssays: d.totalAssays ?? null,
+                activeAssays: d.activeAssays ?? null,
+                percentAssays: d.percentAssays ?? null,
+                pubchemCid: d.pubchemCid ?? null,
+                pubmedCount: d.pubmedCount ?? null,
+                sourcesCount: d.sourcesCount ?? null,
+            };
+            const result = { found: true, detail };
+            if (includeProperties) {
+                const propUrl = `${EPA_CCTE_BASE}/chemical/property/summary/search/by-dtxsid/${dtxsid}`;
+                const propRes = await apiFetchValidated(propUrl, z.array(RawPropertySummarySchema), { headers });
+                if (propRes.isOk() && Array.isArray(propRes.value)) {
+                    result.properties = propRes.value.map((p) => ({
+                        propName: p.propName ?? "",
+                        unit: p.unit ?? "",
+                        experimentalCount: p.experimentalCount ?? null,
+                        experimentalMedian: p.experimentalMedian ?? null,
+                        experimentalMin: p.experimentalMin ?? null,
+                        experimentalMax: p.experimentalMax ?? null,
+                        predictedCount: p.predictedCount ?? null,
+                        predictedMedian: p.predictedMedian ?? null,
+                        predictedMin: p.predictedMin ?? null,
+                        predictedMax: p.predictedMax ?? null,
+                    }));
+                }
+            }
+            return ok(result);
+        },
+    });
+}
+async function resolveDtxsid(query, headers) {
+    if (query.startsWith("DTXSID")) {
+        return { dtxsid: query };
+    }
+    const url = `${EPA_CCTE_BASE}/chemical/search/equal/${encodeURIComponent(query)}`;
+    const res = await apiFetchValidated(url, z.array(CtxChemicalSearchRowSchema), { headers });
+    if (res.isErr())
+        throw new Error(describeApiError(res.error));
+    if (!res.value?.length)
+        return null;
+    return { dtxsid: res.value[0].dtxsid };
+}

package/dist/tools/bio/search-ctx-exposure.d.ts

@@ -0,0 +1,55 @@
+/**
+ * searchCtxExposure — look up chemical exposure data from EPA's CTX
+ * Exposure APIs.
+ */
+interface SeemPrediction {
+    dtxsid: string;
+    productionVolume: number | null;
+    units: string;
+    probabilityDietary: number | null;
+    probabilityResidential: number | null;
+    probabilityPesticide: number | null;
+    probabilityIndustrial: number | null;
+}
+interface HttkParameter {
+    parameter: string;
+    measured: number | null;
+    predicted: number | null;
+    units: string;
+    model: string;
+    species: string;
+    reference: string;
+}
+interface FunctionalUse {
+    functionCategory: string;
+    reportedFunction: string;
+    docTitle: string;
+}
+interface ProductData {
+    productName: string;
+    generalCategory: string;
+    productFamily: string;
+    productType: string;
+    centralWeightFraction: number | null;
+    weightFractionType: string;
+}
+interface ExposureOutput {
+    found: true;
+    dtxsid: string;
+    seem?: SeemPrediction;
+    httk?: HttkParameter[];
+    functionalUse?: FunctionalUse[];
+    productData?: ProductData[];
+}
+type ExposureResult = {
+    found: false;
+    query: string;
+} | ExposureOutput;
+export declare function createSearchCtxExposureTool(deps: {
+    apiKey: string;
+}): import("../define-tool.js").Tool<{
+    query: string;
+    dataType: "all" | "seem" | "httk" | "functional-use" | "product-data";
+    limit: number;
+}, ExposureResult>;
+export {};