@inflexa-ai/harness 0.1.1 → 0.3.0

package/dist/tools/bio/pubmed.js

@@ -0,0 +1,100 @@
+/**
+ * pubmed — one tool over PubMed and PubMed Central (NCBI E-utilities):
+ * search the literature, fetch article metadata, and read the full text of an
+ * open-access article.
+ *
+ * Dependency-bearing: the optional NCBI API key is captured by the factory.
+ *
+ * The input is a flat object with an `action` discriminator — not a
+ * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs
+ * a top-level `"type":"object"`). Each action's required argument is optional
+ * in the schema and enforced by `.refine`, so a malformed call (e.g. 'fulltext'
+ * with no pmcId) fails at the loop boundary and surfaces as an `is_error` tool
+ * result instead of reaching NCBI.
+ *
+ * The three actions form one retrieval chain — search yields PMIDs, details
+ * turns PMIDs into abstracts + the PMC id, fulltext turns a PMC id into the
+ * article body — which is why they share a tool: the identifier for each step
+ * is read off the previous step's result.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { getArticleDetails, getArticleFullText, searchPubmed } from "../lib/pubmed-client.js";
+const inputSchema = z
+    .object({
+    action: z
+        .enum(["search", "details", "fulltext"])
+        .describe("'search' (needs query) — returns totalFound plus, per hit, PMID, title, journal, year and an author summary. " +
+        "'details' (needs pmids, max 20 per call) — each article's full abstract, authors, journal, year, DOI, MeSH terms, and " +
+        "pmcId (non-null only when open-access full text exists in PubMed Central). " +
+        "'fulltext' (needs pmcId, taken from a 'details' result) — the body of ONE open-access PMC article as plain text with " +
+        "section headers preserved; available: false when the article is not open-access."),
+    query: z
+        .string()
+        .optional()
+        .describe("Required for action 'search'. PubMed query syntax — MeSH terms (\"breast neoplasms\"[MeSH]), field tags " +
+        '([Title/Abstract], [Author], [Gene]), Boolean AND/OR/NOT. Example: "BRCA1"[Gene] AND "drug resistance"[Title/Abstract].'),
+    maxResults: z.number().int().min(1).max(50).default(10).optional().describe("action 'search': max results, 1–50 (default 10)."),
+    sort: z.enum(["relevance", "date"]).default("relevance").optional().describe("action 'search': sort order (default \"relevance\")."),
+    dateRange: z
+        .object({
+        from: z.string().describe("Start date in YYYY/MM/DD format"),
+        to: z.string().describe("End date in YYYY/MM/DD format"),
+    })
+        .optional()
+        .describe("action 'search': optional publication date range filter."),
+    pmids: z
+        .array(z.string())
+        .min(1)
+        .max(20)
+        .optional()
+        .describe("Required for action 'details'. Non-empty array of PMID strings, max 20 — batch them, do not call once per PMID."),
+    pmcId: z.string().optional().describe("Required for action 'fulltext'. A PMC ID (e.g. \"PMC1234567\") copied from a 'details' result — not a PMID."),
+})
+    .refine((d) => d.action !== "search" || (d.query !== undefined && d.query.trim().length > 0), {
+    message: "query is required when action is 'search'",
+    path: ["query"],
+})
+    .refine((d) => d.action !== "details" || (d.pmids !== undefined && d.pmids.length > 0), {
+    message: "pmids is required when action is 'details' — pass a non-empty array of PMID strings (max 20), copied from a 'search' result",
+    path: ["pmids"],
+})
+    .refine((d) => d.action !== "fulltext" || (d.pmcId !== undefined && d.pmcId.trim().length > 0), {
+    message: "pmcId is required when action is 'fulltext' — copy it from the pmcId field of a 'details' result; a PMID is not a PMC ID",
+    path: ["pmcId"],
+});
+export function createPubMedTool(deps) {
+    return defineTool({
+        id: "pubmed",
+        description: "Search and read the biomedical literature via PubMed / PubMed Central (NCBI E-utilities). The three actions form a chain " +
+            "— search, then details on the relevant hits, then fulltext; see the action parameter for what each needs and returns. Read " +
+            "fulltext sparingly — only where the 'details' abstract is not enough, and only for articles that have a pmcId (open-access). " +
+            "available: false is an expected outcome, not an error — do not retry it.",
+        inputSchema,
+        execute: async (input) => {
+            switch (input.action) {
+                case "search":
+                    return ok(await searchPubmed(deps.ncbiApiKey, input.query, {
+                        maxResults: input.maxResults,
+                        sort: input.sort,
+                        dateRange: input.dateRange,
+                    }));
+                case "details":
+                    return ok(await getArticleDetails(deps.ncbiApiKey, input.pmids));
+                case "fulltext": {
+                    const parsed = await getArticleFullText(deps.ncbiApiKey, input.pmcId);
+                    // "Not open-access" is an expected outcome — a data variant, not an error.
+                    if (!parsed)
+                        return ok({ pmcId: input.pmcId, available: false });
+                    return ok({
+                        pmcId: input.pmcId,
+                        available: true,
+                        fullText: parsed.fullText,
+                        sections: parsed.sections,
+                    });
+                }
+            }
+        },
+    });
+}

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

@@ -8,17 +8,23 @@ import { SUPPORTED_SPECIES, bucketRank, getMultiSpeciesExpression, parseExpressi
 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.",
+    description: "Get BASELINE (healthy, untreated) gene expression across species from Bgee — use it to judge tissue-of-action ('where is this target expressed?') and model-organism " +
+        "suitability ('is the mouse a fair surrogate for this gene?'). " +
+        "NOT for differential expression between conditions — that is the analysis pipeline's job, never this tool. " +
+        "Takes a human gene symbol and resolves the per-species orthologs itself, returning a per-species tissue table: each tissue carries an expression score, a gold/silver confidence, " +
+        "an expressed / not-expressed state, and a bucketed rank (absent | low | medium | high). Species with no ortholog are listed in notFound. " +
+        "Sparse output is valid no-data: dog and macaque coverage is thin, and a null humanEnsemblId means the symbol did not resolve. Do NOT retry on empty output.",
     inputSchema: z.object({
-        geneSymbol: z.string().min(1).describe("Human gene symbol, e.g. 'BRCA1'."),
+        geneSymbol: z
+            .string()
+            .min(1)
+            .describe("HUMAN gene symbol, e.g. 'BRCA1' — one gene per call. Ensembl IDs and non-human symbols are not accepted; the human symbol is resolved to an ENSG and orthologs are looked up per species."),
         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."),
+            .describe("Species to fetch, any subset of: homo_sapiens, mus_musculus, rattus_norvegicus, canis_lupus_familiaris, macaca_mulatta. " +
+            "Defaults to all five — narrow it only when the cross-species comparison is not needed."),
     }),
     execute: async ({ geneSymbol, species }) => ok(await getMultiSpeciesExpression(geneSymbol, species)),
 });

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

@@ -7,12 +7,23 @@ 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.",
+    description: "Search ClinicalTrials.gov to map the clinical development landscape for a target, drug, or indication — what is being tried, at what phase, by whom, and what stopped. " +
+        "Returns totalFound plus per trial: NCT ID, title, status, phase, conditions, interventions, enrollment, start and completion dates, sponsor, brief summary, and whyStopped " +
+        "(the termination reason, when there is one). " +
+        "`query` is free text matched across the whole study record, so a gene symbol, a drug name, a condition, or an NCT ID all work. " +
+        "`phase` and `status` are optional server-side filters — omit them to see the full landscape; totalFound reports the true match count even when it exceeds the page returned. " +
+        "An empty trials array is a valid 'nothing matched' (often an over-narrow filter) — do not retry the identical query.",
     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"),
+        query: z.string().describe("Free-text search term: condition name, drug/intervention name, gene symbol, or an NCT ID."),
+        phase: z
+            .enum(["EARLY_PHASE1", "PHASE1", "PHASE2", "PHASE3", "PHASE4"])
+            .optional()
+            .describe("Optional exact phase filter. Omit for all phases (observational and expanded-access studies carry no phase and are excluded when this is set)."),
+        status: z
+            .enum(["RECRUITING", "ACTIVE_NOT_RECRUITING", "COMPLETED", "NOT_YET_RECRUITING"])
+            .optional()
+            .describe("Optional recruitment-status filter. Omit for all statuses — note TERMINATED/WITHDRAWN trials are not selectable here and appear only in an unfiltered search."),
+        limit: z.number().int().min(1).max(50).default(20).describe("Max trials to return (default 20, max 50)."),
     }),
     execute: async ({ query, phase, status, limit = 20 }) => {
         const result = await searchTrials(query, { phase, status, limit });

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

@@ -8,6 +8,7 @@
  *   - searchType="gene": input HUGO symbols, returns drugs interacting with each.
  *   - searchType="drug": input drug names/concept IDs, returns genes each acts on.
  */
