@inflexa-ai/harness 0.29.0 → 0.30.1

package/dist/tools/bio/opentargets.js

@@ -17,23 +17,38 @@
  * gene ID or an EFO disease ID, and a gene symbol silently returns an empty
  * result rather than an error. Naming the two identifiers apart is what makes
  * that contract visible at the call site.
+ *
+ * `resolve_disease` closes that contract. It takes the plain disease name a
+ * user supplies and returns the disease ids of the same corpus, thus the
+ * caller never has to know an ontology id before it can ask a question.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
-import { searchDiseaseAssociations, searchTargetAssociations } from "../lib/opentargets-client.js";
+import { searchDiseaseAssociations, searchDiseases, searchTargetAssociations, } from "../lib/opentargets-client.js";
 const DEFAULT_LIMIT = 10;
 const inputSchema = z
     .object({
     action: z
-        .enum(["target", "disease"])
+        .enum(["target", "disease", "resolve_disease"])
         .describe("'target' (needs ensemblId) — the diseases associated with the gene: targetInfo (approvedSymbol, approvedName, " +
         "tractability across small molecule / antibody / other modalities) plus associations[], each with an overall score and " +
         "its per-datatype breakdown — genetic association, known drug, literature, animal model, somatic mutation. " +
         "'disease' (needs efoId) — the targets ranked for that disease; each association carries targetId/targetSymbol/targetName " +
-        "and the same score breakdown."),
+        "and the same score breakdown. " +
+        "'resolve_disease' (needs diseaseName) — the disease-name resolver: a plain name ('type 2 diabetes', 'asthma') comes back as " +
+        "candidates[] { id, name, description }, best match first. Take the id of the row whose name you meant and pass it as efoId."),
     ensemblId: z.string().optional().describe("Ensembl gene ID, e.g. ENSG00000141510 (TP53). Required for action 'target'."),
-    efoId: z.string().optional().describe("EFO disease ID, e.g. EFO_0000311. Required for action 'disease'."),
+    efoId: z
+        .string()
+        .optional()
+        .describe("Open Targets disease ID, e.g. EFO_0000311, MONDO_0005148 or HP_0001250. Required for action 'disease'. Get one from " +
+        "action 'resolve_disease', or from the diseaseId of an action 'target' association."),
+    diseaseName: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Required for action 'resolve_disease'. A plain disease or trait name, e.g. 'type 2 diabetes'. No ontology id, no synonym list."),
     limit: z
         .number()
         .int()
@@ -41,7 +56,8 @@ const inputSchema = z
         .max(100)
         .optional()
         .describe(`Max associations to return (default ${DEFAULT_LIMIT}, max 100), ordered by DESCENDING association score. The default is the top ` +
-        `${DEFAULT_LIMIT}, which is where the evidence is; raise it only when you are surveying the long tail rather than ranking.`),
+        `${DEFAULT_LIMIT}, which is where the evidence is; raise it only when you are surveying the long tail rather than ranking. ` +
+        "For action 'resolve_disease' it caps the candidate rows instead."),
 })
     .refine((d) => d.action !== "target" || (d.ensemblId !== undefined && d.ensemblId.trim().length > 0), {
     message: "ensemblId is required when action is 'target' — Open Targets accepts only Ensembl gene IDs (ENSG…), " +
@@ -49,18 +65,27 @@ const inputSchema = z
     path: ["ensemblId"],
 })
     .refine((d) => d.action !== "disease" || (d.efoId !== undefined && d.efoId.trim().length > 0), {
-    message: "efoId is required when action is 'disease' — Open Targets accepts only EFO disease IDs (e.g. EFO_0000311), never free-text disease names.",
+    message: "efoId is required when action is 'disease' — Open Targets accepts only a disease ID (e.g. EFO_0000311), never a free-text disease name. " +
+        "Call action='resolve_disease' with the name to get the ID, then retry.",
     path: ["efoId"],
+})
+    .refine((d) => d.action !== "resolve_disease" || (d.diseaseName !== undefined && d.diseaseName.trim().length > 0), {
+    message: "diseaseName is required when action is 'resolve_disease' — the plain disease or trait name to resolve.",
+    path: ["diseaseName"],
 });
 export const openTargetsTool = defineTool({
     id: "opentargets",
-    description: "Query the Open Targets Platform — the preferred FIRST call for target assessment, since one 'target' query yields the genetic evidence, " +
-        "tractability, and drug landscape together, already scored and ranked. See the action parameter for what each mode needs and returns.\n" +
-        "It is the integrated view; the underlying records live elsewhere. For the raw genetic evidence (individual SNPs, effect sizes, GDA scores, " +
-        "variant pathogenicity) use gene_disease_evidence. For this target's mechanism-based safety liabilities use target_safety.\n" +
-        "IDENTIFIERS ONLY: it accepts an Ensembl gene ID (action 'target') or an EFO disease ID (action 'disease'). A bare gene symbol or a free-text " +
-        "disease name silently returns an EMPTY result rather than an error — resolve a symbol to its ENSG id with search_gene first.\n" +
-        "NO-DATA IS FINAL — do not retry the same id. Empty associations mean no evidence, or an unresolvable id.",
+    description: "Query the Open Targets Platform — the integrated target-disease evidence corpus of EMBL-EBI, GSK and their partners — the preferred FIRST call " +
+        "for target assessment, since one 'target' query yields the genetic evidence, tractability, and drug landscape together, already scored and " +
+        "ranked. See the action parameter for what each mode needs and returns.\n" +
+        "It is the integrated view; the underlying records live elsewhere. For the raw genetic evidence (individual SNPs from the GWAS Catalog, DisGeNET " +
+        "GDA scores, ClinVar variant pathogenicity) use gene_disease_evidence. For this target's mechanism-based safety liabilities use target_safety.\n" +
+        "ACCEPTED IDENTIFIERS: an Ensembl gene ID for action 'target' (ENSG00000141510); an Open Targets disease ID for action 'disease' — EFO " +
+        "(EFO_0000311), MONDO (MONDO_0005148) or HP (HP_0001250), because Open Targets keys a disease on EFO and EFO imports the other two; and a plain " +
+        "disease NAME for action 'resolve_disease' ('type 2 diabetes'), which is how you obtain that disease ID. A bare gene symbol is NOT accepted by " +
+        "action 'target' and silently returns an empty result — resolve it to its ENSG id with search_gene first.\n" +
+        "NO-DATA IS FINAL — do not retry the same id. Empty associations mean no evidence, or an id the platform does not hold. An empty candidates " +
+        "list means the name matched no disease: rephrase it, do not invent an id.",
     inputSchema,
     describeCall: "none",
     execute: async (input) => {
@@ -74,6 +99,10 @@ export const openTargetsTool = defineTool({
                 const associations = await searchDiseaseAssociations(input.efoId, limit);
                 return ok({ associations });
             }
+            case "resolve_disease": {
+                const { total, candidates } = await searchDiseases(input.diseaseName, limit);
+                return ok({ totalFound: total, candidates });
+            }
         }
     },
 });

