@inflexa-ai/harness 0.13.0 → 0.14.1

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

@@ -0,0 +1,173 @@
+/**
+ * lookupAnnotation — one tool over the functional-annotation vocabularies:
+ * Gene Ontology (QuickGO) and the pathway databases (KEGG, Reactome).
+ *
+ * These were two tools asking one question — "what is this gene or term known
+ * to do?" — against different vocabularies. `search_pathway` already treated
+ * the corpus as a parameter (`source: kegg | reactome | both`) rather than a
+ * tool boundary; this extends the same shape to GO.
+ *
+ * The input is a flat object with a `vocabulary` discriminator — not a
+ * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs
+ * a top-level `"type":"object"`). Per-vocabulary parameters are optional in the
+ * schema and made conditionally required by `.refine`, so a malformed call
+ * fails at the loop boundary naming the missing field instead of reaching an
+ * API request that cannot be built.
+ */
+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";
+const QUICKGO_BASE = "https://www.ebi.ac.uk/QuickGO/services";
+const HEADERS = { Accept: "application/json" };
+const DEFAULT_LIMIT = 10;
+// QuickGO term response, validated at the fetch boundary. The `.transform`
+// carries the (context-free) rename from the raw wire fields to the `GoTerm[]`
+// we return, so parsing IS both the validation and the normalization — there
+// is no separate raw interface or mapper to keep in sync.
+const GoTermResponseSchema = z
+    .object({
+    results: z
+        .array(z.object({
+        id: z.string().optional(),
+        name: z.string().optional(),
+        definition: z.object({ text: z.string().optional() }).nullable().optional(),
+        aspect: z.string().optional(),
+    }))
+        .optional(),
+})
+    .transform((res) => (res.results ?? []).map((t) => ({
+    id: t.id ?? "",
+    name: t.name ?? "",
+    definition: t.definition?.text ?? undefined,
+    aspect: t.aspect ?? undefined,
+})));
+const GoAnnotationResponseSchema = z
+    .object({
+    results: z
+        .array(z.object({
+        geneProductId: z.string().optional(),
+        goId: z.string().optional(),
+        goName: z.string().optional(),
+        goAspect: z.string().optional(),
+        goEvidence: z.string().optional(),
+        qualifier: z.string().optional(),
+    }))
+        .optional(),
+})
+    .transform((res) => (res.results ?? []).map((a) => ({
+    geneProductId: a.geneProductId ?? "",
+    goId: a.goId ?? "",
+    goName: a.goName ?? "",
+    aspect: a.goAspect ?? undefined,
+    evidenceCode: a.goEvidence ?? undefined,
+    qualifier: a.qualifier ?? undefined,
+})));
+const inputSchema = z
+    .object({
+    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 }. " +
+        "'kegg' / 'reactome' — one pathway database; needs query. 'pathways' — both, in parallel; needs query. " +
+        "Returns pathways[] { id, name, source, url, 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."),
+    goId: z
+        .string()
+        .regex(/^GO:\d{7}$/)
+        .optional()
+        .describe("'go' only. A specific GO term ID, e.g. 'GO:0008150'."),
+    geneProductId: z.string().min(1).optional().describe("'go' only. A UniProt accession, e.g. 'P04637', for that protein's GO annotations."),
+    taxonId: z.number().int().optional().describe("'go' only, with geneProductId. NCBI Taxon ID filter (9606 = human, 10090 = mouse)."),
+    organism: z.string().optional().describe("Pathway vocabularies only. KEGG organism code — 'hsa' (human, default), 'mmu' (mouse); mapped for Reactome."),
+    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."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .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",
+    path: ["query"],
+})
+    .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)",
+    path: ["goId"],
+})
+    .refine((d) => d.vocabulary === "go" || (d.goId === undefined && d.geneProductId === undefined && d.taxonId === undefined), {
+    message: "goId, geneProductId and taxonId belong to vocabulary 'go' — the pathway vocabularies take query + organism",
+    path: ["vocabulary"],
+})
+    .refine((d) => d.vocabulary !== "go" || (d.organism === undefined && d.includeGenes === undefined), {
+    message: "organism and includeGenes belong to the pathway vocabularies — vocabulary 'go' filters annotations with taxonId instead",
+    path: ["vocabulary"],
+});
+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" +
+        "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.",
+    inputSchema,
+    execute: async ({ vocabulary, query, goId, geneProductId, taxonId, organism, includeGenes, limit }) => {
+        const cap = limit ?? DEFAULT_LIMIT;
+        if (vocabulary !== "go") {
+            const pathways = await searchPathways(query, {
+                source: vocabulary === "pathways" ? "both" : vocabulary,
+                organism: organism ?? "hsa",
+                includeGenes: includeGenes ?? false,
+                maxResults: cap,
+            });
+            return ok({ pathways });
+        }
+        const tasks = [];
+        let terms;
+        let annotations;
+        if (goId) {
+            tasks.push((async () => {
+                const res = await apiFetchValidated(`${QUICKGO_BASE}/ontology/go/terms/${encodeURIComponent(goId)}`, GoTermResponseSchema, {
+                    headers: HEADERS,
+                });
+                if (res.isErr())
+                    throw new Error(`GO lookup: ${describeApiError(res.error)}`);
+                terms = res.value;
+            })());
+        }
+        if (query) {
+            tasks.push((async () => {
+                const params = new URLSearchParams({ query, limit: String(cap) });
+                const res = await apiFetchValidated(`${QUICKGO_BASE}/ontology/go/search?${params}`, GoTermResponseSchema, { headers: HEADERS });
+                if (res.isErr())
+                    throw new Error(`GO search: ${describeApiError(res.error)}`);
+                const searchTerms = res.value;
+                terms = terms ? [...terms, ...searchTerms] : searchTerms;
+            })());
+        }
+        if (geneProductId) {
+            tasks.push((async () => {
+                const params = new URLSearchParams({ geneProductId, limit: String(cap) });
+                if (taxonId)
+                    params.set("taxonId", String(taxonId));
+                const res = await apiFetchValidated(`${QUICKGO_BASE}/annotation/search?${params}`, GoAnnotationResponseSchema, { headers: HEADERS });
+                if (res.isErr())
+                    throw new Error(`Annotations: ${describeApiError(res.error)}`);
+                annotations = res.value;
+            })());
+        }
+        await Promise.all(tasks);
+        return ok({ terms, annotations });
+    },
+});

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 });
     },
 });