@inflexa-ai/harness 0.13.0 → 0.14.0

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

@@ -1,7 +1,10 @@
 /**
  * opentargets — one tool over the Open Targets Platform: target-disease
- * association evidence (from a gene or from a disease) and the target's
- * curated safety liabilities.
+ * association evidence, read from a gene or from a disease.
+ *
+ * The curated safety liabilities this tool used to serve now belong to
+ * `target_safety`, which pairs them with the local secondary-pharmacology panel
+ * and resolves the Ensembl id they need.
  *
  * The input is a flat object with an `action` discriminator — not a
  * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs
@@ -15,22 +18,15 @@
  * result rather than an error. Naming the two identifiers apart is what makes
  * that contract visible at the call site.
  */
-import { type Association, type SafetyLiability, type TargetInfo } from "../lib/opentargets-client.js";
+import { type Association, type TargetInfo } from "../lib/opentargets-client.js";
 type OpenTargetsOutput = {
     targetInfo: TargetInfo | null;
     associations: Association[];
 } | {
     associations: Association[];
-} | {
-    found: false;
-    ensemblId: string;
-} | {
-    found: true;
-    targetSymbol: string;
-    safetyLiabilities: SafetyLiability[];
 };
 export declare const openTargetsTool: import("../define-tool.js").Tool<{
-    action: "target" | "disease" | "safety";
+    action: "target" | "disease";
     ensemblId?: string | undefined;
     efoId?: string | undefined;
     limit?: number | undefined;

package/dist/tools/bio/opentargets.js

@@ -1,7 +1,10 @@
 /**
  * opentargets — one tool over the Open Targets Platform: target-disease
- * association evidence (from a gene or from a disease) and the target's
- * curated safety liabilities.
+ * association evidence, read from a gene or from a disease.
+ *
+ * The curated safety liabilities this tool used to serve now belong to
+ * `target_safety`, which pairs them with the local secondary-pharmacology panel
+ * and resolves the Ensembl id they need.
  *
  * The input is a flat object with an `action` discriminator — not a
  * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs
@@ -18,32 +21,30 @@
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
-import { getTargetSafetyLiabilities, searchDiseaseAssociations, searchTargetAssociations, } from "../lib/opentargets-client.js";
+import { searchDiseaseAssociations, searchTargetAssociations } from "../lib/opentargets-client.js";
+const DEFAULT_LIMIT = 10;
 const inputSchema = z
     .object({
     action: z
-        .enum(["target", "disease", "safety"])
+        .enum(["target", "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. " +
-        "'safety' (needs ensemblId) — the target's curated safety liabilities: found: true with targetSymbol and " +
-        "safetyLiabilities[] { event, biosamples (affected tissues), effects (direction of effect), source }. This is TARGET-level, " +
-        "mechanism-based safety — for the post-market adverse events of a specific marketed DRUG use search_faers instead."),
-    ensemblId: z.string().optional().describe("Ensembl gene ID, e.g. ENSG00000141510 (TP53). Required for action 'target' and 'safety'."),
+        "and the same score breakdown."),
+    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'."),
     limit: z
         .number()
         .int()
         .min(1)
         .max(100)
-        .default(25)
         .optional()
-        .describe("Max associations to return (default 25, max 100), ordered by descending association score. Ignored by 'safety'."),
+        .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.`),
 })
-    .refine((d) => d.action === "disease" || (d.ensemblId !== undefined && d.ensemblId.trim().length > 0), {
-    message: "ensemblId is required when action is 'target' or 'safety' — Open Targets accepts only Ensembl gene IDs (ENSG…), " +
+    .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…), " +
         "never gene symbols. Resolve the symbol to an ENSG id with search_gene, then retry.",
     path: ["ensemblId"],
 })
@@ -53,37 +54,25 @@ const inputSchema = z
 });
 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, and 'safety' adds the mechanism-based liabilities. See the " +
-        "action parameter for what each mode needs and returns.\n" +
-        "IDENTIFIERS ONLY: it accepts an Ensembl gene ID (action 'target'/'safety') 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); safety found: false " +
-        "means no Open Targets record for that Ensembl id (usually a wrong id); safety found: true with an empty safetyLiabilities " +
-        "array means no curated liability.",
+    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.",
     inputSchema,
     execute: async (input) => {
+        const limit = input.limit ?? DEFAULT_LIMIT;
         switch (input.action) {
             case "target": {
-                const targetInfo = await searchTargetAssociations(input.ensemblId, input.limit);
+                const targetInfo = await searchTargetAssociations(input.ensemblId, limit);
                 return ok({ targetInfo, associations: targetInfo?.associations ?? [] });
             }
             case "disease": {
-                const associations = await searchDiseaseAssociations(input.efoId, input.limit);
+                const associations = await searchDiseaseAssociations(input.efoId, limit);
                 return ok({ associations });
             }
-            case "safety": {
-                const result = await getTargetSafetyLiabilities(input.ensemblId);
-                // "Target not found" is an expected outcome — a data variant, not an error.
-                if (!result)
-                    return ok({ found: false, ensemblId: input.ensemblId });
-                return ok({
-                    found: true,
-                    targetSymbol: result.targetSymbol,
-                    safetyLiabilities: result.safetyLiabilities,
-                });
-            }
         }
     },
 });

package/dist/tools/bio/pubchem.js

@@ -44,14 +44,16 @@ const inputSchema = z
     activeOnly: z
         .boolean()
         .optional()
-        .describe("Action 'assays' only. Default false (all outcomes). Set true to keep only rows whose activityOutcome is 'Active'."),
+        .describe("Action 'assays' only. Default TRUE — only rows whose activityOutcome is 'Active'. A widely screened compound has thousands of " +
+        "inactive rows and they answer nothing on their own; set false only when a LOW hit rate is the finding you are after (selectivity, " +
+        "or confirming a compound was tested and came back clean)."),
     limit: z
         .number()
         .int()
         .min(1)
         .max(500)
         .optional()
-        .describe("Action 'assays' only. Max assay records to return (default 50, max 500). Applied after the activeOnly filter."),
+        .describe("Action 'assays' only. Max assay records to return (default 25, max 500). Applied after the activeOnly filter."),
 })
     .refine((d) => d.action !== "compound" || (d.query !== undefined && d.query.trim().length > 0), {
     message: "query is required when action is 'compound' — the identifier to resolve (a name, SMILES, InChI, InChIKey, or CID)",
@@ -83,8 +85,8 @@ export const pubchemTool = defineTool({
             case "assays":
                 return ok({
                     assays: await fetchPubchemAssays(input.cid, {
-                        activeOnly: input.activeOnly ?? false,
-                        limit: input.limit ?? 50,
+                        activeOnly: input.activeOnly ?? true,
+                        limit: input.limit ?? 25,
                     }),
                 });
         }

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

@@ -16,24 +16,28 @@
  * turns PMIDs into abstracts + the PMC id, fulltext turns a PMC id into the
  * article body — which is why they share a tool: the identifier for each step
  * is read off the previous step's result.
+ *
+ * Every step is bounded, because this is the tool most able to flood a context:
+ * an author list can run to hundreds of names, and one research article parses
+ * to 40–80k characters — more than the entire tool surface costs to attach.
+ * `details` trims the two unbounded list fields; `fulltext` admits whole
+ * sections up to a character budget and always returns the article's full
+ * section outline so a follow-up can name what it wants.
  */
-import type { ArticleSection } from "../lib/ncbi-utils.js";
-import { type ArticleDetail, type PubMedSummary } from "../lib/pubmed-client.js";
+import { type BoundedArticleDetail, type BoundedFullText, type PubMedSummary } from "../lib/pubmed-client.js";
 type PubMedOutput = {
     totalFound: number;
     results: PubMedSummary[];
 } | {
-    articles: ArticleDetail[];
+    articles: BoundedArticleDetail[];
     notFound: string[];
 } | {
     pmcId: string;
     available: false;
-} | {
+} | ({
     pmcId: string;
     available: true;
-    fullText: string;
-    sections: ArticleSection[];
-};
+} & BoundedFullText);
 export declare function createPubMedTool(deps: {
     ncbiApiKey?: string;
 }): import("../define-tool.js").Tool<{
@@ -46,6 +50,10 @@ export declare function createPubMedTool(deps: {
         to: string;
     } | undefined;
     pmids?: string[] | undefined;
+    maxAuthors?: number | undefined;
+    maxMeshTerms?: number | undefined;
     pmcId?: string | undefined;
+    sections?: string[] | undefined;
+    maxChars?: number | undefined;
 }, PubMedOutput>;
 export {};

package/dist/tools/bio/pubmed.js

@@ -16,27 +16,42 @@
  * turns PMIDs into abstracts + the PMC id, fulltext turns a PMC id into the
  * article body — which is why they share a tool: the identifier for each step
  * is read off the previous step's result.
+ *
+ * Every step is bounded, because this is the tool most able to flood a context:
+ * an author list can run to hundreds of names, and one research article parses
+ * to 40–80k characters — more than the entire tool surface costs to attach.
+ * `details` trims the two unbounded list fields; `fulltext` admits whole
+ * sections up to a character budget and always returns the article's full
+ * section outline so a follow-up can name what it wants.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
-import { getArticleDetails, getArticleFullText, searchPubmed } from "../lib/pubmed-client.js";
+import { boundArticleDetails, getArticleDetails, getArticleFullText, searchPubmed, } from "../lib/pubmed-client.js";
+const DEFAULTS = { searchResults: 10, maxAuthors: 5, maxMeshTerms: 10, maxChars: 12_000 };
 const inputSchema = z
     .object({
     action: z
         .enum(["search", "details", "fulltext"])
         .describe("'search' (needs query) — returns totalFound plus, per hit, PMID, title, journal, year and an author summary. " +
-        "'details' (needs pmids, max 20 per call) — each article's full abstract, authors, journal, year, DOI, MeSH terms, and " +
-        "pmcId (non-null only when open-access full text exists in PubMed Central). " +
-        "'fulltext' (needs pmcId, taken from a 'details' result) — the body of ONE open-access PMC article as plain text with " +
-        "section headers preserved; available: false when the article is not open-access."),
+        "'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. " +
+        "'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."),
     query: z
         .string()
         .optional()
         .describe("Required for action 'search'. PubMed query syntax — MeSH terms (\"breast neoplasms\"[MeSH]), field tags " +
         '([Title/Abstract], [Author], [Gene]), Boolean AND/OR/NOT. Example: "BRCA1"[Gene] AND "drug resistance"[Title/Abstract].'),
-    maxResults: z.number().int().min(1).max(50).default(10).optional().describe("action 'search': max results, 1–50 (default 10)."),
-    sort: z.enum(["relevance", "date"]).default("relevance").optional().describe("action 'search': sort order (default \"relevance\")."),
+    maxResults: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe(`action 'search': max results, 1–50 (default ${DEFAULTS.searchResults}). totalFound reports the true match count regardless.`),
+    sort: z.enum(["relevance", "date"]).optional().describe("action 'search': sort order (default \"relevance\")."),
     dateRange: z
         .object({
         from: z.string().describe("Start date in YYYY/MM/DD format"),
@@ -49,8 +64,36 @@ const inputSchema = z
         .min(1)
         .max(20)
         .optional()
-        .describe("Required for action 'details'. Non-empty array of PMID strings, max 20 — batch them, do not call once per PMID."),
+        .describe("Required for action 'details'. Non-empty array of PMID strings, max 20 — batch them, do not call once per PMID. Each article returns a " +
+        "FULL abstract, so 20 is a large result; pass the handful you actually intend to read."),
+    maxAuthors: z
+        .number()
+        .int()
+        .min(0)
+        .max(100)
+        .optional()
+        .describe(`action 'details': leading authors kept per article (default ${DEFAULTS.maxAuthors}, 0 for none); authorCount gives the true total.`),
+    maxMeshTerms: z
+        .number()
+        .int()
+        .min(0)
+        .max(100)
+        .optional()
+        .describe(`action 'details': MeSH terms kept per article (default ${DEFAULTS.maxMeshTerms}, 0 for none); meshTermCount gives the true total.`),
     pmcId: z.string().optional().describe("Required for action 'fulltext'. A PMC ID (e.g. \"PMC1234567\") copied from a 'details' result — not a PMID."),
+    sections: z
+        .array(z.string())
+        .optional()
+        .describe("action 'fulltext': case-insensitive substring filter on section headings, e.g. ['methods','results']. Omit first to get the outline, " +
+        "then name what you need — far cheaper than raising maxChars."),
+    maxChars: z
+        .number()
+        .int()
+        .min(500)
+        .max(200_000)
+        .optional()
+        .describe(`action 'fulltext': character budget across returned section bodies (default ${DEFAULTS.maxChars}). Sections are admitted whole, in ` +
+        "document order, until the budget would be exceeded."),
 })
     .refine((d) => d.action !== "search" || (d.query !== undefined && d.query.trim().length > 0), {
     message: "query is required when action is 'search'",
@@ -63,6 +106,14 @@ const inputSchema = z
     .refine((d) => d.action !== "fulltext" || (d.pmcId !== undefined && d.pmcId.trim().length > 0), {
     message: "pmcId is required when action is 'fulltext' — copy it from the pmcId field of a 'details' result; a PMID is not a PMC ID",
     path: ["pmcId"],
+})
+    .refine((d) => d.action === "fulltext" || (d.sections === undefined && d.maxChars === undefined), {
+    message: "sections and maxChars apply to action 'fulltext' only",
+    path: ["action"],
+})
+    .refine((d) => d.action === "details" || (d.maxAuthors === undefined && d.maxMeshTerms === undefined), {
+    message: "maxAuthors and maxMeshTerms apply to action 'details' only",
+    path: ["action"],
 });
 export function createPubMedTool(deps) {
     return defineTool({
@@ -70,29 +121,37 @@ export function createPubMedTool(deps) {
         description: "Search and read the biomedical literature via PubMed / PubMed Central (NCBI E-utilities). The three actions form a chain " +
             "— search, then details on the relevant hits, then fulltext; see the action parameter for what each needs and returns. Read " +
             "fulltext sparingly — only where the 'details' abstract is not enough, and only for articles that have a pmcId (open-access). " +
+            "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.",
         inputSchema,
         execute: async (input) => {
             switch (input.action) {
                 case "search":
                     return ok(await searchPubmed(deps.ncbiApiKey, input.query, {
-                        maxResults: input.maxResults,
-                        sort: input.sort,
-                        dateRange: input.dateRange,
+                        maxResults: input.maxResults ?? DEFAULTS.searchResults,
+                        ...(input.sort ? { sort: input.sort } : {}),
+                        ...(input.dateRange ? { dateRange: input.dateRange } : {}),
                     }));
-                case "details":
-                    return ok(await getArticleDetails(deps.ncbiApiKey, input.pmids));
+                case "details": {
+                    const { articles, notFound } = await getArticleDetails(deps.ncbiApiKey, input.pmids);
+                    return ok({
+                        articles: boundArticleDetails(articles, {
+                            maxAuthors: input.maxAuthors ?? DEFAULTS.maxAuthors,
+                            maxMeshTerms: input.maxMeshTerms ?? DEFAULTS.maxMeshTerms,
+                        }),
+                        notFound,
+                    });
+                }
                 case "fulltext": {
-                    const parsed = await getArticleFullText(deps.ncbiApiKey, input.pmcId);
+                    const parsed = await getArticleFullText(deps.ncbiApiKey, input.pmcId, {
+                        ...(input.sections ? { sections: input.sections } : {}),
+                        maxChars: input.maxChars ?? DEFAULTS.maxChars,
+                    });
                     // "Not open-access" is an expected outcome — a data variant, not an error.
                     if (!parsed)
                         return ok({ pmcId: input.pmcId, available: false });
-                    return ok({
-                        pmcId: input.pmcId,
-                        available: true,
-                        fullText: parsed.fullText,
-                        sections: parsed.sections,
-                    });
+                    return ok({ pmcId: input.pmcId, available: true, ...parsed });
                 }
             }
         },

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

@@ -4,9 +4,28 @@
 export declare const searchClinicalTrialsTool: import("../define-tool.js").Tool<{
     query: string;
     limit: number;
+    includeSummaries: boolean;
     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[];
+    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;
+    }[];
 }>;

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

@@ -5,11 +5,13 @@ import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { 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, brief summary, and whyStopped " +
-        "(the termination reason, when there is one). " +
+        "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.",
@@ -23,10 +25,29 @@ export const searchClinicalTrialsTool = defineTool({
             .enum(["RECRUITING", "ACTIVE_NOT_RECRUITING", "COMPLETED", "NOT_YET_RECRUITING"])
             .optional()
             .describe("Optional recruitment-status filter. Omit for all statuses — note TERMINATED/WITHDRAWN trials are not selectable here and appear only in an unfiltered search."),
-        limit: z.number().int().min(1).max(50).default(20).describe("Max trials to return (default 20, max 50)."),
+        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."),
+        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."),
     }),
-    execute: async ({ query, phase, status, limit = 20 }) => {
+    execute: async ({ query, phase, status, limit = 10, includeSummaries = false }) => {
         const result = await searchTrials(query, { phase, status, limit });
-        return ok({ totalFound: result.totalFound, trials: result.trials });
+        const trials = includeSummaries
+            ? result.trials
+            : result.trials.map(({ detailedDescription: _detailedDescription, ...trial }) => ({
+                ...trial,
+                briefSummary: trial.briefSummary === null ? null : trial.briefSummary.slice(0, SUMMARY_PREVIEW_CHARS),
+                summaryTruncated: (trial.briefSummary?.length ?? 0) > SUMMARY_PREVIEW_CHARS,
+            }));
+        return ok({ totalFound: result.totalFound, trials });
     },
 });

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

@@ -10,14 +10,20 @@ export const searchFaersTool = defineTool({
     description: "Search FDA FAERS for post-market adverse-event reports on one marketed drug — the real-world safety signal for a specific molecule. " +
         "Returns totalReports and adverseEvents[]: { reaction (MedDRA preferred term), count }, most-reported first. " +
         "These are spontaneous report counts, NOT incidence rates: there is no denominator and reporting is heavily biased, so use them to rank signals, never to state a rate. " +
-        "Matching is on the openFDA GENERIC name only — 'imatinib' works, the brand name 'Gleevec' does not. For mechanism-based liabilities of a target (rather than a drug), use opentargets({action:\"safety\"}). " +
+        "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."),
-        limit: z.number().int().min(1).max(100).default(25).describe("Max distinct adverse-reaction terms to return (default 25, max 100)."),
+        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)."),
     }),
-    execute: async ({ drugName, limit = 25, serious = false }) => {
+    execute: async ({ drugName, limit = 15, serious = false }) => {
         const result = await getFaersByDrug(drugName, { limit, serious });
         return ok({
             totalReports: result.totalReports,

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

@@ -4,7 +4,6 @@
 export declare const searchGeneTool: import("../define-tool.js").Tool<{
     symbols: string[];
     species: string;
-    expand: boolean;
 }, {
     genes: import("../lib/ensembl-client.js").GeneInfo[];
     notFound: string[];

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

@@ -7,13 +7,12 @@ import { defineTool } from "../define-tool.js";
 import { lookupGenes } from "../lib/ensembl-client.js";
 export const searchGeneTool = defineTool({
     id: "search_gene",
-    description: "Look up gene information from Ensembl by gene symbol. " +
-        "Returns Ensembl IDs, genomic coordinates, biotype, and descriptions. " +
-        "Supports batch lookups of up to 200 symbols at once.",
+    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.",
     inputSchema: z.object({
         symbols: z.array(z.string()).min(1).max(200).describe("Gene symbols to look up (e.g. ['BRCA1', 'TP53'])"),
         species: z.string().default("homo_sapiens").describe("Species name (e.g. 'homo_sapiens', 'mus_musculus')"),
-        expand: z.boolean().default(false).describe("Include transcript/exon details in the response"),
     }),
-    execute: async ({ symbols, species, expand }) => ok(await lookupGenes(symbols, { species, expand })),
+    execute: async ({ symbols, species }) => ok(await lookupGenes(symbols, { species })),
 });

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

@@ -39,7 +39,7 @@ 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. " +
-        "Returns totalFound plus datasets[]: { accession (GSE…/GDS…), title, summary (truncated to 500 chars), platform, sampleCount, organism, pubmedIds }. " +
+        "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. " +
         "An empty datasets array is a valid 'nothing matched' — do not retry the identical query.",
@@ -55,9 +55,15 @@ export const searchGeoDatasetsTool = defineTool({
             .enum(["gds", "gse"])
             .default("gse")
             .describe("'gse' (default) — GEO Series: raw submitter-deposited studies, far more numerous. 'gds' — curated DataSets: fewer, but normalized and value-added."),
-        limit: z.number().int().min(1).max(50).default(15).describe("Max datasets to return (default 15, max 50)."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .default(10)
+            .describe("Max datasets to return (default 10, max 50). totalFound reports the true match count regardless."),
     }),
-    execute: async ({ query, organism, datasetType = "gse", limit = 15 }) => {
+    execute: async ({ query, organism, datasetType = "gse", limit = 10 }) => {
         let searchQuery = query;
         // Escape backslashes first, then quotes, so a `\` in the organism value
         // cannot smuggle an unescaped `"` past the escaping and break out of the
@@ -87,7 +93,7 @@ export const searchGeoDatasetsTool = defineTool({
             return {
                 accession: r.accession ?? r.gse ?? `GDS${id}`,
                 title: r.title ?? "",
-                summary: (r.summary ?? "").slice(0, 500),
+                summary: (r.summary ?? "").slice(0, 300),
                 platform: r.gpl ?? r.platform ?? null,
                 sampleCount: r.n_samples ? Number(r.n_samples) : null,
                 organism: r.taxon ?? null,

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

@@ -1,16 +1,20 @@
 /**
  * searchInteractions — query protein-protein interactions via STRING DB.
  */
-import { getEnrichment, getInteractionPartners } from "../lib/string-client.js";
+import { type StringEnrichment, type StringInteraction } from "../lib/string-client.js";
 type InteractionsOutput = {
-    enrichment: Awaited<ReturnType<typeof getEnrichment>>;
+    enrichment: StringEnrichment[];
+    totalTerms: number;
 } | {
-    interactions: Awaited<ReturnType<typeof getInteractionPartners>>;
+    interactions: StringInteraction[];
+} | {
+    interactions: StringInteraction[];
+    totalEdges: number;
 };
 export declare const searchInteractionsTool: import("../define-tool.js").Tool<{
     identifiers: string[];
     species: number;
-    action: "partners" | "network" | "enrichment";
+    action: "enrichment" | "partners" | "network";
     minScore: number;
     limit: number;
 }, InteractionsOutput>;

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

@@ -5,27 +5,43 @@ import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { getEnrichment, getInteractionNetwork, getInteractionPartners } from "../lib/string-client.js";
+const DEFAULT_LIMIT = 20;
 export const searchInteractionsTool = defineTool({
     id: "search_interactions",
-    description: "Query protein-protein interactions from STRING DB. " +
-        "Actions: 'partners' finds interaction partners for proteins, " +
-        "'network' gets the full interaction network between listed proteins, " +
-        "'enrichment' returns functional enrichment analysis (GO, KEGG, Reactome).",
+    description: "Query STRING DB for protein-protein 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 " +
+        "opposed to lookup_annotation, which just reads a vocabulary. " +
+        "`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) — do not retry.",
     inputSchema: z.object({
         identifiers: z.array(z.string()).min(1).max(100).describe("Protein/gene identifiers (e.g. ['TP53', 'BRCA1'])"),
         species: z.number().int().default(9606).describe("NCBI Taxonomy ID (9606 = human, 10090 = mouse)"),
         action: z.enum(["partners", "network", "enrichment"]).default("partners").describe("Query type"),
-        minScore: z.number().int().min(0).max(1000).default(400).describe("Minimum confidence score (400=medium, 700=high, 900=highest)"),
-        limit: z.number().int().min(1).max(100).default(20).describe("Max interaction partners (partners action only)"),
+        minScore: z
+            .number()
+            .int()
+            .min(0)
+            .max(1000)
+            .default(400)
+            .describe("Minimum confidence score, 'partners' and 'network' only (400=medium, 700=high, 900=highest). Raise it to cut a large network down."),
+        limit: z
+            .number()
+            .int()
+            .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). ` +
+            "Rows are ordered best-first (score descending for interactions, FDR ascending for enrichment), so the default keeps the strongest."),
     }),
     execute: async ({ identifiers, species, action, minScore, limit }) => {
         if (action === "enrichment") {
-            const enrichment = await getEnrichment(identifiers, species);
-            return ok({ enrichment });
+            return ok(await getEnrichment(identifiers, species, { limit }));
         }
-        const interactions = action === "partners"
-            ? await getInteractionPartners(identifiers, { species, minScore, limit })
-            : await getInteractionNetwork(identifiers, { species, minScore });
-        return ok({ interactions });
+        if (action === "network") {
+            return ok(await getInteractionNetwork(identifiers, { species, minScore, limit }));
+        }
+        return ok({ interactions: await getInteractionPartners(identifiers, { species, minScore, limit }) });
     },
 });