package/dist/tools/bio/pubchem.js

@@ -69,8 +69,11 @@ const inputSchema = z
 });
 export const pubchemTool = defineTool({
     id: "pubchem",
-    description: "Query PubChem (110M+ compounds) — pick the lookup with `action`: 'compound' (resolve an identifier), 'crossrefs' (external registry ids for a CID), 'assays' (bioassay screening " +
-        "summaries for a CID). See `action` for what each returns. " +
+    description: "Query PubChem — the open chemical database of the NCBI, with over 110M compounds and their BioAssay screening records. Pick the lookup with " +
+        "`action`: 'compound' (resolve an identifier), 'crossrefs' (external registry ids for a CID), 'assays' (bioassay screening summaries for a CID). " +
+        "See `action` for what each returns. " +
+        "ACCEPTED IDENTIFIERS: for 'compound', the form named by `searchBy` — a chemical name ('aspirin'), a SMILES string, an InChI, an InChIKey " +
+        "('BSYNRYMUTXBXSQ-UHFFFAOYSA-N') or a numeric CID ('2244'). 'crossrefs' and 'assays' take the numeric CID only. " +
         "Reach for PubChem when ChEMBL misses the compound — it covers metabolites, vendor chemicals, food additives and environmental compounds that ChEMBL does not. " +
         "PubChem carries no curated mechanism or potency data, so resolve broadly HERE and then bridge OUT: action 'compound' to get the cid, action 'crossrefs' to take its ChEMBL ID, " +
         "then chembl action='mechanism' / 'bioactivity' there for curated activity data. " +

package/dist/tools/bio/pubmed.js

@@ -118,12 +118,18 @@ const inputSchema = z
 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 " +
+        description: "Search and read the biomedical literature in PubMed and PubMed Central — the MEDLINE citation index and the open-access full-text archive of " +
+            "the U.S. National Library of Medicine, through the 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.\n" +
+            "ACCEPTED IDENTIFIERS: an Entrez free-text query with optional field tags for 'search' ('PCSK9[Title] AND 2020:2024[dp]'); PMIDs for " +
+            "'details' ('34567890'); and a PMID or a PMC ID for 'fulltext' ('PMC7096066'). For literature outside MEDLINE — a method, a model, a " +
+            "preprint — use search_semantic_scholar or search_arxiv instead.\n" +
+            "Read " +
             "fulltext sparingly — only where the 'details' abstract is not enough, and only for articles that have a pmcId (open-access). " +
             "A full article is larger than everything else this tool returns combined, so it comes back trimmed to a character budget: take the " +
             "`outline` from the first call and re-request the specific `sections` you need rather than raising maxChars. " +
-            "available: false is an expected outcome, not an error — do not retry it.",
+            "An empty result set and available: false are expected outcomes, not errors — an article with no PMC record simply has no open full text. " +
+            "Report it and continue, do not retry it.",
         inputSchema,
         // One tool, three jobs. The action alone would still render three
         // different searches identically, so each action names its own subject:

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

@@ -1,31 +1,31 @@
 /**
- * searchClinicalTrials — search ClinicalTrials.gov for clinical trials.
+ * searchClinicalTrials — search ClinicalTrials.gov for clinical trials, and
+ * read one study back by the NCT id that a search returns.
+ *
+ * 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"`). `action` defaults to 'search', thus the
+ * common call stays a query and nothing more.
  */
+import { type ClinicalTrial, type TrialDetails } from "../lib/clinical-trials-client.js";
+/** A listed trial keeps the full record, or the preview shape that trims it. */
+type TrialListRow = ClinicalTrial | (Omit<ClinicalTrial, "detailedDescription"> & {
+    summaryTruncated: boolean;
+});
+/** One result shape per action — the key names the records it carries. */
+type ClinicalTrialsOutput = {
+    trial: TrialDetails | null;
+} | {
+    totalFound: number;
+    trials: TrialListRow[];
+};
 export declare const searchClinicalTrialsTool: import("../define-tool.js").Tool<{
-    query: string;
+    action: "search" | "details";
     limit: number;
     includeSummaries: boolean;
+    query?: string | undefined;
+    nctId?: string | undefined;
     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[] | {
-        briefSummary: string | null;
-        summaryTruncated: boolean;
-        nctId: string;
-        title: string;
-        officialTitle: string | null;
-        status: string;
-        phase: string | null;
-        studyType: string | null;
-        primaryPurpose: string | null;
-        conditions: string[];
-        interventions: string[];
-        interventionDetails: import("../lib/clinical-trials-client.js").ClinicalTrialIntervention[];
-        enrollmentCount: number | null;
-        startDate: string | null;
-        primaryCompletionDate: string | null;
-        whyStopped: string | null;
-        sponsor: string | null;
-    }[];
-}>;
+    status?: "RECRUITING" | "ACTIVE_NOT_RECRUITING" | "COMPLETED" | "NOT_YET_RECRUITING" | "TERMINATED" | "WITHDRAWN" | "SUSPENDED" | undefined;
+}, ClinicalTrialsOutput>;
+export {};

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

@@ -1,46 +1,84 @@
 /**
- * searchClinicalTrials — search ClinicalTrials.gov for clinical trials.
+ * searchClinicalTrials — search ClinicalTrials.gov for clinical trials, and
+ * read one study back by the NCT id that a search returns.
+ *
+ * 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"`). `action` defaults to 'search', thus the
+ * common call stays a query and nothing more.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
-import { searchTrials } from "../lib/clinical-trials-client.js";
+import { getTrialDetails, searchTrials } from "../lib/clinical-trials-client.js";
 /** briefSummary preview length when `includeSummaries` is off. */
 const SUMMARY_PREVIEW_CHARS = 300;
 export const searchClinicalTrialsTool = defineTool({
     id: "search_clinical_trials",
-    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, whyStopped " +
-        "(the termination reason, when there is one) and a briefSummary preview — set includeSummaries for the full protocol prose. " +
-        "`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("Free-text search term: condition name, drug/intervention name, gene symbol, or an NCT ID."),
+    description: "Search ClinicalTrials.gov — the trial registry of the U.S. National Library of Medicine, which holds interventional and observational studies " +
+        "worldwide — to map the clinical development landscape for a target, drug, or indication: what is being tried, at what phase, by whom, and what " +
+        "stopped.\n" +
+        "action 'search' (the default) returns totalFound plus per trial: NCT ID, title, status, phase, conditions, interventions, enrollment, start and " +
+        "completion dates, sponsor, whyStopped (the termination reason, when there is one) and a briefSummary preview — set includeSummaries for the full " +
+        "protocol prose.\n" +
+        "action 'details' takes ONE nctId and returns that study in full: the same trial record plus outcomes[] (each primary/secondary/other outcome " +
+        "measure with its numeric effect where the sponsor posted results) and the reported adverse events with their per-arm counts. This is how you " +
+        "read a result, as opposed to finding a trial.\n" +
+        "ACCEPTED IDENTIFIERS: `query` is free text matched across the whole study record, so a gene symbol ('KRAS'), a drug or brand name ('imatinib', " +
+        "'Gleevec'), a condition ('melanoma') or an NCT ID ('NCT00000102') all work. `nctId` takes one NCT ID and nothing else.\n" +
+        "`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.\n" +
+        "ABSENCE IS NORMAL. An empty trials array is a valid 'nothing matched' (often an over-narrow filter) and a null trial from 'details' means the " +
+        "registry holds no such NCT ID — report it and move on, do not retry the identical call. A trial with no posted results carries empty outcomes " +
+        "and adverse events, which means unreported, never zero.",
+    inputSchema: z
+        .object({
+        action: z
+            .enum(["search", "details"])
+            .default("search")
+            .describe("'search' (default) — find trials with `query`. 'details' — read one trial, with its outcomes and adverse events, by `nctId`."),
+        query: z.string().optional().describe("Required for 'search'. Free-text search term: condition name, drug/brand name, gene symbol, or an NCT ID."),
+        nctId: z
+            .string()
+            .optional()
+            .describe("Required for 'details'. One ClinicalTrials.gov registry ID, e.g. 'NCT00000102' — exactly as the nctId field of a search result."),
         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)."),
+            .describe("'search' only. 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"])
+            .enum(["RECRUITING", "ACTIVE_NOT_RECRUITING", "COMPLETED", "NOT_YET_RECRUITING", "TERMINATED", "WITHDRAWN", "SUSPENDED"])
             .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."),
+            .describe("'search' only. Optional recruitment-status filter. Omit for all statuses. TERMINATED (stopped early), WITHDRAWN (stopped before " +
+            "enrollment) and SUSPENDED are the attrition record — filter on one of them to ask what failed, and read whyStopped for the reason."),
         limit: z
             .number()
             .int()
             .min(1)
             .max(50)
             .default(10)
-            .describe("Max trials to return (default 10, max 50). totalFound reports the true match count regardless."),
+            .describe("'search' only. Max trials to return (default 10, max 50). totalFound reports the true match count regardless."),
         includeSummaries: z
             .boolean()
             .default(false)
-            .describe("Default FALSE — briefSummary comes back as a 300-character preview and detailedDescription is omitted, which is enough to map a " +
-            "landscape. Set true for the full protocol prose, and narrow `limit` when you do: a full summary runs to several thousand characters " +
-            "per trial."),
+            .describe("'search' only. Default FALSE — briefSummary comes back as a 300-character preview and detailedDescription is omitted, which is enough " +
+            "to map a landscape. Set true for the full protocol prose, and narrow `limit` when you do: a full summary runs to several thousand " +
+            "characters per trial."),
+    })
+        .refine((d) => d.action === "details" || (d.query !== undefined && d.query.trim().length > 0), {
+        message: "query is required when action is 'search' — the free text to match across the study records.",
+        path: ["query"],
+    })
+        .refine((d) => d.action !== "details" || (d.nctId !== undefined && d.nctId.trim().length > 0), {
+        message: "nctId is required when action is 'details' — one NCT ID, e.g. 'NCT00000102'. Find one with action 'search'.",
+        path: ["nctId"],
     }),
     describeCall: "none",
-    execute: async ({ query, phase, status, limit = 10, includeSummaries = false }) => {
+    execute: async ({ action = "search", query, nctId, phase, status, limit = 10, includeSummaries = false, }) => {
+        if (action === "details") {
+            return ok({ trial: await getTrialDetails(nctId) });
+        }
         const result = await searchTrials(query, { phase, status, limit });
         const trials = includeSummaries
             ? result.trials

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

@@ -1,11 +1,31 @@
 /**
- * searchFaers — search FDA FAERS for adverse event reports for a drug.
+ * searchFaers — one tool over the two openFDA drug corpora: the FAERS
+ * spontaneous adverse-event reports and the Structured Product Labels.
+ *
+ * The three actions answer one question between them — what is known about
+ * the post-market safety of this molecule. `adverse_events` ranks the reported
+ * reactions, `seriousness` counts the outcome flags behind them, and `label`
+ * gives the regulatory answer: the boxed warning, the Section 5 warnings, and
+ * whether a REMS program constrains the drug.
+ *
+ * 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"`).
  */
+import { type AdverseEventCount, type DrugLabelAction, type SeriousnessProfile } from "../lib/openfda-client.js";
+/** One result shape per action — the key names the records it carries. */
+type FaersOutput = {
+    totalReports: number | undefined;
+    adverseEvents: AdverseEventCount[];
+} | {
+    seriousness: SeriousnessProfile | null;
+} | {
+    labels: DrugLabelAction[];
+};
 export declare const searchFaersTool: import("../define-tool.js").Tool<{
+    action: "label" | "adverse_events" | "seriousness";
     drugName: string;
-    limit: number;
     serious: boolean;
-}, {
-    totalReports: number | undefined;
-    adverseEvents: import("../lib/openfda-client.js").AdverseEventCount[];
-}>;
+    limit?: number | undefined;
+}, FaersOutput>;
+export {};

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

@@ -1,34 +1,86 @@
 /**
- * searchFaers — search FDA FAERS for adverse event reports for a drug.
+ * searchFaers — one tool over the two openFDA drug corpora: the FAERS
+ * spontaneous adverse-event reports and the Structured Product Labels.
+ *
+ * The three actions answer one question between them — what is known about
+ * the post-market safety of this molecule. `adverse_events` ranks the reported
+ * reactions, `seriousness` counts the outcome flags behind them, and `label`
+ * gives the regulatory answer: the boxed warning, the Section 5 warnings, and
+ * whether a REMS program constrains the drug.
+ *
+ * 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"`).
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
-import { getFaersByDrug } from "../lib/openfda-client.js";
+import { getDrugLabelActions, getFaersByDrug, getFaersSeriousness, } from "../lib/openfda-client.js";
+/** `label` returns whole prose sections, so its ceiling is far below the others. */
+const LABEL_MAX_LIMIT = 10;
+const LABEL_DEFAULT_LIMIT = 3;
 export const searchFaersTool = defineTool({
     id: "search_faers",
-    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 marketed drug), use target_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("Generic (INN) drug name, e.g. 'imatinib', 'pembrolizumab'. Brand names do not match."),
+    description: "openFDA — the post-market drug record of the U.S. Food and Drug Administration, across two corpora: FAERS (the FDA Adverse Event Reporting " +
+        "System, spontaneous reports) and the Structured Product Labels (the approved prescribing information, served through DailyMed). Three lookups; " +
+        "pick with `action`.\n" +
+        "'adverse_events' (default) — 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.\n" +
+        "'seriousness' — the outcome breakdown behind those reports: totalReports plus fatalCount, hospitalizationCount, lifeThreateningCount, " +
+        "disablingCount, congenitalAnomalyCount and otherSeriousCount. This is how you tell a common nuisance reaction from a lethal one; the same " +
+        "no-denominator caveat holds.\n" +
+        "'label' — the regulatory position on the drug: boxedWarning text, the Section 5 warningsAndCautions excerpt, a REMS indicator, the brand and " +
+        "generic names, the application number, the label effective date and a citable DailyMed URL. This is the only action that carries an official " +
+        "warning rather than a report count.\n" +
+        "ACCEPTED IDENTIFIERS: a drug name in `drugName`. 'adverse_events' and 'seriousness' match the openFDA GENERIC name only — 'imatinib' works, the " +
+        "brand name 'Gleevec' does not. 'label' matches the generic OR the brand name, so a brand name goes in there and the genericName field of each " +
+        "row gives you the generic to use for the other two actions.\n" +
+        "For mechanism-based liabilities of a TARGET (rather than a marketed drug), use target_safety; for a chemical's toxicology use comptox.\n" +
+        "ABSENCE IS NORMAL: an empty adverseEvents array, a null seriousness, or an empty labels array means the drug is absent from that corpus under " +
+        "that name — say so and continue, do not retry the same name.",
+    inputSchema: z
+        .object({
+        action: z
+            .enum(["adverse_events", "seriousness", "label"])
+            .default("adverse_events")
+            .describe("'adverse_events' (default) — the ranked reaction terms. 'seriousness' — the outcome-flag breakdown for the same reports. 'label' — " +
+            "the FDA label: boxed warning, Section 5 warnings and REMS."),
+        drugName: z
+            .string()
+            .min(1)
+            .describe("The drug name. Generic (INN) for 'adverse_events' and 'seriousness', e.g. 'imatinib' or 'pembrolizumab' — a brand name matches " +
+            "nothing there. 'label' also accepts a brand name, e.g. 'Gleevec'."),
         limit: z
             .number()
             .int()
             .min(1)
             .max(100)
-            .default(15)
-            .describe("Max distinct adverse-reaction terms to return, most-reported first (default 15, max 100). totalReports covers the whole drug regardless."),
-        serious: z.boolean().default(false).describe("When true, count only reports flagged serious (death, hospitalization, life-threatening, disabling)."),
+            .optional()
+            .describe(`'adverse_events': max distinct adverse-reaction terms to return, most-reported first (default 15, max 100); totalReports covers the ` +
+            `whole drug regardless. 'label': max label versions, newest first (default ${LABEL_DEFAULT_LIMIT}, max ${LABEL_MAX_LIMIT}) — a ` +
+            `boxed warning runs to thousands of characters, so raise it only to trace how a warning changed. Ignored by 'seriousness'.`),
+        serious: z
+            .boolean()
+            .default(false)
+            .describe("'adverse_events' only. When true, count only reports flagged serious (death, hospitalization, life-threatening, disabling). For the " +
+            "breakdown of WHICH serious outcome, use action 'seriousness' instead."),
+    })
+        .refine((d) => d.action !== "label" || d.limit === undefined || d.limit <= LABEL_MAX_LIMIT, {
+        message: `limit is capped at ${LABEL_MAX_LIMIT} for action 'label' — each label version carries whole prose sections`,
+        path: ["limit"],
     }),
     describeCall: "none",
-    execute: async ({ drugName, limit = 15, serious = false }) => {
-        const result = await getFaersByDrug(drugName, { limit, serious });
-        return ok({
-            totalReports: result.totalReports,
-            adverseEvents: result.adverseEvents,
-        });
+    execute: async ({ action = "adverse_events", drugName, limit, serious = false }) => {
+        switch (action) {
+            case "seriousness":
+                return ok({ seriousness: await getFaersSeriousness(drugName) });
+            case "label":
+                return ok({ labels: await getDrugLabelActions(drugName, { limit: limit ?? LABEL_DEFAULT_LIMIT }) });
+            case "adverse_events": {
+                const result = await getFaersByDrug(drugName, { limit: limit ?? 15, serious });
+                return ok({ totalReports: result.totalReports, adverseEvents: result.adverseEvents });
+            }
+        }
     },
 });

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

@@ -1,10 +1,26 @@
 /**
- * searchGene — look up gene information via the Ensembl REST API.
+ * searchGene — resolve gene identifiers against the Ensembl REST API.
+ *
+ * Ensembl itself keys only on a symbol (`/lookup/symbol`), which makes an
+ * ENSG, a UniProt accession, a ChEMBL target id or an HGNC id unusable as
+ * input. That is the identifier a user pastes, so this tool takes it: an
+ * input that is not a plain symbol goes through `resolveTarget`, which anchors
+ * it on HGNC and UniProt, and the approved symbol it returns is what reaches
+ * Ensembl. `resolvedFrom` reports each such translation, thus the caller can
+ * see which input became which symbol.
  */
+import { type GeneInfo } from "../lib/ensembl-client.js";
+/** One input that was not a symbol, beside the approved symbol it became. */
+interface ResolvedIdentifier {
+    input: string;
+    symbol: string;
+}
 export declare const searchGeneTool: import("../define-tool.js").Tool<{
-    symbols: string[];
+    identifiers: string[];
     species: string;
 }, {
-    genes: import("../lib/ensembl-client.js").GeneInfo[];
+    genes: GeneInfo[];
+    resolvedFrom: ResolvedIdentifier[];
     notFound: string[];
 }>;
+export {};

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

@@ -1,30 +1,87 @@
 /**
- * searchGene — look up gene information via the Ensembl REST API.
+ * searchGene — resolve gene identifiers against the Ensembl REST API.
+ *
+ * Ensembl itself keys only on a symbol (`/lookup/symbol`), which makes an
+ * ENSG, a UniProt accession, a ChEMBL target id or an HGNC id unusable as
+ * input. That is the identifier a user pastes, so this tool takes it: an
+ * input that is not a plain symbol goes through `resolveTarget`, which anchors
+ * it on HGNC and UniProt, and the approved symbol it returns is what reaches
+ * Ensembl. `resolvedFrom` reports each such translation, thus the caller can
+ * see which input became which symbol.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { lookupGenes } from "../lib/ensembl-client.js";
+import { resolveTarget } from "../lib/identifier-resolver.js";
 /**
- * How many symbols a detail names before it switches to a count plus a sample.
- * Eight symbols of typical length stay well inside the emit-site cap, so the
- * listed form is never the thing that trips it.
+ * How many identifiers a detail names before it switches to a count plus a
+ * sample. Eight identifiers of typical length stay well inside the emit-site
+ * cap, so the listed form is never the thing that trips it.
  */
-const SYMBOLS_LISTED_IN_FULL = 8;
+const IDENTIFIERS_LISTED_IN_FULL = 8;
+/**
+ * The identifier spaces that Ensembl cannot key on. Anything that matches none
+ * of them is treated as a symbol and goes straight to Ensembl.
+ */
+const NON_SYMBOL_PATTERNS = [/^ENSG\d{11}$/, /^HGNC:\d+$/, /^CHEMBL\d+$/, /^[A-Z][0-9][A-Z0-9]{3}[0-9](-\d+)?$/];
+function isSymbol(identifier) {
+    return !NON_SYMBOL_PATTERNS.some((pattern) => pattern.test(identifier));
+}
 export const searchGeneTool = defineTool({
     id: "search_gene",
-    description: "Resolve gene symbols against Ensembl — the identifier step other tools depend on. Per symbol: Ensembl gene ID (ENSG…), coordinates, strand, " +
-        "biotype, assembly, description; plus notFound[]. Gene-level only — no transcripts or exons. Batch up to 200 symbols per call. " +
-        "notFound is valid no-data (deprecated, aliased or mistyped symbol, or wrong species) — do not retry unchanged.",
+    description: "Resolve gene identifiers against Ensembl — the identifier step other tools depend on. Per gene: Ensembl gene ID (ENSG…), coordinates, strand, " +
+        "biotype, assembly, description; plus resolvedFrom[] and notFound[]. Gene-level only — no transcripts or exons. Batch up to 200 identifiers per " +
+        "call.\n" +
+        "ACCEPTED IDENTIFIERS, mixed freely in one call: a HUGO gene symbol ('BRCA1'), an Ensembl gene ID ('ENSG00000012048'), an HGNC ID ('HGNC:1100'), " +
+        "a UniProt accession ('P38398') and a ChEMBL target ID ('CHEMBL5619'). An input that is not a symbol is anchored on the HGNC and UniProt " +
+        "registries first, and the approved symbol it yields is reported in resolvedFrom[] — that anchoring is human, so a non-symbol input with a " +
+        "non-human `species` looks the ortholog up by the human approved symbol.\n" +
+        "notFound is valid no-data (a deprecated, aliased or mistyped identifier, or one this species has no gene for) — report it and continue, do not " +
+        "retry unchanged.",
     inputSchema: z.object({
-        symbols: z.array(z.string()).min(1).max(200).describe("Gene symbols to look up (e.g. ['BRCA1', 'TP53'])"),
+        identifiers: z
+            .array(z.string())
+            .min(1)
+            .max(200)
+            .describe("Gene identifiers to look up, mixed freely (e.g. ['BRCA1', 'ENSG00000141510', 'P38398', 'HGNC:1100', 'CHEMBL5619'])"),
         species: z.string().default("homo_sapiens").describe("Species name (e.g. 'homo_sapiens', 'mus_musculus')"),
     }),
-    // The symbols are the call. A large batch is summarized here rather than
+    // The identifiers are the call. A large batch is summarized here rather than
     // left to the emit-site cap: that cap cuts at a character, so a 200-symbol
     // join arrives ending in `TP5` — a fragment that reads as a real symbol and
     // says nothing about how many were dropped. The count leads, so a batch is
     // legible as a batch even when the sample after it is itself trimmed.
-    describeCall: ({ symbols }) => symbols.length <= SYMBOLS_LISTED_IN_FULL ? symbols.join(", ") : `${symbols.length} genes: ${symbols.slice(0, SYMBOLS_LISTED_IN_FULL).join(", ")}, …`,
-    execute: async ({ symbols, species }) => ok(await lookupGenes(symbols, { species })),
+    describeCall: ({ identifiers }) => identifiers.length <= IDENTIFIERS_LISTED_IN_FULL
+        ? identifiers.join(", ")
+        : `${identifiers.length} genes: ${identifiers.slice(0, IDENTIFIERS_LISTED_IN_FULL).join(", ")}, …`,
+    execute: async ({ identifiers, species }) => {
+        const symbols = [];
+        const resolvedFrom = [];
+        const notFound = [];
+        for (const identifier of identifiers) {
+            const trimmed = identifier.trim();
+            if (isSymbol(trimmed)) {
+                symbols.push(trimmed);
+                continue;
+            }
+            // `resolveTarget` throws when it can anchor the input on no human
+            // gene. That is absence, so it becomes a notFound row.
+            try {
+                const resolved = await resolveTarget(trimmed);
+                resolvedFrom.push({ input: trimmed, symbol: resolved.geneSymbol });
+                symbols.push(resolved.geneSymbol);
+            }
+            catch {
+                notFound.push(trimmed);
+            }
+        }
+        const genes = [];
+        if (symbols.length > 0) {
+            const lookup = await lookupGenes(symbols, { species });
+            genes.push(...lookup.genes);
+            notFound.push(...lookup.notFound);
+        }
+        return ok({ genes, resolvedFrom, notFound });
+    },
 });

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

@@ -38,7 +38,10 @@ 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 — use it to find external validation cohorts or to cite published data. " +
+    description: "Search the NCBI Gene Expression Omnibus (GEO) — the public functional-genomics repository of the U.S. National Library of Medicine — for " +
+        "gene-expression datasets by disease, tissue, or experimental condition. Use it to find external validation cohorts or to cite published data. " +
+        "ACCEPTED IDENTIFIERS: an Entrez free-text query with optional field tags ('breast cancer RNA-seq'), a GEO accession ('GSE12345', 'GDS1234'), and " +
+        "an organism scientific name ('Homo sapiens') in `organism`. " +
         "Returns totalFound plus datasets[]: { accession (GSE…/GDS…), title, summary (truncated to 300 chars), platform, sampleCount, organism, pubmedIds }. " +
         "HARD CAVEAT: this tool returns metadata only, and sandbox containers have no network — never plan an in-sandbox step that downloads a GEO dataset. " +
         "Bringing the data itself in is a capability of the surrounding environment, not of this tool: consult the tools you actually have rather than assuming it is possible or that it is not. " +