+import type { Logger } from "../../lib/logger.js";
 interface Interaction {
     geneName: string;
     drugName: string;
@@ -26,7 +27,16 @@ interface Interaction {
         value: string;
     }[];
 }
-export declare const searchDgidbTool: import("../define-tool.js").Tool<{
+/**
+ * A factory rather than a bare const (unlike its bio-leaf siblings) because it
+ * logs: DGIdb answers GraphQL partial errors alongside usable data, and an
+ * operator debugging odd interaction results needs to see them. `ToolContext`
+ * carries no deps by design, so a tool that logs is dep-bearing — the same
+ * reason `createSearchClinvarTool` takes its key that way.
+ */
+export declare function createSearchDgidbTool(deps?: {
+    readonly logger?: Logger;
+}): import("../define-tool.js").Tool<{
     query: string | string[];
     searchType: "drug" | "gene";
     minSources: number;

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

@@ -11,6 +11,7 @@
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
+import { createNoopLogger } from "../../lib/console-logger.js";
 import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
 const DGIDB_GRAPHQL_URL = "https://dgidb.org/api/graphql";
 const GENE_INTERACTIONS_QUERY = `query($genes: [String!]!) {
@@ -115,85 +116,98 @@ function applyFilters(interactions, filters) {
     }
     return out;
 }
-export const searchDgidbTool = defineTool({
-    id: "search_dgidb",
-    description: "Query the Drug-Gene Interaction Database (DGIdb) for drug-gene interactions. " +
-        "DGIdb aggregates 30+ sources (ChEMBL, DrugBank, TTD, PharmGKB, GuideToPharmacology, CIViC, etc.) " +
-        "and returns source counts as a confidence signal. " +
-        "searchType='gene' returns drugs interacting with input HUGO gene symbols (most common: 'what drugs hit my gene set?'). " +
-        "searchType='drug' returns the genes each input drug is known to act on. " +
-        "Free, no API key required. Sorted by source count desc.",
-    inputSchema: z.object({
-        query: z
-            .union([z.string(), z.array(z.string()).max(50)])
-            .describe("Single identifier or list of up to 50. For searchType='gene': HUGO symbols. For searchType='drug': drug names or DGIdb concept IDs."),
-        searchType: z.enum(["gene", "drug"]).default("gene"),
-        interactionTypes: z.array(z.string()).optional().describe("Case-insensitive substring filter on interaction type. e.g. ['inhibitor', 'antagonist']"),
-        sources: z.array(z.string()).optional().describe("Restrict to interactions from these source DBs (case-insensitive substring)."),
-        minSources: z.number().int().min(1).default(1).describe("Drop interactions supported by fewer than this many sources."),
-        limit: z.number().int().min(1).max(200).default(50).describe("Max interactions per input gene/drug after filtering."),
-    }),
-    execute: async ({ query, searchType = "gene", interactionTypes, sources, minSources = 1, limit = 50 }) => {
-        const inputs = typeof query === "string" ? [query] : query;
-        if (inputs.length === 0 || inputs.every((s) => !s.trim())) {
-            throw new Error("query must contain at least one identifier");
-        }
-        const isGene = searchType === "gene";
-        const variableName = isGene ? "genes" : "drugs";
-        const queryString = isGene ? GENE_INTERACTIONS_QUERY : DRUG_INTERACTIONS_QUERY;
-        const res = await apiFetchValidated(DGIDB_GRAPHQL_URL, DgidbResponseSchema, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
-                query: queryString,
-                variables: { [variableName]: inputs },
-            }),
-        });
-        if (res.isErr())
-            throw new Error(describeApiError(res.error));
-        const body = res.value;
-        if (!body || !body.data)
-            throw new Error("DGIdb returned no data");
-        if (body.errors?.length) {
-            console.warn("dgidb.partial_errors", { errors: body.errors.slice(0, 3) });
-        }
-        const nodes = (isGene ? body.data.genes?.nodes : body.data.drugs?.nodes) ?? [];
-        const nodeMap = new Map();
-        for (const node of nodes) {
-            nodeMap.set(node.name.toLowerCase(), node);
-            if (!isGene && node.conceptId) {
-                nodeMap.set(node.conceptId.toLowerCase(), node);
-            }
-        }
-        const results = inputs.map((input) => {
-            const node = nodeMap.get(input.toLowerCase());
-            if (!node) {
-                return { input, found: false, interactions: [] };
+/**
+ * A factory rather than a bare const (unlike its bio-leaf siblings) because it
+ * logs: DGIdb answers GraphQL partial errors alongside usable data, and an
+ * operator debugging odd interaction results needs to see them. `ToolContext`
+ * carries no deps by design, so a tool that logs is dep-bearing — the same
+ * reason `createSearchClinvarTool` takes its key that way.
+ */
+export function createSearchDgidbTool(deps = {}) {
+    const logger = (deps.logger ?? createNoopLogger()).named("search_dgidb");
+    return defineTool({
+        id: "search_dgidb",
+        description: "Query the Drug-Gene Interaction Database (DGIdb) for drug-gene interactions. " +
+            "DGIdb aggregates 30+ sources (ChEMBL, DrugBank, TTD, PharmGKB, GuideToPharmacology, CIViC, etc.) " +
+            "and returns source counts as a confidence signal. " +
+            "searchType='gene' returns drugs interacting with input HUGO gene symbols (most common: 'what drugs hit my gene set?'). " +
+            "searchType='drug' returns the genes each input drug is known to act on. " +
+            "Free, no API key required. Sorted by source count desc.",
+        inputSchema: z.object({
+            query: z
+                .union([z.string(), z.array(z.string()).max(50)])
+                .describe("Single identifier or list of up to 50. For searchType='gene': HUGO symbols. For searchType='drug': drug names or DGIdb concept IDs."),
+            searchType: z.enum(["gene", "drug"]).default("gene"),
+            interactionTypes: z
+                .array(z.string())
+                .optional()
+                .describe("Case-insensitive substring filter on interaction type. e.g. ['inhibitor', 'antagonist']"),
+            sources: z.array(z.string()).optional().describe("Restrict to interactions from these source DBs (case-insensitive substring)."),
+            minSources: z.number().int().min(1).default(1).describe("Drop interactions supported by fewer than this many sources."),
+            limit: z.number().int().min(1).max(200).default(50).describe("Max interactions per input gene/drug after filtering."),
+        }),
+        execute: async ({ query, searchType = "gene", interactionTypes, sources, minSources = 1, limit = 50 }) => {
+            const inputs = typeof query === "string" ? [query] : query;
+            if (inputs.length === 0 || inputs.every((s) => !s.trim())) {
+                throw new Error("query must contain at least one identifier");
             }
-            const inputSide = isGene
-                ? { geneName: node.name }
-                : {
-                    drugName: node.name,
-                    drugConceptId: node.conceptId ?? undefined,
-                };
-            const mapped = (node.interactions ?? []).map((raw) => mapInteraction(raw, searchType, inputSide));
-            const filtered = applyFilters(mapped, {
-                interactionTypes,
-                sources,
-                minSources,
+            const isGene = searchType === "gene";
+            const variableName = isGene ? "genes" : "drugs";
+            const queryString = isGene ? GENE_INTERACTIONS_QUERY : DRUG_INTERACTIONS_QUERY;
+            const res = await apiFetchValidated(DGIDB_GRAPHQL_URL, DgidbResponseSchema, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    query: queryString,
+                    variables: { [variableName]: inputs },
+                }),
             });
-            const sorted = filtered.sort((a, b) => {
-                if (b.sourceCount !== a.sourceCount) {
-                    return b.sourceCount - a.sourceCount;
+            if (res.isErr())
+                throw new Error(describeApiError(res.error));
+            const body = res.value;
+            if (!body || !body.data)
+                throw new Error("DGIdb returned no data");
+            if (body.errors?.length) {
+                logger.warn("dgidb partial errors alongside data", { errors: body.errors.slice(0, 3) });
+            }
+            const nodes = (isGene ? body.data.genes?.nodes : body.data.drugs?.nodes) ?? [];
+            const nodeMap = new Map();
+            for (const node of nodes) {
+                nodeMap.set(node.name.toLowerCase(), node);
+                if (!isGene && node.conceptId) {
+                    nodeMap.set(node.conceptId.toLowerCase(), node);
                 }
-                return (b.interactionScore ?? 0) - (a.interactionScore ?? 0);
+            }
+            const results = inputs.map((input) => {
+                const node = nodeMap.get(input.toLowerCase());
+                if (!node) {
+                    return { input, found: false, interactions: [] };
+                }
+                const inputSide = isGene
+                    ? { geneName: node.name }
+                    : {
+                        drugName: node.name,
+                        drugConceptId: node.conceptId ?? undefined,
+                    };
+                const mapped = (node.interactions ?? []).map((raw) => mapInteraction(raw, searchType, inputSide));
+                const filtered = applyFilters(mapped, {
+                    interactionTypes,
+                    sources,
+                    minSources,
+                });
+                const sorted = filtered.sort((a, b) => {
+                    if (b.sourceCount !== a.sourceCount) {
+                        return b.sourceCount - a.sourceCount;
+                    }
+                    return (b.interactionScore ?? 0) - (a.interactionScore ?? 0);
+                });
+                return {
+                    input,
+                    found: true,
+                    interactions: sorted.slice(0, limit),
+                };
             });
-            return {
-                input,
-                found: true,
-                interactions: sorted.slice(0, limit),
-            };
-        });
-        return ok({ results });
-    },
-});
+            return ok({ results });
+        },
+    });
+}

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

@@ -7,11 +7,15 @@ import { defineTool } from "../define-tool.js";
 import { getFaersByDrug } from "../lib/openfda-client.js";
 export const searchFaersTool = defineTool({
     id: "search_faers",
-    description: "Search FDA FAERS (Adverse Event Reporting System) for adverse event reports associated with a drug. Returns the most frequently reported adverse reactions. Use to assess real-world safety signals for drugs or drug candidates targeting a specific gene/pathway.",
+    description: "Search FDA FAERS for post-market adverse-event reports on one marketed drug — the real-world safety signal for a specific molecule. " +
+        "Returns totalReports and adverseEvents[]: { reaction (MedDRA preferred term), count }, most-reported first. " +
+        "These are spontaneous report counts, NOT incidence rates: there is no denominator and reporting is heavily biased, so use them to rank signals, never to state a rate. " +
+        "Matching is on the openFDA GENERIC name only — 'imatinib' works, the brand name 'Gleevec' does not. For mechanism-based liabilities of a target (rather than a drug), use opentargets({action:\"safety\"}). " +
+        "An empty adverseEvents array is valid no-data (drug absent from FAERS under that generic name) — do not retry.",
     inputSchema: z.object({
-        drugName: z.string().describe("Drug generic name (e.g. imatinib, pembrolizumab)"),
-        limit: z.number().int().min(1).max(100).default(25).describe("Max adverse event types to return"),
-        serious: z.boolean().default(false).describe("Filter to serious adverse events only"),
+        drugName: z.string().describe("Generic (INN) drug name, e.g. 'imatinib', 'pembrolizumab'. Brand names do not match."),
+        limit: z.number().int().min(1).max(100).default(25).describe("Max distinct adverse-reaction terms to return (default 25, max 100)."),
+        serious: z.boolean().default(false).describe("When true, count only reports flagged serious (death, hospitalization, life-threatening, disabling)."),
     }),
     execute: async ({ drugName, limit = 25, serious = false }) => {
         const result = await getFaersByDrug(drugName, { limit, serious });

package/dist/tools/bio/search-geo-datasets.js

@@ -38,17 +38,31 @@ const GeoEsummaryResponseSchema = z.object({
 });
 export const searchGeoDatasetsTool = defineTool({
     id: "search_geo_datasets",
-    description: "Search NCBI GEO for public gene expression datasets by disease, tissue, or experimental condition. Returns dataset accessions and metadata for identifying external validation cohorts. Note: sandbox containers cannot download GEO data directly — use this tool to identify relevant datasets, then reference accessions in analysis plans.",
+    description: "Search NCBI GEO for public gene-expression datasets by disease, tissue, or experimental condition — use it to find external validation cohorts or to cite published data. " +
+        "Returns totalFound plus datasets[]: { accession (GSE…/GDS…), title, summary (truncated to 500 chars), platform, sampleCount, organism, pubmedIds }. " +
+        "HARD CAVEAT: sandbox containers cannot download GEO data. This tool identifies and cites accessions only — never plan an analysis step that fetches a GEO dataset. " +
+        "An empty datasets array is a valid 'nothing matched' — do not retry the identical query.",
     inputSchema: z.object({
-        query: z.string().describe("Search terms (e.g. 'breast cancer RNA-seq responder', 'NSCLC pembrolizumab')"),
-        organism: z.string().optional().describe("Filter by organism (e.g. 'Homo sapiens')"),
-        datasetType: z.enum(["gds", "gse"]).default("gse").describe("GDS (curated datasets) or GSE (series, more numerous)"),
-        limit: z.number().int().min(1).max(50).default(15).describe("Max results"),
+        query: z
+            .string()
+            .describe("NCBI Entrez free-text query (e.g. 'breast cancer RNA-seq responder', 'NSCLC pembrolizumab'). Entrez field tags are allowed."),
+        organism: z
+            .string()
+            .optional()
+            .describe("Optional organism filter, appended as an [Organism] term. Use the scientific name, e.g. 'Homo sapiens', 'Mus musculus'."),
+        datasetType: z
+            .enum(["gds", "gse"])
+            .default("gse")
+            .describe("'gse' (default) — GEO Series: raw submitter-deposited studies, far more numerous. 'gds' — curated DataSets: fewer, but normalized and value-added."),
+        limit: z.number().int().min(1).max(50).default(15).describe("Max datasets to return (default 15, max 50)."),
     }),
     execute: async ({ query, organism, datasetType = "gse", limit = 15 }) => {
         let searchQuery = query;
+        // Escape backslashes first, then quotes, so a `\` in the organism value
+        // cannot smuggle an unescaped `"` past the escaping and break out of the
+        // quoted Entrez phrase.
         if (organism)
-            searchQuery += ` AND "${organism.replace(/"/g, '\\"')}"[Organism]`;
+            searchQuery += ` AND "${organism.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"[Organism]`;
         const db = "gds";
         const typeFilter = datasetType === "gse" ? " AND gse[Entry Type]" : " AND gds[Entry Type]";
         searchQuery += typeFilter;

package/dist/tools/bio/search-gwas-catalog.d.ts

@@ -23,7 +23,7 @@ interface GwasAssociation {
 }
 export declare const searchGwasCatalogTool: import("../define-tool.js").Tool<{
     query: string;
-    searchType: "gene" | "trait" | "variant";
+    searchType: "gene" | "variant" | "trait";
     pValueThreshold: number;
     limit: number;
 }, {

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

@@ -20,11 +20,17 @@ const PharmgkbResponseSchema = z.object({
 });
 export const searchPharmgkbTool = defineTool({
     id: "search_pharmgkb",
-    description: "Search PharmGKB for pharmacogenomic clinical annotations — gene-drug interactions, dosing guidelines (CPIC/DPWG), and variant-level clinical significance. Use to determine if a gene variant affects drug metabolism, efficacy, or toxicity.",
+    description: "Search PharmGKB clinical annotations for a gene-drug pharmacogenomic link — use it to judge whether a gene affects a drug's metabolism, efficacy, or toxicity. " +
+        "Returns annotations[]: { gene, drug, levelOfEvidence (PharmGKB 1A…4, where 1A is guideline-backed) }. The phenotype, guidelineSource and summary fields are always null " +
+        "in this tool's output — treat levelOfEvidence as the only strength signal and do not attribute CPIC/DPWG guideline text to it. " +
+        "Matching is an exact field filter, not a search: 'CYP2D6' resolves, 'cytochrome P450 2D6' does not. " +
+        "An empty annotations array is valid no-data (no curated PGx link) — do not retry.",
     inputSchema: z.object({
-        query: z.string().describe("Gene symbol (e.g. CYP2D6) or drug name (e.g. tamoxifen)"),
-        searchType: z.enum(["gene", "drug"]).describe("Search by gene or drug"),
-        limit: z.number().int().min(1).max(50).default(20).describe("Max results"),
+        query: z
+            .string()
+            .describe("Exact gene symbol (e.g. 'CYP2D6') when searchType='gene', or exact drug name (e.g. 'tamoxifen') when searchType='drug'. No fuzzy matching."),
+        searchType: z.enum(["gene", "drug"]).describe("'gene' filters PharmGKB on location.genes.symbol; 'drug' filters on relatedChemicals.name."),
+        limit: z.number().int().min(1).max(50).default(20).describe("Max annotations to return (default 20, max 50); applied client-side after the fetch."),
     }),
     execute: async ({ query, searchType, limit = 20 }) => {
         const filter = searchType === "gene" ? `location.genes.symbol=${encodeURIComponent(query)}` : `relatedChemicals.name=${encodeURIComponent(query)}`;

package/dist/tools/display/index.d.ts

@@ -1,4 +1,5 @@
 /**
  * Display barrel — user-facing presentation cards streamed to chat.
  */
+export * from "./normalize-echart-spec.js";
 export * from "./show-user.js";

package/dist/tools/display/index.js

@@ -1,4 +1,5 @@
 /**
  * Display barrel — user-facing presentation cards streamed to chat.
  */
+export * from "./normalize-echart-spec.js";
 export * from "./show-user.js";

package/dist/tools/display/normalize-echart-spec.d.ts

@@ -0,0 +1,61 @@
+/**
+ * ECharts layout normalization — the renderer-side invariant behind `show_user(kind: "echart")`.
+ *
+ * The layout discipline (no duplicate title, bottom legend, grid margins that fit the axis labels,
+ * every category label shown, a downloadable chart) is applied HERE, deterministically, rather than
+ * being a checklist the model must remember on every chart it composes. A rule a model must remember
+ * is a rule it can forget.
+ *
+ * Two invariants govern every rule below:
+ *
+ * 1. **Defaults, not overrides.** Every property is filled in only when the author left it unset —
+ *    an explicit, sensible authored `grid`/`legend`/`rotate`/filename is respected. The two forced
+ *    fields are `title` (deleted: the `show_user` `title` param is the card heading, so an in-spec
+ *    title is a genuine duplicate render) and `axisLabel.interval` (pinned to `0`: ECharts' default
+ *    `"auto"` SILENTLY DROPS labels, which is the exact bug this rule exists to prevent).
+ * 2. **Never turn a valid chart invalid.** Nothing here is derived from data that may be absent: a
+ *    property is only injected where it is meaningful (a `grid` only for a cartesian chart), and an
+ *    unknown category count yields the safe layout rather than a guessed one.
+ *
+ * Pure: the input spec is never mutated. Modified branches are copy-on-write; untouched branches are
+ * shared by reference. `normalize(normalize(x))` deep-equals `normalize(x)`.
+ */
+export interface NormalizeEchartSpecOptions {
+    /**
+     * The `show_user` `title` param — the card heading rendered above the chart canvas. Seeds the
+     * `saveAsImage` download filename when the author supplied none.
+     */
+    title?: string;
+}
+/**
+ * Kebab-case download filename: `"HMGCR — VST Expression"` → `"hmgcr-vst-expression"`.
+ * Diacritics are folded, every other non-alphanumeric run collapses to a single dash.
+ */
+export declare function kebabFilename(source: string | undefined): string;
+/**
+ * Category count on the x axis, or `null` when the spec cannot tell us.
+ *
+ * `null` is the honest answer for a CSV-backed chart (`show_user`'s `dataPath`): the rows are loaded
+ * by the host at render time and deliberately never pulled through the model's context window, so
+ * they are NOT in the spec. Guessing a rotation for an axis of unknown length is worse than not
+ * rotating — an unrotated axis is also exactly what the other `null` cases (a value axis: scatter,
+ * time series) want. The count is used ONLY to pick a label rotation; it never touches the data, so
+ * an off-by-one at a bucket boundary costs at most a rotation, never a rendering.
+ */
+export declare function categoryCount(spec: Record<string, unknown>): number | null;
+/**
+ * Apply the ECharts layout invariant to an author-composed spec.
+ *
+ * - `title` is deleted (always) — the `show_user` `title` param is the visible card heading, and
+ *   `title.subtext` is the documented misuse for stats that belong in the tooltip.
+ * - `legend` defaults to `{ bottom: 0 }` for a multi-series chart and `{ show: false }` for a
+ *   single-series one (nothing to disambiguate); an authored legend is left alone.
+ * - `grid` (cartesian charts only) gets `top` 8% — 12% when a `graphic` annotation shares the canvas
+ *   — `bottom` 20% / 25% (rotated labels) / 30% (rotated labels above a bottom legend), `left` 10%,
+ *   `right` 5%. Only unset keys are filled.
+ * - `axisLabel.interval` is pinned to `0` on every axis; the x axis is rotated 45° (11–20 categories)
+ *   or 90° (>20) unless the author chose a rotation.
+ * - `toolbox.feature.saveAsImage` is injected with `type: "png"` and a kebab-case filename derived
+ *   from the `show_user` title (falling back to the stripped in-spec title, then `"chart"`).
+ */
+export declare function normalizeEchartSpec(spec: Record<string, unknown>, opts?: NormalizeEchartSpecOptions): Record<string, unknown>;