@inflexa-ai/harness 0.29.0 → 0.30.1

package/dist/tools/bio/gene-disease-evidence.d.ts

@@ -1,8 +1,8 @@
 /**
- * geneDiseaseEvidence — one tool over the three gene↔disease evidence corpora:
- * the NHGRI-EBI GWAS Catalog, DisGeNET, and NCBI ClinVar.
+ * geneDiseaseEvidence — one tool over the four gene↔disease evidence corpora:
+ * the NHGRI-EBI GWAS Catalog, DisGeNET, NCBI ClinVar, and cBioPortal.
  *
- * These were three tools with the same input skeleton (`query` + a
+ * The first three were three tools with the same input skeleton (`query` + a
  * gene/disease/variant discriminator + a strength threshold + `limit`)
  * answering the same question — what genetic evidence links this gene to this
  * disease or trait. Picking between them was never a routing decision an agent
@@ -10,19 +10,28 @@
  * defaults to all of them. `search_pathway`'s `source: kegg | reactome | both`
  * is the same shape.
  *
+ * cBioPortal joins them as the somatic half of the same question, and it is the
+ * one source that is NOT in the default set: it scans every curated study, thus
+ * it costs several large requests that a routine gene query must not pay.
+ *
  * Each source runs independently and reports its own outcome in `perSource`: a
  * missing DisGeNET key or a GWAS Catalog outage degrades that one corpus to
- * `unavailable` instead of failing a call the other two could have answered.
+ * `unavailable` instead of failing a call the others could have answered.
  *
  * The input is a flat object with a `queryType` discriminator — not a
  * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs
- * a top-level `"type":"object"`).
+ * a top-level `"type":"object"`). A `queryType` that only one corpus can serve
+ * — an accession of that corpus — marks the others `not_applicable` rather
+ * than sending them a query they cannot read.
  */
+import { type MutationFrequency } from "../lib/cbioportal-client.js";
 import { type ClinvarVariant } from "../lib/clinvar-client.js";
 import { type Gda } from "../lib/disgenet-client.js";
 import { type GwasAssociation } from "../lib/gwas-catalog-client.js";
-declare const SOURCES: readonly ["gwas", "disgenet", "clinvar"];
+declare const SOURCES: readonly ["gwas", "disgenet", "clinvar", "cbioportal"];
 type Source = (typeof SOURCES)[number];
