@inflexa-ai/harness 0.40.0 → 0.41.1

package/dist/tools/ad-hoc-router.js

@@ -23,10 +23,15 @@ const resourcesSchema = z.object({
     gpu: z.object({ count: z.number().int().positive() }).optional(),
 });
 const routeSchema = z.object({
-    agentId: z.string().optional(),
-    resources: resourcesSchema.optional(),
-    rationale: z.string().optional(),
-    packages: z.array(z.string()).optional(),
+    agentId: z.string().optional().describe("The id of one specialist from the eligible catalog, copied exactly."),
+    resources: resourcesSchema
+        .optional()
+        .describe("The sandbox resources of the step, inside the stated ranges. Omit to take the defaults; a value outside the ranges is replaced by the defaults."),
+    rationale: z.string().optional().describe("One or two sentences on why this specialist fits the request. The step agent reads it."),
+    packages: z
+        .array(z.string())
+        .optional()
+        .describe("The packages that the scripts of the step import, each as `[python:|r:]<name>[==<version>]`. An empty array is valid."),
 });
 export function defaultAdHocResources(policy) {
     return policy ? { cpu: Math.min(4, policy.perStep.maxCpu), memoryGb: Math.min(8, policy.perStep.maxMemoryGb) } : { cpu: 4, memoryGb: 8 };

package/dist/tools/bio/chembl.js

@@ -38,10 +38,11 @@ const inputSchema = z
         .describe("Which ChEMBL lookup to run; each names its params and return fields.\n" +
         "'compounds' (query + searchType) — molecules by target, name or SMILES: resolve a named compound to its ID and structure, or list " +
         "what was assayed against a target. → chemblId, preferredCompoundName, canonicalSmiles, molecularWeight, alogp, molecularFormula.\n" +
-        "'drug' (query) — approved drugs by indication or by drug name: 'what treats X?', 'is Y approved, since when?'. → moleculeChemblId, " +
-        "preferredName, maxPhase (4 = approved), moleculeType, firstApproval, indication. A disease term reads the curated indication " +
-        "registry, highest phase first; a query that matches no disease term reads the approved molecules (max_phase >= 4) instead, and " +
-        "their indications come back with them.\n" +
+        "'drug' (query) — approved drugs by drug name or by indication: 'is Y approved, since when?', 'what treats X?'. → moleculeChemblId, " +
+        "preferredName, maxPhase (4 = approved), moleculeType, firstApproval, indication. The query is read as a molecule name first: the " +
+        "approved molecules (max_phase 4) that it names come back with their indications. A query that names no approved molecule is then " +
+        "read as a disease term against the curated indication registry, highest phase first, and those rows can hold clinical-stage " +
+        "molecules. Thus a clinical-stage compound queried by name gives an empty array; action 'compounds' resolves it.\n" +
         "'mechanism' (chemblId, molecule only) — curated mechanism of ONE molecule: 'how does X work?'. → mechanismOfAction, actionType " +
         "(INHIBITOR, AGONIST, …), targetChemblId + targetName, moleculeChemblId. Curated mainly for clinical/approved molecules, so tool " +
         "compounds often have none.\n" +
@@ -62,7 +63,9 @@ const inputSchema = z
     searchType: z
         .enum(["target", "compound", "smiles"])
         .optional()
-        .describe("Required for 'compounds' — how to read `query`. 'target': resolve to a ChEMBL target, then return what was assayed against it. " +
+        .describe("Required for 'compounds' — how to read `query`. 'target': resolve `query` to the TOP ChEMBL target hit only — the result does not " +
+        "name that target, and a symbol can hit a non-human ortholog — then return what was assayed against it; a target ChEMBL ID from " +
+        "action 'targets' pins the target. " +
         "'compound': free-text over molecule names. 'smiles': flexmatch structure search."),
     chemblId: z
         .string()

package/dist/tools/bio/comptox.js

@@ -45,8 +45,8 @@ const inputSchema = z
         "HTTK toxicokinetic parameters, reported functional uses, consumer-product composition."),
     query: z
         .string()
-        .describe("Chemical identifier (all datasets). A DTXSID ('DTXSID7020182') is used directly; a CASRN ('80-05-7'), a name ('bisphenol A'), or — for " +
-        "dataset 'chemical' — an InChIKey is resolved by EXACT match, so a non-canonical or misspelled name yields found: false."),
+        .describe("Chemical identifier (all datasets). A DTXSID ('DTXSID7020182') is used directly; a CASRN ('80-05-7'), a name ('bisphenol A'), or " +
+        "an InChIKey is resolved by EXACT match, so a non-canonical or misspelled name yields found: false."),
     dataType: z
         .enum(["toxval", "genetox", "cancer", "seem", "httk", "functional-use", "product-data", "all"])
         .optional()
@@ -103,8 +103,8 @@ export function createComptoxTool(deps) {
             "bioactivity), 'hazard' (in-vivo: " +
             "NOAEL/LOAEL/LD50, genotoxicity, cancer), 'chemical' (identity + physicochemical/ADMET), 'exposure' (SEEM predictions, toxicokinetics, uses, " +
             "products). See `dataset` for what each returns; all four resolve `query` to a DTXSID first.\n" +
-            "ACCEPTED IDENTIFIERS: a DTXSID ('DTXSID7020182') used directly, or a CASRN ('80-05-7'), a chemical name ('bisphenol A') or — for dataset " +
-            "'chemical' — an InChIKey, each resolved by EXACT match.\n" +
+            "ACCEPTED IDENTIFIERS, for every dataset: a DTXSID ('DTXSID7020182') used directly, or a CASRN ('80-05-7'), a chemical name " +
+            "('bisphenol A') or an InChIKey, each resolved by EXACT match.\n" +
             "Requires EPA_CCTE_API_KEY — a missing key fails terminally: do NOT retry, tell the user the key needs configuring and proceed without EPA data.\n" +
             "found: false means the query did not resolve to a chemical; a present-but-empty section is likewise valid no-data. Do not retry either.\n" +
             "This is environmental/industrial-chemical data: for drug-like compounds prefer PubChem or ChEMBL — dataset 'chemical' returns " +

package/dist/tools/bio/drug-gene-interactions.js

@@ -106,11 +106,12 @@ export function createDrugGeneInteractionsTool(deps) {
         description: "Drug↔gene interactions across DGIdb (the Drug Gene Interaction Database), DrugBank and PharmGKB, in one call — 'what drugs hit these " +
             "genes?' and 'what genes does this drug act on?'. See `direction` and `sources` for the modes.\n" +
             "ACCEPTED IDENTIFIERS: a HUGO gene symbol ('EGFR') for direction 'gene_to_drugs'; a drug name ('imatinib'), a DrugBank ID ('DB00619') or a " +
-            "DGIdb concept ID for 'drug_to_genes'. A brand name and a non-HUGO symbol match nothing — resolve the symbol with search_gene and the brand " +
-            "name with search_faers({action:'label'}) first.\n" +
-            "It answers whether an interaction is KNOWN, by whom, and of what type. For quotable POTENCY (IC50/Ki) use chembl({action:'bioactivity'}) instead.\n" +
+            "DGIdb concept ID for 'drug_to_genes'. A brand name and a non-HUGO symbol match nothing — resolve the symbol with search_gene, and pass " +
+            "the generic drug name, not the brand name.\n" +
+            "It answers whether an interaction is KNOWN, by whom, and of what type. It carries no potency value (IC50/Ki).\n" +
             "Verbose fields (`includeAttributes`, `includeDrugRecord`) are off by default — both cost a lot of context and are rarely what the question needs.\n" +
-            "ALWAYS read `perSource` before concluding an interaction is unknown: 'no_data' means that corpus has nothing; 'unavailable' means it could " +
+            "`perSource` gives the outcome of each corpus, and a conclusion that an interaction is unknown rests on it: 'no_data' means that corpus " +
+            "has nothing; 'unavailable' means it could " +
             "not be reached (a missing DRUGBANK_API_KEY lands here — tell the user and proceed with DGIdb). A `found: false` entry means the identifier " +
             "is not in DGIdb at all, usually a non-HUGO symbol or a brand name. Neither is worth retrying unchanged.",
         inputSchema,

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

@@ -156,15 +156,15 @@ export function createGeneDiseaseEvidenceTool(deps) {
         id: "gene_disease_evidence",
         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, pathogenicity calls and somatic mutation " +
-            "frequencies with their studies and PMIDs.\n" +
+            "It returns the underlying records — actual SNPs, effect sizes, scores, pathogenicity calls and somatic mutation frequencies with their " +
+            "studies and PMIDs — not one integrated score across evidence types.\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 ('asthma', '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. " +
             "The GWAS Catalog matches the EXACT EFO trait label (case-insensitive): 'asthma' resolves, a paraphrase such as 'LDL cholesterol' reads as " +
             "no_data there ('low density lipoprotein cholesterol measurement' is the label) while the other corpora still answer it.\n" +
-            "ALWAYS read `perSource` before concluding anything is absent. 'no_data' means that corpus genuinely has nothing; 'unavailable' means it " +
+            "`perSource` gives the outcome of each corpus, and a conclusion of absence rests on it. '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 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,

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

@@ -84,7 +84,9 @@ const inputSchema = z
     vocabulary: 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 }. " +
+        "and/or annotations[] { geneProductId, goId, goName, aspect, evidenceCode, qualifier } — the first `limit` rows that QuickGO " +
+        "serves, one row for each term, evidence and reference, thus a term can repeat, a well-studied protein holds hundreds of rows, " +
+        "and the result gives no total. " +
         "'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
@@ -110,8 +112,10 @@ const inputSchema = z
     includeGenes: z
         .boolean()
         .optional()
-        .describe("Pathway vocabularies only. Default FALSE — member-gene lists cost one request per pathway and run to hundreds of symbols. True only when " +
-        "you need the members, not the pathway identities."),
+        .describe("Pathway vocabularies only. Default FALSE — member lists cost one request per pathway and run to hundreds of entries. KEGG members " +
+        "are NCBI Gene (Entrez) IDs ('7157'), not symbols. Reactome members are participant entity names with their compartment " +
+        "('p-T389/412-RPS6KB1 [cytosol]', 'ATP [cytosol]'), small molecules included. True only when you need the members, not the " +
+        "pathway identities."),
     limit: z
         .number()
         .int()

package/dist/tools/bio/opentargets.js

@@ -32,7 +32,9 @@ const inputSchema = z
     action: z
         .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 " +
+        "tractability — for smallMolecule, antibody and otherModalities, the labels of the positive Open Targets buckets, from " +
+        "'Approved Drug' and 'Advanced Clinical' down to 'High-Quality Pocket' or 'UniProt loc high conf'; an empty list means no " +
+        "positive bucket and null means no assessment) 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. " +
@@ -75,11 +77,11 @@ const inputSchema = z
 });
 export const openTargetsTool = defineTool({
     id: "opentargets",
-    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" +
+    description: "Query the Open Targets Platform — the integrated target-disease evidence corpus of EMBL-EBI, GSK and their partners. One 'target' query " +
+        "gives the tractability of the target and its disease associations, already scored and ranked, each with a per-datatype score for genetic " +
+        "association, known drug, literature, animal model and somatic mutation. See the action parameter for what each mode needs and returns.\n" +
+        "It is the integrated view, not the underlying records: it names no drug, no SNP, no effect size, no ClinVar call and no PMID, and it " +
+        "holds no safety liability.\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 " +

package/dist/tools/bio/pubchem.js

@@ -19,14 +19,16 @@ const inputSchema = z
     action: z
         .enum(["compound", "crossrefs", "assays"])
         .describe("Which PubChem lookup to run. " +
-        "'compound' — resolve `query` (in the namespace named by `searchBy`) to a compound. Returns results[]: identity (cid, canonicalSmiles, inchi, inchiKey, iupacName, " +
+        "'compound' — resolve `query` (in the namespace named by `searchBy`) to a compound. Returns results[]: identity (cid, canonicalSmiles — " +
+        "the PubChem connectivity SMILES, with no stereochemistry and no isotopes, thus inchi is the full structure — inchi, inchiKey, iupacName, " +
         "molecularFormula) and computed properties (molecularWeight, xlogp, tpsa, hbondDonorCount, hbondAcceptorCount, rotatableBondCount, complexity). " +
         "'crossrefs' — external registry ids for a `cid`. Returns crossRefs[]: a flat list of { source, id } entries. `source` names the registry that the id pattern " +
         "identifies — ChEMBL, ChEBI, DrugBank, KEGG, HMDB, CAS, PDB or UNII — and it is null for an id of any other registry; filter by `source` for the one you want. " +
         "This is the bridge out of PubChem. " +
         "'assays' — bioassay screening summaries for a `cid`; answers 'has this compound ever been screened, and against what?'. Returns assays[]: aid, assayName, targetName " +
         "(the target accession, for example a UniProt or PDB id), " +
-        "activityOutcome (Active / Inactive / Inconclusive / Unspecified), activityValue. Broad HTS screening coverage, NOT curated potency — for numbers you intend to quote " +
+        "activityOutcome (Active / Inactive / Inconclusive / Unspecified), activityValue (in µM; null when the assay reports none). Broad HTS " +
+        "screening coverage, NOT curated potency — for numbers you intend to quote " +
         "(IC50/Ki), prefer chembl action='bioactivity'."),
     query: z
         .string()

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

@@ -37,7 +37,7 @@ type PubMedOutput = {
 } | ({
     pmcId: string;
     available: true;
-} & BoundedFullText);
+} & Omit<BoundedFullText, "sections">);
 export declare function createPubMedTool(deps: {
     ncbiApiKey?: string;
 }): import("../define-tool.js").Tool<{

package/dist/tools/bio/pubmed.js

@@ -34,8 +34,9 @@ const inputSchema = z
     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, journal, year, DOI, pmcId (non-null only when open-access " +
-        "full text exists in PubMed Central), plus the leading authors and MeSH terms with authorCount / meshTermCount giving the true totals. " +
+        "'details' (needs pmids, max 20 per call) — each article's full abstract, journal, year, DOI, pmcId (non-null when the article is in " +
+        "PubMed Central, which includes articles outside the open-access subset), plus the leading authors and MeSH terms with authorCount / " +
+        "meshTermCount giving the true totals. " +
         "'fulltext' (needs pmcId, taken from a 'details' result) — the body of ONE open-access PMC article as plain text with section headers " +
         "preserved, trimmed to maxChars; `outline` lists every section with its size and whether it came back, and truncated says whether " +
         "anything was left out. available: false when the article is not open-access."),
@@ -122,10 +123,10 @@ export function createPubMedTool(deps) {
             "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" +
+            "'details' ('34567890'); and a PMC ID for 'fulltext' ('PMC7096066'), never a PMID — the PMC number of an article differs from its PMID. " +
+            "PubMed holds MEDLINE and PMC only, thus a method, a model or a preprint outside MEDLINE is often absent here.\n" +
             "Read " +
-            "fulltext sparingly — only where the 'details' abstract is not enough, and only for articles that have a pmcId (open-access). " +
+            "fulltext sparingly — only where the 'details' abstract is not enough, and only for articles that have a pmcId. " +
             "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. " +
             "An empty result set and available: false are expected outcomes, not errors — an article with no PMC record simply has no open full text. " +
@@ -172,7 +173,10 @@ export function createPubMedTool(deps) {
                     // "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, ...parsed });
+                    // `fullText` already holds each admitted section under its heading, thus the
+                    // `sections` array would send the same text to the model a second time.
+                    const { sections: _sections, ...bounded } = parsed;
+                    return ok({ pmcId: input.pmcId, available: true, ...bounded });
                 }
             }
         },

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

@@ -23,7 +23,8 @@ export const searchClinicalTrialsTool = defineTool({
         "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" +
+        "read a result, as opposed to finding a trial. The 'details' answer is not trimmed: a large trial with posted results carries hundreds of " +
+        "adverse-event terms, each with its per-arm counts, thus one answer can run to tens of thousands of characters.\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" +
         "`status` is an optional server-side filter and `phase` narrows the returned page. Omit both to see the full landscape. totalFound reports the true " +

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

@@ -34,7 +34,8 @@ export const searchGeneTool = defineTool({
         "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 " +
+        "a six-character UniProt accession ('P38398') and a ChEMBL target ID ('CHEMBL5619'); a ten-character accession ('A0A0B4J1Y9') is read " +
+        "as a symbol and lands in notFound. 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 " +

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

@@ -12,12 +12,16 @@ export const searchInteractionsTool = defineTool({
         "evidence into one confidence score — for interactions and gene-set functional enrichment. " +
         "'partners' — the one-hop interaction partners of the input proteins, score-sorted: 'what else does this protein work with?'. " +
         "'network' — the interactions AMONG the input proteins only, no new nodes: 'is my gene set actually connected?'. " +
-        "'enrichment' — statistical over-representation of GO, KEGG, Reactome and Pfam terms in the input set, FDR-sorted: the enrichment TEST, as " +
+        "'enrichment' — statistical over-representation of terms in the input set against the whole genome, FDR-sorted, over every STRING " +
+        "category: GO Process / Function / Component, KEGG, Reactome (RCTM), Pfam, InterPro, UniProt keywords, COMPARTMENTS, DISEASES, HPO, " +
+        "WikiPathways and PubMed publications (PMID) among them, with `category` naming the source of each row. It is the enrichment TEST, as " +
         "opposed to lookup_annotation, which just reads a vocabulary. " +
         "ACCEPTED IDENTIFIERS: STRING resolves each one itself, so a HUGO gene symbol ('TP53'), a UniProt accession ('P04637'), an Ensembl protein ID " +
         "('ENSP00000269305') and a full protein name all work, mixed in one call. `species` takes an NCBI Taxonomy ID (9606 = human).\n" +
-        "`limit` applies to all three actions and defaults small: a network over N proteins grows with N² edges. `totalEdges` / `totalTerms` give the " +
-        "pre-trim counts. An empty result is valid no-data (unconnected set, no enriched term, unresolvable identifiers) — report it and continue, do " +
+        "`limit` applies to all three actions and defaults small: a network over N proteins grows with N² edges. For 'partners', STRING applies " +
+        "it to EACH input protein, thus N inputs give up to N × limit rows. `totalEdges` / `totalTerms` give the pre-trim counts of 'network' and " +
+        "'enrichment'; 'partners' gives no total. An empty result is valid no-data (unconnected set, no enriched term, unresolvable identifiers) — " +
+        "report it and continue, do " +
         "not retry.",
     inputSchema: z.object({
         identifiers: z.array(z.string()).min(1).max(100).describe("Protein/gene identifiers (e.g. ['TP53', 'BRCA1'])"),
@@ -36,7 +40,7 @@ export const searchInteractionsTool = defineTool({
             .min(1)
             .max(500)
             .default(DEFAULT_LIMIT)
-            .describe(`Max records returned — partners, network edges, or enriched terms depending on action (default ${DEFAULT_LIMIT}, max 500). ` +
+            .describe(`Max records returned — partners PER INPUT PROTEIN, network edges, or enriched terms depending on action (default ${DEFAULT_LIMIT}, max 500). ` +
             "Rows are ordered best-first (score descending for interactions, FDR ascending for enrichment), so the default keeps the strongest."),
     }),
     describeCall: "none",

package/dist/tools/bio/target-safety.js

@@ -93,7 +93,8 @@ export const targetSafetyTool = defineTool({
     id: "target_safety",
     description: "TARGET-level, mechanism-based safety liability — the curated secondary-pharmacology panel and Open Targets' curated liabilities in one call. " +
         "Judges what engaging a target is likely to do to an organ system, before any specific molecule exists.\n" +
-        "ACCEPTED IDENTIFIERS, mixed freely in one call: a HUGO gene symbol ('HERG', 'KCNH2'), a ChEMBL target ID ('CHEMBL240'), a UniProt accession " +
+        "ACCEPTED IDENTIFIERS, mixed freely in one call: an approved HUGO gene symbol ('KCNH2' — an alias such as 'hERG' matches no panel entry), a " +
+        "ChEMBL target ID ('CHEMBL240'), a UniProt accession " +
         "('Q12809') and an Ensembl gene ID ('ENSG00000055118').\n" +
         "This is the safety of the TARGET, not of a drug. For a marketed molecule's post-market adverse events use search_faers; for a chemical's " +
         "toxicology use comptox; for what removing the gene does in vivo use gene_preclinical_profile.\n" +

package/dist/tools/display/show-user.js

@@ -41,7 +41,7 @@ const ShowUserInputSchema = z.object({
     dataPath: z
         .string()
         .optional()
-        .describe("echart only: analysis-rooted CSV artifact path (e.g. 'runs/run-abc/step-2/output/de-summary.csv') the host loads as the ECharts `dataset.source` at render time. Author `encode`/dimensions against the CSV's column names (read only its header) and omit `dataset.source` from the spec — the rows are never pulled through the context window. If the data is not chart-ready (needs aggregation, filtering, reshaping), do that in a sandbox step that writes a chart-ready CSV. Inline `dataset.source` is only for a handful of numbers you just computed in conversation that exist nowhere as an artifact."),
+        .describe("echart only: analysis-rooted CSV artifact path (e.g. 'runs/run-abc/step-2/output/de-summary.csv') the host loads as the ECharts `dataset.source` at render time. Author `encode`/dimensions against the CSV's column names (read only its header) and omit `dataset.source` from the spec — the rows are never pulled through the context window. The tool checks the shape of the path only, not that the file exists; a wrong path fails only when the card renders. If the data is not chart-ready (needs aggregation, filtering, reshaping), do that in a sandbox step that writes a chart-ready CSV. Inline `dataset.source` is only for a handful of numbers you just computed in conversation that exist nowhere as an artifact."),
     body: z.string().optional().describe("Markdown content to render (kind=markdown)"),
     code: z.string().optional().describe("Code content (kind=code)"),
     language: z.string().optional().describe("Language identifier, e.g. r, python, bash (kind=code)"),

package/dist/tools/execute-analysis.js

@@ -23,9 +23,17 @@ import { callExtendAnalysisFarm } from "./sandbox/link-packages.js";
 const planIdSchema = z.string().regex(/^pln-[a-f0-9]{8}$/, "planId must be a pln-<8hex> value");
 const inputSchema = z
     .object({
-    mode: z.enum(["plan", "adhoc"]),
-    planId: planIdSchema.optional(),
-    request: z.string().min(1).optional(),
+    mode: z
+        .enum(["plan", "adhoc"])
+        .describe("`plan` runs a stored plan that the user approved. `adhoc` runs one targeted step for an explicit user request."),
+    planId: planIdSchema
+        .optional()
+        .describe("mode=plan only, and required there: the `pln-<8hex>` id of the approved stored plan. Omit it for mode=adhoc."),
+    request: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("mode=adhoc only, and required there: the computational request of the user, in the words of the user. Omit it for mode=plan."),
 })
     .superRefine((value, ctx) => {
     if (value.mode === "plan" && (value.planId === undefined || value.request !== undefined)) {
@@ -319,7 +327,9 @@ export function createExecuteAnalysisTool(deps) {
         description: "Launch analysis computation asynchronously. Use mode=plan with the planId only after the user approved that stored plan. " +
             "Use mode=adhoc with the user's exact targeted computational request when they explicitly asked to run/compute/test/compare it; " +
             "that explicit request is consent and needs no synthetic-plan approval. If computation is merely your suggestion, ask first. " +
-            "You never choose the sandbox specialist: ad hoc routing does that automatically. Returns runId with status=in_progress; inspect results on a later turn.",
+            "You never choose the sandbox specialist: ad hoc routing does that automatically. Returns runId with status=in_progress; inspect results on a later turn. " +
+            "A plan that already has an active run returns that run, so a second run of one plan does not start. " +
+            "The launch fails with an error, and no run starts, when the plan is not found or fails validation, when a package of the plan cannot link, or when the run is not authorized.",
         inputSchema,
         // The mode is what a user most needs to see here — an approved plan
         // running is a different event from an ad hoc request being routed.

package/dist/tools/lib/opentargets-client.d.ts

@@ -22,10 +22,15 @@ export interface Association {
     somaticMutationScore: number | null;
     literaturePmids: string[];
 }
+/**
+ * The positive tractability buckets of each modality, by their Open Targets label
+ * ('Approved Drug', 'Structure with Ligand', 'UniProt loc high conf', …). An empty
+ * list means no positive bucket. `null` means Open Targets gives no row for the modality.
+ */
 export interface TargetTractability {
-    smallMolecule: boolean | null;
-    antibody: boolean | null;
-    otherModalities: boolean | null;
+    smallMolecule: string[] | null;
+    antibody: string[] | null;
+    otherModalities: string[] | null;
 }
 export interface TargetInfo {
     ensemblId: string;

package/dist/tools/lib/opentargets-client.js

@@ -277,10 +277,19 @@ export async function searchTargetAssociations(ensemblId, limit = 25) {
     if (!target)
         return null;
     const tractabilityEntries = target.tractability ?? [];
+    // Open Targets gives one row for each bucket of a modality, from 'Approved Drug' down to a
+    // predicted pocket or a localization. The first row alone is the 'Approved Drug' bucket, thus
+    // each modality keeps the labels of all of its positive rows.
+    const positiveLabels = (modality) => {
+        const rows = tractabilityEntries.filter((t) => t.modality === modality);
+        if (rows.length === 0)
+            return null;
+        return rows.flatMap((t) => (t.value === true && t.label ? [t.label] : []));
+    };
     const tractability = {
-        smallMolecule: tractabilityEntries.find((t) => t.modality === "SM")?.value ?? null,
-        antibody: tractabilityEntries.find((t) => t.modality === "AB")?.value ?? null,
-        otherModalities: tractabilityEntries.find((t) => t.modality === "OC")?.value ?? null,
+        smallMolecule: positiveLabels("SM"),
+        antibody: positiveLabels("AB"),
+        otherModalities: positiveLabels("OC"),
     };
     const rows = data.associations?.associatedDiseases?.rows ?? [];
     const associations = rows.map((row) => ({

package/dist/tools/read-tool-output.js

@@ -5,7 +5,7 @@
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { unwrapOrThrow } from "../lib/result.js";
-import { pairSafeIndex, READ_TOOL_OUTPUT_TOOL_ID, TOOL_RESULT_CAP } from "../loop/tool-output.js";
+import { pairSafeIndex, READ_TOOL_OUTPUT_TOOL_ID, TOOL_OUTPUT_KEEP_MAX, TOOL_RESULT_CAP } from "../loop/tool-output.js";
 import { defineTool } from "./define-tool.js";
 const DEFAULT_PAGE_CHARS = 8 * 1024;
 const MAX_PAGE_CHARS = 16 * 1024;
@@ -105,9 +105,12 @@ function search(ref, text, start, limit, pattern) {
 export function createReadToolOutputTool(store) {
     return defineTool({
         id: READ_TOOL_OUTPUT_TOOL_ID,
-        description: "Read the full text of a tool result that came back as an excerpt. A result longer than the limit of the context " +
-            "comes back as its start and its end, and the excerpt gives a reference when the harness kept the whole text. " +
-            "Pass that reference as `ref`. Read a window with `offset` and `limit`: an offset counts the characters " +
+        description: "Read the kept text of a tool result that came back as an excerpt. A tool result longer than " +
+            `${TOOL_RESULT_CAP} characters comes back as its start and its end, and the excerpt gives a reference when the harness kept the text. ` +
+            `Pass that reference as \`ref\`. The harness keeps at most ${TOOL_OUTPUT_KEEP_MAX} characters. Of a longer text, it keeps the first ` +
+            "half and the last half of that bound, with a line between them that gives the count of characters not kept. " +
+            "A reference that the harness did not keep gives the status `not_found`, and the rest of that result cannot be read. " +
+            "Read a window with `offset` and `limit`: an offset counts the characters " +
             `(UTF-16 code units) of the kept text from 0, and a page has at most ${MAX_PAGE_CHARS} characters, ` +
             `${DEFAULT_PAGE_CHARS} by default. Or give \`pattern\`, a JavaScript regular expression, to get at most ` +
             `${MAX_MATCHES} matches, each with its offset and the text around it. When a result gives \`more: true\`, ` +

package/dist/tools/report-authoring/authoring-tools.js

@@ -54,13 +54,20 @@ const blockPayload = z.union([AuthoringBlockSchema, z.unknown()]);
  * present. Under `.optional()` each of those nulls fails the input parse, and the block never lands.
  */
 const absentable = (schema) => schema.nullish();
+/** The meaning of each flat destination field. The add and the move share it. */
+const DESTINATION_NOTES = {
+    parentId: "The id of the section that holds the destination. Leave it out for the root. An anchor in `before` or `after` implies its parent.",
+    place: "Put the block at the `start` or the `end` of the parent. The default is `end`. Give a place or an anchor, not both.",
+    before: "The id of a sibling block. The block lands directly before it.",
+    after: "The id of a sibling block. The block lands directly after it.",
+};
 /** The flat destination fields. An anchor is `before` or `after`, and a place is `start` or `end`. */
 const addBlockInput = z.object({
     block: blockPayload,
-    parentId: absentable(z.string()),
-    place: absentable(z.enum(["start", "end"])),
-    before: absentable(z.string()),
-    after: absentable(z.string()),
+    parentId: absentable(z.string()).describe(DESTINATION_NOTES.parentId),
+    place: absentable(z.enum(["start", "end"])).describe(DESTINATION_NOTES.place),
+    before: absentable(z.string()).describe(DESTINATION_NOTES.before),
+    after: absentable(z.string()).describe(DESTINATION_NOTES.after),
 });
 /**
  * The change payload is a title for a section target, or a block for an atom target, and exactly one of
@@ -68,27 +75,27 @@ const addBlockInput = z.object({
  * `z.unknown()` as a required key, thus an optional marker is what makes the retitle call representable.
  */
 const changeBlockInput = z.object({
-    targetId: z.string(),
-    title: absentable(z.string()),
-    block: blockPayload.optional(),
+    targetId: z.string().describe("The id of the block to change, as the outline gives it."),
+    title: absentable(z.string()).describe("The new title of a section target. Give a title or a block, not both."),
+    block: blockPayload.optional().describe("The replacement of an atom target. Give a title or a block, not both."),
 });
 const removeBlockInput = z.object({
-    targetId: z.string(),
+    targetId: z.string().describe("The id of the block to remove, as the outline gives it."),
 });
 const moveBlockInput = z.object({
-    targetId: z.string(),
-    parentId: absentable(z.string()),
-    place: absentable(z.enum(["start", "end"])),
-    before: absentable(z.string()),
-    after: absentable(z.string()),
+    targetId: z.string().describe("The id of the block to move, as the outline gives it."),
+    parentId: absentable(z.string()).describe(DESTINATION_NOTES.parentId),
+    place: absentable(z.enum(["start", "end"])).describe(DESTINATION_NOTES.place),
+    before: absentable(z.string()).describe(DESTINATION_NOTES.before),
+    after: absentable(z.string()).describe(DESTINATION_NOTES.after),
 });
 const readOutlineInput = z.object({});
 /** The read names its target with the same field name as each mutation, thus one id key serves them all. */
 const readBlockInput = z.object({
-    targetId: z.string(),
+    targetId: z.string().describe("The id of the block to read, as the outline gives it."),
 });
 const setTitleInput = z.object({
-    title: z.string().min(1),
+    title: z.string().min(1).describe("The title of the whole report."),
 });
 const finishDraftInput = z.object({});
 /**

package/dist/tools/report-session/derive-table.js

@@ -144,7 +144,11 @@ export function createDeriveTableTool(deps) {
             "That directory is the one place that the script can write: the analysis mounts read-only, and the container has no network. " +
             "The standard output carries the logs of the script alone, thus a table that it prints there reaches nobody. " +
             "The derived table joins the pinned evidence of this session, thus a block binds its path the same way as a pinned artifact. " +
-            "A name that this session already derived is refused, thus a second derivation of one table takes a new name.",
+            "A name that this session already derived is refused, thus a second derivation of one table takes a new name. " +
+            `Limits: the script holds at most ${String(SCRIPT_CAP_BYTES / 1024)} KiB, inputs holds at most ${String(INPUT_CAP)} paths, ` +
+            `and the run stops after ${String(DERIVATION_DEADLINE_MS / 1000)} seconds. ` +
+            "A failed script gives back exec-failed with the tail of its standard error. " +
+            "The outcome unavailable means that this host cannot run a derivation, and a repeat gives the same outcome.",
         inputSchema: deriveTableInput,
         executionMode: "inline",
         describeCall: (input) => `derive ${input.output}`,

package/dist/tools/report-session/examine-page.js

@@ -226,13 +226,14 @@ export function createExaminePageTool(deps) {
     const releaseMs = deps.deadlines?.releaseMs ?? RELEASE_DEADLINE_MS;
     return defineTool({
         id: "examine_page",
-        description: "Open the rendered report page in a real headless browser, and report what you see. " +
-            "Give back one or more screenshots, the coverage of the look, the console errors, and the failed requests. " +
+        description: "Open the rendered report page in a real headless browser, and give back what a reviewer sees: " +
+            "one or more screenshots, the coverage of the look, the console errors, and the failed requests. " +
             "A tall page arrives as consecutive top-to-bottom slices in document order, and the tiles list names the rows of each slice. " +
             "The coverage says whether the pictures hold the whole page, a truncated top portion of it, or the top window alone. " +
             "Run it after the preview to look at the current page, and to confirm that the layout and the charts read clean. " +
-            "The report tool records a version only after you look at the current page. " +
-            "If the page has no confirmed render, run the preview again first.",
+            "A look at the page of the current draft is what lets record_report_version record. " +
+            "The outcomes no-page and missed-stamp mean that no preview rendered the current page: run preview_report, then look again. " +
+            "The outcome no-browser means that this host gives no browser, and a repeat gives the same outcome.",
         inputSchema: examinePageInput,
         executionMode: "inline",
         describeCall: "none",

package/dist/tools/report-session/preview-report.js

@@ -393,9 +393,14 @@ export function createPreviewReportTool(deps) {
     const resolvePageAsset = deps.resolvePageAsset ?? resolvePageAssetFromInstallation;
     return defineTool({
         id: "preview_report",
-        description: "Render the current draft to a self-contained HTML page, and give back the page path. " +
+        description: "Render the current draft to an HTML page in the session directory, and give back the page path. " +
+            "The page loads its figures, table data, and libraries from an assets directory that the tool stages beside it. " +
             "The tool finishes the draft first: an incomplete draft gives back the gap list, and no page renders. " +
             "On a pass it resolves each reference, stages each bound image beside the page, and writes the page. " +
+            "An unresolved reference gives back the block and the binding to repair. " +
+            "The outcome resolver-unavailable means that this host gives no reference resolver, and a repeat gives the same outcome. " +
+            "A rendered page carries pagePath, and access when the host serves the page: a URL with its expiry, or the reason that no URL was granted. " +
+            "The render marks the page that examine_page looks at next. " +
             "Use it to see the report, and to confirm that each reference resolves.",
         inputSchema: previewReportInput,
         executionMode: "inline",

package/dist/tools/report-session/record-version.js

@@ -128,7 +128,8 @@ export function createRecordVersionTool(deps) {
         id: "record_report_version",
         description: "Record the current draft as one report version. The tool runs the whole gate first: it finishes the draft, " +
             "resolves each reference, matches each chart encoding, and matches each assert. An incomplete draft gives back the gap list, " +
-            "and a failed reference gives back the block that broke. The tool records a version only after the eyes look at the current page. " +
+            "and a failed reference gives back the block that broke. The tool records a version only after examine_page looked at the page of the current draft: " +
+            "with no look it gives back never-seen, and after an edit since the look it gives back stale-look. " +
             "A thread holds one version, thus a later record replaces it whole. Amend the draft, look at the page again, and record again. " +
             "After the version lands, the tool removes the file of each derived table that no block of the recorded report binds.",
         inputSchema: recordVersionInput,

package/dist/tools/research/context7-docs.js

@@ -43,7 +43,10 @@ function renderSnippets(snippets) {
 }
 export const resolveLibraryIdTool = defineTool({
     id: "resolve_library_id",
-    description: "Resolve a package name (e.g., 'scanpy', 'DESeq2', 'scikit-learn') to a Context7 library ID. Call this BEFORE `query_docs` to get the library ID needed for documentation lookup. Returns matching libraries ranked by relevance.",
+    description: "Resolve a package name (e.g., 'scanpy', 'DESeq2', 'scikit-learn') to the Context7 library ID that `query_docs` needs. " +
+        "Returns the single best match as {found: true, libraryId, name, description}, or {found: false} when Context7 holds no library for the name. " +
+        "`query` ranks the candidates and only the top one comes back, thus make sure that `name` is the package you meant. " +
+        "A failed Context7 request returns an error result.",
     inputSchema: z.object({
         libraryName: z.string().describe("Package or library name to search for (e.g., 'scanpy', 'pysam', 'lifelines')."),
         query: z.string().describe("What you need help with — used to rank results by relevance (e.g., 'how to run differential expression')."),
@@ -69,7 +72,10 @@ export const resolveLibraryIdTool = defineTool({
 });
 export const queryDocsTool = defineTool({
     id: "query_docs",
-    description: "Query up-to-date documentation and code examples for a library. You must call `resolve_library_id` first to get the libraryId. Use this to verify function signatures, parameters, and usage patterns before writing code.",
+    description: "Query up-to-date documentation and code examples for a library. The libraryId comes from `resolve_library_id`. " +
+        "Returns {found: true, documentation}: Markdown snippets, each with a title, a source id, a description, and code blocks. " +
+        "Returns {found: false} when Context7 holds no library at that ID or no snippet for the query. A failed Context7 request returns an error result. " +
+        "Use this to verify function signatures, parameters, and usage patterns before writing code.",
     inputSchema: z.object({
         libraryId: z.string().describe("Context7 library ID exactly as `resolve_library_id` gave it — an owner and a library, for example '/scverse/scanpy'."),
         query: z.string().describe("Specific question about the library (e.g., 'rank_genes_groups function parameters and usage')."),