+declare const QUERY_TYPES: readonly ["gene", "disease", "variant", "gwas_study", "clinvar_accession"];
+type QueryType = (typeof QUERY_TYPES)[number];
 /**
  * Per-source outcome. `unavailable` (key absent, corpus erroring) and
  * `not_applicable` (the corpus has no lookup for this queryType) are both
@@ -38,19 +47,20 @@ interface SourceOutcome {
 }
 interface GeneDiseaseEvidenceOutput {
     query: string;
-    queryType: "gene" | "disease" | "variant";
+    queryType: QueryType;
     perSource: SourceOutcome[];
     gwas?: GwasAssociation[];
     disgenet?: Gda[];
     clinvar?: ClinvarVariant[];
+    cbioportal?: MutationFrequency[];
 }
 export declare function createGeneDiseaseEvidenceTool(deps: {
     ncbiApiKey?: string;
     disgenetApiKey: string;
 }): import("../define-tool.js").Tool<{
     query: string;
-    queryType: "gene" | "disease" | "variant";
-    sources?: ("clinvar" | "gwas" | "disgenet")[] | undefined;
+    queryType: "gene" | "disease" | "variant" | "gwas_study" | "clinvar_accession";
+    sources?: ("clinvar" | "gwas" | "disgenet" | "cbioportal")[] | undefined;
     limit?: number | undefined;
     pValueThreshold?: number | undefined;
     minScore?: number | undefined;

package/dist/tools/bio/gene-disease-evidence.js

@@ -1,8 +1,8 @@
 /**
- * geneDiseaseEvidence — one tool over the three gene↔disease evidence corpora:
- * the NHGRI-EBI GWAS Catalog, DisGeNET, and NCBI ClinVar.
+ * geneDiseaseEvidence — one tool over the four gene↔disease evidence corpora:
+ * the NHGRI-EBI GWAS Catalog, DisGeNET, NCBI ClinVar, and cBioPortal.
  *
- * These were three tools with the same input skeleton (`query` + a
+ * The first three were three tools with the same input skeleton (`query` + a
  * gene/disease/variant discriminator + a strength threshold + `limit`)
  * answering the same question — what genetic evidence links this gene to this
  * disease or trait. Picking between them was never a routing decision an agent
@@ -10,45 +10,87 @@
  * defaults to all of them. `search_pathway`'s `source: kegg | reactome | both`
  * is the same shape.
  *
+ * cBioPortal joins them as the somatic half of the same question, and it is the
+ * one source that is NOT in the default set: it scans every curated study, thus
+ * it costs several large requests that a routine gene query must not pay.
+ *
  * Each source runs independently and reports its own outcome in `perSource`: a
  * missing DisGeNET key or a GWAS Catalog outage degrades that one corpus to
- * `unavailable` instead of failing a call the other two could have answered.
+ * `unavailable` instead of failing a call the others could have answered.
  *
  * The input is a flat object with a `queryType` discriminator — not a
  * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs
- * a top-level `"type":"object"`).
+ * a top-level `"type":"object"`). A `queryType` that only one corpus can serve
+ * — an accession of that corpus — marks the others `not_applicable` rather
+ * than sending them a query they cannot read.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
+import { getSomaticMutationFrequencies } from "../lib/cbioportal-client.js";
 import { filterInformative, searchClinvar } from "../lib/clinvar-client.js";
 import { searchDisgenet } from "../lib/disgenet-client.js";
 import { searchGwasCatalog } from "../lib/gwas-catalog-client.js";
-const SOURCES = ["gwas", "disgenet", "clinvar"];
+const SOURCES = ["gwas", "disgenet", "clinvar", "cbioportal"];
+const QUERY_TYPES = ["gene", "disease", "variant", "gwas_study", "clinvar_accession"];
 const DEFAULT_LIMIT = 10;
 const MAX_LIMIT = 100;
-/** DisGeNET has no variant-level lookup; the other two do. */
+/** Which query types each corpus can read. An accession is readable by one corpus only. */
+const SOURCE_QUERY_TYPES = {
+    gwas: ["gene", "disease", "variant", "gwas_study"],
+    disgenet: ["gene", "disease"],
+    clinvar: ["gene", "disease", "variant", "clinvar_accession"],
+    cbioportal: ["gene"],
+};
+/**
+ * cBioPortal stays out of the default set. It scans every curated study, thus
+ * a caller opts into it by naming it in `sources`.
+ */
+const OPT_IN_SOURCES = ["cbioportal"];
 function applicableSources(queryType) {
-    return queryType === "variant" ? ["gwas", "clinvar"] : [...SOURCES];
+    return SOURCES.filter((source) => SOURCE_QUERY_TYPES[source].includes(queryType));
 }
+/** The corpora a call queries when it names none. */
+function defaultSources(queryType) {
+    return applicableSources(queryType).filter((source) => !OPT_IN_SOURCES.includes(source));
+}
+/**
+ * The GWAS Catalog name for each query type it serves. `clinvar_accession` is
+ * absent because `applicableSources` never selects the GWAS Catalog for it.
+ */
+const GWAS_SEARCH_TYPES = {
+    gene: "gene",
+    disease: "trait",
+    variant: "variant",
+    gwas_study: "study",
+};
 const inputSchema = z.object({
     query: z
         .string()
         .min(1)
-        .describe("The entity, matching `queryType`. gene: a HUGO symbol ('PCSK9'); DisGeNET also takes an Entrez ID. disease: a disease or trait name " +
-        "('LDL cholesterol'); DisGeNET also takes a UMLS CUI ('C0006142'). variant: a dbSNP rsID ('rs11591147')."),
+        .describe("The entity, matching `queryType`. gene: a HUGO symbol ('PCSK9'); DisGeNET also takes an Entrez ID, and cBioPortal takes the symbol " +
+        "directly. disease: a disease or trait name ('LDL cholesterol'); DisGeNET also takes a UMLS CUI ('C0006142'). variant: a dbSNP rsID " +
+        "('rs11591147'). gwas_study: a GWAS Catalog study accession ('GCST000392'). clinvar_accession: a ClinVar accession ('VCV000012345', " +
+        "'RCV000009910') or a bare variation ID."),
     queryType: z
-        .enum(["gene", "disease", "variant"])
+        .enum(QUERY_TYPES)
         .describe("'gene' — the diseases/traits associated with a gene. 'disease' — the genes associated with a disease or trait (the GWAS Catalog calls it a " +
-        "trait; this value covers both). 'variant' — one rsID; DisGeNET is skipped, having no variant-level lookup."),
+        "trait; this value covers both). 'variant' — one rsID; DisGeNET is skipped, having no variant-level lookup. 'gwas_study' — every " +
+        "association reported by ONE GWAS Catalog study, read back from the studyAccession that a gwas record carries; GWAS Catalog only. " +
+        "'clinvar_accession' — one ClinVar record, read back from the accession that a clinvar record carries; ClinVar only."),
     sources: z
         .array(z.enum(SOURCES))
         .min(1)
         .optional()
-        .describe("Corpora to query in parallel. Default ALL applicable — they carry different evidence types, and disagreement between them is itself informative. " +
-        "'gwas': population SNP-trait associations with effect sizes and p-values (common-variant / MR support). " +
+        .describe("Corpora to query in parallel. Default ALL applicable EXCEPT cbioportal — they carry different evidence types, and disagreement between them " +
+        "is itself informative. " +
+        "'gwas': the NHGRI-EBI GWAS Catalog — population SNP-trait associations with effect sizes and p-values (common-variant / MR support). " +
         "'disgenet': curated + text-mined gene-disease associations scored 0–1, broadest coverage; needs DISGENET_API_KEY. " +
-        "'clinvar': clinically classified germline variants — pathogenicity and review status; rare/Mendelian rather than common-variant."),
+        "'clinvar': NCBI ClinVar — clinically classified germline variants, pathogenicity and review status; rare/Mendelian rather than " +
+        "common-variant. " +
+        "'cbioportal': the somatic half — how often the gene is mutated in each cancer type across every curated cBioPortal study, as " +
+        "cancerTypeName, mutatedSamples/totalSamples, frequency and the contributing studies. OPT IN by naming it: it scans every study, so it is " +
+        "several seconds slower than the rest, and it applies to queryType 'gene' only."),
     limit: z
         .number()
         .int()
@@ -110,18 +152,22 @@ async function runSource(source, fetch) {
 export function createGeneDiseaseEvidenceTool(deps) {
     return defineTool({
         id: "gene_disease_evidence",
-        description: "Genetic evidence linking a gene to a disease or trait, across the GWAS Catalog, DisGeNET and ClinVar in one call — 'is there human genetic " +
-            "support for this target in this indication?'. See `sources` for what each corpus carries.\n" +
+        description: "Genetic evidence linking a gene to a disease or trait, across the NHGRI-EBI GWAS Catalog, DisGeNET, NCBI ClinVar and cBioPortal in one call " +
+            "— 'is there human genetic support for this target in this indication?'. See `sources` for what each corpus carries.\n" +
             "For the integrated, pre-scored view prefer opentargets({action:'target'}) FIRST — it folds genetic association together with tractability " +
-            "and the drug landscape. Reach here for the underlying records: actual SNPs, effect sizes, scores and pathogenicity calls with their studies and PMIDs.\n" +
+            "and the drug landscape. Reach here for the underlying records: actual SNPs, effect sizes, scores, pathogenicity calls and somatic mutation " +
+            "frequencies with their studies and PMIDs.\n" +
+            "ACCEPTED IDENTIFIERS, each named by its `queryType`: a HUGO gene symbol or an Entrez ID ('PCSK9', '5008'); a disease or trait name or a UMLS " +
+            "CUI ('LDL cholesterol', 'C0006142'); a dbSNP rsID ('rs11591147'); a GWAS Catalog study accession ('GCST000392'); and a ClinVar accession " +
+            "('VCV000012345'). The last two read one record back by the accession that an earlier result of this same tool reported.\n" +
             "ALWAYS read `perSource` before concluding anything is absent. 'no_data' means that corpus genuinely has nothing; 'unavailable' means it " +
-            "could not be reached (a missing DISGENET_API_KEY lands here — tell the user and proceed with the other two); 'not_applicable' means that " +
+            "could not be reached (a missing DISGENET_API_KEY lands here — tell the user and proceed with the others); 'not_applicable' means that " +
             "corpus has no lookup for this queryType. Only 'no_data' is evidence of absence, and none is worth retrying unchanged.",
         inputSchema,
         describeCall: "none",
         execute: async (input) => {
             const applicable = applicableSources(input.queryType);
-            const requested = input.sources ?? applicable;
+            const requested = input.sources ?? defaultSources(input.queryType);
             const selected = requested.filter((s) => applicable.includes(s));
             const limit = input.limit ?? DEFAULT_LIMIT;
             const output = {
@@ -136,10 +182,10 @@ export function createGeneDiseaseEvidenceTool(deps) {
                     detail: `${source} has no lookup for queryType '${input.queryType}'`,
                 })),
             };
-            const [gwas, disgenet, clinvar] = await Promise.all([
+            const [gwas, disgenet, clinvar, cbioportal] = await Promise.all([
                 selected.includes("gwas")
                     ? runSource("gwas", async () => {
-                        const searchType = input.queryType === "gene" ? "gene" : input.queryType === "disease" ? "trait" : "variant";
+                        const searchType = GWAS_SEARCH_TYPES[input.queryType];
                         const res = await searchGwasCatalog(input.query, searchType, {
                             limit,
                             ...(input.pValueThreshold !== undefined ? { pValueThreshold: input.pValueThreshold } : {}),
@@ -169,6 +215,12 @@ export function createGeneDiseaseEvidenceTool(deps) {
                         return { records: variants, totalFound: res.totalFound };
                     })
                     : null,
+                selected.includes("cbioportal")
+                    ? runSource("cbioportal", async () => {
+                        const res = await getSomaticMutationFrequencies(input.query);
+                        return { records: res.rows.slice(0, limit), totalFound: res.rows.length };
+                    })
+                    : null,
             ]);
             if (gwas) {
                 output.perSource.push(gwas.outcome);
@@ -182,6 +234,10 @@ export function createGeneDiseaseEvidenceTool(deps) {
                 output.perSource.push(clinvar.outcome);
                 output.clinvar = clinvar.records;
             }
+            if (cbioportal) {
+                output.perSource.push(cbioportal.outcome);
+                output.cbioportal = cbioportal.records;
+            }
             return ok(output);
         },
     });

package/dist/tools/bio/gene-preclinical-profile.d.ts

@@ -1,20 +1,24 @@
 /**
- * genePreclinicalProfile — the in-vivo preclinical picture of one gene: where
- * it is expressed at baseline (Bgee) and what removing it does to a mouse
- * (IMPC), behind one `include`.
+ * genePreclinicalProfile — the in-vivo picture of one gene: where it is
+ * expressed at baseline (Bgee), what removing it does to a mouse (IMPC), and
+ * what people who carry variation in it present with (Monarch, HPO), behind
+ * one `include`.
  *
- * The two halves share an input exactly — ONE human gene symbol, with the
- * per-species orthologs resolved internally — and answer one question between
- * them: is this target expressed where it needs to act, and is a model organism
- * a fair surrogate for it. They were two tools that were called as a pair.
+ * The three halves share an input exactly — ONE human gene symbol, with the
+ * per-species orthologs and the gene curie resolved internally — and answer one
+ * question between them: is this target expressed where it needs to act, is a
+ * model organism a fair surrogate for it, and what does losing it do to a
+ * person. The first two were two tools that were called as a pair.
  *
- * Neither source caps its own output: Bgee returns every annotated tissue per
- * species and IMPC every significant phenotype term, so both halves are trimmed
- * here rather than in the clients — the target-assessment collectors read the
- * same clients and legitimately want full fidelity for the dossier.
+ * No source caps its own output: Bgee returns every annotated tissue per
+ * species, IMPC every significant phenotype term, and Monarch every curated
+ * HPO annotation, so each half is trimmed here rather than in the clients — the
+ * target-assessment collectors read the same clients and legitimately want full
+ * fidelity for the dossier.
  */
 import { type SupportedSpecies, type TissueRow } from "../lib/bgee-client.js";
 import { type MpTerm, type ViabilityCall, type ViabilityCategory } from "../lib/impc-client.js";
+import { type MonarchPhenotypeAssociation } from "../lib/monarch-client.js";
 interface BoundedSpeciesEntry {
     species: SupportedSpecies;
     taxonId: number;
@@ -30,6 +34,21 @@ interface ExpressionHalf {
     bySpecies: BoundedSpeciesEntry[];
     notFound: string[];
 }
+/**
+ * One curated human phenotype. The HPO ancestor closure of the source record
+ * is dropped here: it exists so a dossier collector can resolve an organ system
+ * by identifier, and it runs to hundreds of ids that a reader never uses.
+ */
+type HumanPhenotypeTerm = Omit<MonarchPhenotypeAssociation, "ancestorIds">;
+interface HumanPhenotypeHalf {
+    /** The curie Monarch was queried by, e.g. `HGNC:1100`; null when the symbol did not anchor on HGNC. */
+    geneCurie: string | null;
+    hpoTerms: HumanPhenotypeTerm[];
+    /** Curated HPO annotations before `phenotypeLimit`. */
+    phenotypeCount: number;
+    /** True when `phenotypeLimit` trimmed `hpoTerms`; `phenotypeCount` is the real total. */
+    phenotypesTrimmed: boolean;
+}
 interface KnockoutHalf {
     mouseMarkerSymbol: string | null;
     mgiAccessionId: string | null;
@@ -46,12 +65,13 @@ type PreclinicalOutput = {
     geneSymbol: string;
     expression?: ExpressionHalf;
     knockout?: KnockoutHalf;
+    phenotypes?: HumanPhenotypeHalf;
 };
 export declare const genePreclinicalProfileTool: import("../define-tool.js").Tool<{
     geneSymbol: string;
-    include?: ("expression" | "knockout")[] | undefined;
+    include?: ("phenotypes" | "expression" | "knockout")[] | undefined;
     species?: ("homo_sapiens" | "mus_musculus" | "rattus_norvegicus" | "canis_lupus_familiaris" | "macaca_mulatta")[] | undefined;
-    minRank?: "absent" | "high" | "medium" | "low" | undefined;
+    minRank?: "low" | "medium" | "high" | "absent" | undefined;
     tissueLimit?: number | undefined;
     phenotypeLimit?: number | undefined;
 }, PreclinicalOutput>;

package/dist/tools/bio/gene-preclinical-profile.js

@@ -1,23 +1,28 @@
 /**
- * genePreclinicalProfile — the in-vivo preclinical picture of one gene: where
- * it is expressed at baseline (Bgee) and what removing it does to a mouse
- * (IMPC), behind one `include`.
+ * genePreclinicalProfile — the in-vivo picture of one gene: where it is
+ * expressed at baseline (Bgee), what removing it does to a mouse (IMPC), and
+ * what people who carry variation in it present with (Monarch, HPO), behind
+ * one `include`.
  *
- * The two halves share an input exactly — ONE human gene symbol, with the
- * per-species orthologs resolved internally — and answer one question between
- * them: is this target expressed where it needs to act, and is a model organism
- * a fair surrogate for it. They were two tools that were called as a pair.
+ * The three halves share an input exactly — ONE human gene symbol, with the
+ * per-species orthologs and the gene curie resolved internally — and answer one
+ * question between them: is this target expressed where it needs to act, is a
+ * model organism a fair surrogate for it, and what does losing it do to a
+ * person. The first two were two tools that were called as a pair.
  *
- * Neither source caps its own output: Bgee returns every annotated tissue per
- * species and IMPC every significant phenotype term, so both halves are trimmed
- * here rather than in the clients — the target-assessment collectors read the
- * same clients and legitimately want full fidelity for the dossier.
+ * No source caps its own output: Bgee returns every annotated tissue per
+ * species, IMPC every significant phenotype term, and Monarch every curated
+ * HPO annotation, so each half is trimmed here rather than in the clients — the
+ * target-assessment collectors read the same clients and legitimately want full
+ * fidelity for the dossier.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { SUPPORTED_SPECIES, getMultiSpeciesExpression } from "../lib/bgee-client.js";
+import { resolveTarget } from "../lib/identifier-resolver.js";
 import { getKoPhenotypeProfile } from "../lib/impc-client.js";
+import { getGenePhenotypeProfile } from "../lib/monarch-client.js";
 /** Ordered weakest → strongest so `minRank` can be a numeric floor. */
 const RANK_ORDER = { absent: 0, low: 1, medium: 2, high: 3 };
 /** Human + mouse: the pairing that answers "is the mouse a fair surrogate?". */
@@ -30,11 +35,13 @@ const inputSchema = z.object({
         .describe("HUMAN gene symbol, e.g. 'BRCA1' — one gene per call. Ensembl IDs, mouse symbols and MGI IDs are NOT accepted; the ENSG and the per-species " +
         "orthologs are resolved for you."),
     include: z
-        .array(z.enum(["expression", "knockout"]))
+        .array(z.enum(["expression", "knockout", "phenotypes"]))
         .min(1)
         .optional()
-        .describe("Default BOTH — two sides of one judgement, one request each. 'expression': Bgee baseline (healthy, untreated) expression per species and " +
-        "tissue. 'knockout': IMPC mouse loss-of-function phenotype."),
+        .describe("Default ['expression','knockout'] — two sides of one judgement, one request each. 'expression': Bgee baseline (healthy, untreated) " +
+        "expression per species and tissue. 'knockout': IMPC mouse loss-of-function phenotype. 'phenotypes': the HUMAN counterpart — the curated " +
+        "HPO phenotypes that Monarch attributes to variation in this gene, from HPOA, OMIM and Orphanet, each with its PMIDs and the disease it " +
+        "was annotated under. Ask for it explicitly, and pair it with 'knockout' when the question is whether the mouse recapitulates the person."),
     species: z
         .array(z.enum(SUPPORTED_SPECIES))
         .min(1)
@@ -60,8 +67,9 @@ const inputSchema = z.object({
         .min(1)
         .max(200)
         .optional()
-        .describe(`'knockout' only. Max MP phenotype terms, best p-value first (default ${DEFAULTS.phenotypeLimit}, max 200). \`phenotypeCount\` gives the ` +
-        "true total; `organSystems` is never trimmed, so the top-line picture survives."),
+        .describe(`'knockout' and 'phenotypes'. Max phenotype terms per half — MP terms best p-value first, HPO terms in curation order (default ` +
+        `${DEFAULTS.phenotypeLimit}, max 200). Each half reports its own \`phenotypeCount\` for the true total; \`organSystems\` is never ` +
+        "trimmed, so the top-line knockout picture survives."),
 });
 function boundExpression(raw, minRank, tissueLimit) {
     const floor = RANK_ORDER[minRank];
@@ -95,31 +103,64 @@ function boundKnockout(raw, phenotypeLimit) {
         phenotypesTrimmed: raw.mpTerms.length > phenotypeLimit,
     };
 }
+/**
+ * Anchor the symbol on HGNC and read the curated human phenotypes. A symbol
+ * that anchors on no HGNC id gives a null curie and an empty term list, which
+ * is absence and not a failure.
+ */
+async function fetchHumanPhenotypes(geneSymbol, phenotypeLimit) {
+    let geneCurie;
+    try {
+        geneCurie = (await resolveTarget(geneSymbol)).ids.hgnc;
+    }
+    catch {
+        geneCurie = null;
+    }
+    if (!geneCurie)
+        return { geneCurie: null, hpoTerms: [], phenotypeCount: 0, phenotypesTrimmed: false };
+    const profile = await getGenePhenotypeProfile(geneCurie);
+    return {
+        geneCurie: profile.geneCurie,
+        hpoTerms: profile.phenotypes.slice(0, phenotypeLimit).map(({ ancestorIds: _ancestorIds, ...term }) => term),
+        phenotypeCount: profile.phenotypes.length,
+        phenotypesTrimmed: profile.phenotypes.length > phenotypeLimit,
+    };
+}
 export const genePreclinicalProfileTool = defineTool({
     id: "gene_preclinical_profile",
-    description: "The in-vivo preclinical profile of ONE human gene — baseline expression (Bgee) and mouse-knockout phenotype (IMPC) in one call. Answers " +
-        "tissue-of-action ('where does this target act?'), model-organism suitability ('is the mouse a fair surrogate?') and essentiality ('what happens " +
-        "when this gene is lost?').\n" +
+    description: "The in-vivo profile of ONE human gene across three corpora in one call — baseline expression from Bgee, the mouse-knockout phenotype from IMPC " +
+        "(the International Mouse Phenotyping Consortium), and the curated human phenotypes from the Monarch Initiative (HPO terms sourced from HPOA, " +
+        "OMIM and Orphanet). Answers tissue-of-action ('where does this target act?'), model-organism suitability ('is the mouse a fair surrogate?'), " +
+        "essentiality ('what happens when this gene is lost?') and the human read-out ('what do people carrying variation in it present with?').\n" +
         "Expression is BASELINE (healthy, untreated) only — differential expression between conditions is the analysis pipeline's job, never this tool.\n" +
+        "ACCEPTED IDENTIFIERS: one HUMAN gene symbol, e.g. 'BRCA1'. The ENSG, the per-species orthologs and the HGNC curie are resolved for you; an " +
+        "Ensembl ID, a mouse symbol and an MGI ID are not accepted here — put those through search_gene first.\n" +
         "Output is trimmed by default (see `minRank`, `tissueLimit`, `phenotypeLimit`); the accompanying counts distinguish a trimmed list from a sparse one.\n" +
         "SPARSE OUTPUT IS VALID NO-DATA, not an error — do not retry. A null humanEnsemblId means the symbol did not resolve; a null mouseMarkerSymbol " +
-        "with no phenotype terms means the gene has not been IMPC-phenotyped, which is common.",
+        "with no phenotype terms means the gene has not been IMPC-phenotyped, which is common; an empty hpoTerms list means Monarch curates no human " +
+        "phenotype for the gene, and a null geneCurie means the symbol anchored on no HGNC id.",
     inputSchema,
     describeCall: "none",
     execute: async ({ geneSymbol, include, species, minRank, tissueLimit, phenotypeLimit }) => {
         const halves = include ?? ["expression", "knockout"];
         const wantExpression = halves.includes("expression");
         const wantKnockout = halves.includes("knockout");
-        const [expressionRaw, knockoutRaw] = await Promise.all([
+        const wantPhenotypes = halves.includes("phenotypes");
+        const termLimit = phenotypeLimit ?? DEFAULTS.phenotypeLimit;
+        const [expressionRaw, knockoutRaw, phenotypesHalf] = await Promise.all([
             wantExpression ? getMultiSpeciesExpression(geneSymbol, [...(species ?? DEFAULT_SPECIES)]) : Promise.resolve(null),
             wantKnockout ? getKoPhenotypeProfile(geneSymbol) : Promise.resolve(null),
+            wantPhenotypes ? fetchHumanPhenotypes(geneSymbol, termLimit) : Promise.resolve(null),
         ]);
         const output = { geneSymbol };
         if (expressionRaw) {
             output.expression = boundExpression(expressionRaw, minRank ?? DEFAULTS.minRank, tissueLimit ?? DEFAULTS.tissueLimit);
         }
         if (knockoutRaw) {
-            output.knockout = boundKnockout(knockoutRaw, phenotypeLimit ?? DEFAULTS.phenotypeLimit);
+            output.knockout = boundKnockout(knockoutRaw, termLimit);
+        }
+        if (phenotypesHalf) {
+            output.phenotypes = phenotypesHalf;
         }
         return ok(output);
     },

package/dist/tools/bio/lookup-annotation.d.ts

@@ -38,6 +38,7 @@ type AnnotationOutput = {
 export declare const lookupAnnotationTool: import("../define-tool.js").Tool<{
     vocabulary: "kegg" | "reactome" | "go" | "pathways";
     query?: string | undefined;
+    pathwayId?: string | undefined;
     goId?: string | undefined;
     geneProductId?: string | undefined;
     taxonId?: number | undefined;

package/dist/tools/bio/lookup-annotation.js

@@ -18,7 +18,7 @@ import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
-import { searchPathways } from "../lib/pathway-client.js";
+import { getPathwayById, searchPathways } from "../lib/pathway-client.js";
 const QUICKGO_BASE = "https://www.ebi.ac.uk/QuickGO/services";
 const HEADERS = { Accept: "application/json" };
 const DEFAULT_LIMIT = 10;
@@ -70,13 +70,20 @@ const inputSchema = z
         .enum(["go", "kegg", "reactome", "pathways"])
         .describe("'go' — Gene Ontology via QuickGO (EBI); needs ONE of goId, query, or geneProductId. Returns terms[] { id, name, definition, aspect } " +
         "and/or annotations[] { geneProductId, goId, goName, aspect, evidenceCode, qualifier }. " +
-        "'kegg' / 'reactome' — one pathway database; needs query. 'pathways' — both, in parallel; needs query. " +
-        "Returns pathways[] { id, name, source, url, genes? }."),
+        "'kegg' / 'reactome' — one pathway database; needs query or pathwayId. 'pathways' — both, in parallel; needs query or pathwayId. " +
+        "Returns pathways[] { id, name, source, url, description?, genes? }."),
     query: z
         .string()
         .min(1)
         .optional()
-        .describe("Free-text term. Required for the pathway vocabularies ('apoptosis', 'MAPK signaling'); for 'go' it is one of the three accepted inputs."),
+        .describe("Free-text term. Required for the pathway vocabularies ('apoptosis', 'MAPK signaling') unless pathwayId is given; for 'go' it is one of " +
+        "the three accepted inputs."),
+    pathwayId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Pathway vocabularies only. ONE pathway identifier, read back exactly as a search returned it — a Reactome stable ID ('R-HSA-109581') " +
+        "or a KEGG pathway ID ('hsa04010'). The prefix picks the database, so `vocabulary` and `organism` are ignored for it."),
     goId: z
         .string()
         .regex(/^GO:\d{7}$/)
@@ -98,9 +105,13 @@ const inputSchema = z
         .optional()
         .describe(`Max records per vocabulary queried (default ${DEFAULT_LIMIT}, max 100); with 'pathways' it applies to KEGG and Reactome separately.`),
 })
-    .refine((d) => d.vocabulary === "go" || (d.query !== undefined && d.query.trim().length > 0), {
-    message: "query is required for vocabulary 'kegg', 'reactome' and 'pathways' — the pathway term to search for",
+    .refine((d) => d.vocabulary === "go" || (d.query !== undefined && d.query.trim().length > 0) || (d.pathwayId !== undefined && d.pathwayId.length > 0), {
+    message: "vocabulary 'kegg', 'reactome' and 'pathways' need query (the pathway term to search for) or pathwayId (one 'R-HSA-…' or 'hsa…' identifier)",
     path: ["query"],
+})
+    .refine((d) => d.vocabulary !== "go" || d.pathwayId === undefined, {
+    message: "pathwayId belongs to the pathway vocabularies — vocabulary 'go' takes goId instead",
+    path: ["pathwayId"],
 })
     .refine((d) => d.vocabulary !== "go" || d.goId !== undefined || d.query !== undefined || d.geneProductId !== undefined, {
     message: "vocabulary 'go' needs at least one of goId (term by ID), query (free-text term search), or geneProductId (a protein's annotations)",
@@ -116,16 +127,23 @@ const inputSchema = z
 });
 export const lookupAnnotationTool = defineTool({
     id: "lookup_annotation",
-    description: "Functional annotation for a gene, protein or term — Gene Ontology (QuickGO) and the pathway databases (KEGG, Reactome) behind one `vocabulary`. " +
-        "Names what a gene is known to do, resolves a GO or pathway identifier, or finds the pathways a term belongs to.\n" +
+    description: "Functional annotation for a gene, protein or term — the Gene Ontology (through EBI QuickGO) and the pathway databases KEGG and Reactome, behind " +
+        "one `vocabulary`. Names what a gene is known to do, resolves a GO or pathway identifier, or finds the pathways a term belongs to.\n" +
+        "ACCEPTED IDENTIFIERS: a GO term ID ('GO:0008150'), a UniProt accession for a protein's annotations ('P04637'), an NCBI Taxon ID ('9606'), a " +
+        "Reactome stable ID ('R-HSA-109581'), a KEGG pathway ID ('hsa04010'), and free text for any of the vocabularies ('apoptosis').\n" +
         "This is annotation LOOKUP, not enrichment: to test whether a gene SET is over-represented in GO/KEGG/Reactome terms use " +
         "search_interactions({action:'enrichment'}), which does the statistics.\n" +
-        "An empty terms / annotations / pathways array is valid no-data — do not retry the same input.",
+        "An empty terms / annotations / pathways array is valid no-data — report it and continue, do not retry the same input. An empty pathways array " +
+        "for a pathwayId means neither database holds that identifier.",
     inputSchema,
     describeCall: "none",
-    execute: async ({ vocabulary, query, goId, geneProductId, taxonId, organism, includeGenes, limit }) => {
+    execute: async ({ vocabulary, query, pathwayId, goId, geneProductId, taxonId, organism, includeGenes, limit, }) => {
         const cap = limit ?? DEFAULT_LIMIT;
         if (vocabulary !== "go") {
+            if (pathwayId) {
+                const pathway = await getPathwayById(pathwayId);
+                return ok({ pathways: pathway ? [pathway] : [] });
+            }
             const pathways = await searchPathways(query, {
                 source: vocabulary === "pathways" ? "both" : vocabulary,
                 organism: organism ?? "hsa",

package/dist/tools/bio/opentargets.d.ts

@@ -17,18 +17,26 @@
  * 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 { type Association, type TargetInfo } from "../lib/opentargets-client.js";
+import { type Association, type DiseaseCandidate, type TargetInfo } from "../lib/opentargets-client.js";
 type OpenTargetsOutput = {
     targetInfo: TargetInfo | null;
     associations: Association[];
 } | {
     associations: Association[];
+} | {
+    totalFound: number;
+    candidates: DiseaseCandidate[];
 };
 export declare const openTargetsTool: import("../define-tool.js").Tool<{
-    action: "target" | "disease";
+    action: "target" | "disease" | "resolve_disease";
     ensemblId?: string | undefined;
     efoId?: string | undefined;
+    diseaseName?: string | undefined;
     limit?: number | undefined;
 }, OpenTargetsOutput>;
 export {};