@inflexa-ai/harness 0.41.0 → 0.41.1

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')."),

package/dist/tools/research/generate-analogy-report.js

@@ -39,7 +39,7 @@ function createSubmitAnalogyReportTool(cell) {
             "relations, and key terms of phase 1, and each analogy with its " +
             "coverage and its cited solutions from phase 2. Call it one time with " +
             "the full report. If it rejects the report, correct the fields that it " +
-            "names and call it again. Stop immediately after an accepted call.",
+            "names and call it again. An accepted call ends the run.",
         inputSchema: AnalogyReportSchema,
         describeCall: "none",
         execute: async (report) => {
@@ -47,7 +47,7 @@ function createSubmitAnalogyReportTool(cell) {
             cell.outcome = { kind: "report", report };
             return ok({
                 recorded: true,
-                message: "Report recorded. You are done — stop now and do not take further actions.",
+                message: "Report recorded.",
             });
         },
     });
@@ -135,25 +135,25 @@ export function createGenerateAnalogyReportTool(deps) {
         description: "Idea-generation engine. Extracts structural analogies for an open-ended " +
             "scientific problem and returns real, cited solutions from other fields " +
             "(control theory, ML, ecology, logistics, economics…).\n" +
-            "WHEN: any exploratory or hypothesis-generation turn — 'what could we do " +
-            "about X', 'what should we try', 'how could we approach this', 'we're " +
-            "stuck', 'brainstorm ideas', 'are there precedents outside biology'. The " +
-            "trigger is exploratory INTENT, not the words 'analogy' or 'cross-domain' " +
-            "— users rarely name it, so infer it and reach for the tool proactively.\n" +
+            "WHEN: an exploratory or hypothesis-generation turn — the user asks how " +
+            "to approach a problem, what to try, or whether precedents exist outside " +
+            "biology. The intent decides, whether or not the user names analogy or " +
+            "cross-domain search.\n" +
             "NOT for: in-domain literature review (use `pubmed` and the other " +
             "bio-lookup tools), single-gene factual lookup (use `search_gene`), or " +
             "execution-mode turns where the user just wants the next step done. It " +
-            "drives a multi-step research sub-agent over live literature search, so " +
-            "it is slow — never spend it on a fact you could look up.\n" +
+            "drives a multi-step research sub-agent (up to 40 model turns) over live " +
+            "literature search, so it is slow; a fact that one lookup answers does " +
+            "not need it.\n" +
             "RETURNS an AnalogyReport envelope the UI renders as an inline card. An " +
             "analogy the search could not fill carries a `coverage` tag " +
             "(`queried_no_data` | `search_failed` | `not_loaded`) with an empty " +
-            "`solutions` array — informational, NOT an error. A top-level `error` " +
-            "field means no report was produced: on `error.kind === " +
-            '"extraction-failed"` do NOT retry with the same or a similar problem ' +
-            "statement (the wrapper already salvaged the run one time — you would " +
-            "burn latency on the same failure). Surface the message and ask the " +
-            "user to narrow the problem.",
+            "`solutions` array — a partial result, not an error. A top-level `error` " +
+            'field with `kind: "extraction-failed"` means no report was produced: the ' +
+            "sub-agent found the problem empty or incoherent, failed, or ended with " +
+            "no report after one corrective request. `error.message` gives the cause. " +
+            "A retry with the same or a similar problem statement meets the same " +
+            "failure, thus surface the message and ask the user to narrow the problem.",
         inputSchema: generateAnalogyReportInputSchema,
         describeCall: "none",
         execute: async (input, ctx) => {

package/dist/tools/research/generate-plan.js

@@ -340,7 +340,8 @@ function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger
     const submitPlanTool = defineTool({
         id: "submit_plan",
         description: "Submit the final plan for persistence. Re-validates the plan; on " +
-            "success returns {accepted: true, planId} — STOP after this. On " +
+            "success returns {accepted: true, planId}, and an accepted call ends " +
+            "the planning session. On " +
             "rejection returns {accepted: false, issues} — fix and call again, " +
             "or switch to report_blocker if the plan cannot be made valid. This " +
             "arg schema is the authoritative plan contract.",
@@ -421,11 +422,12 @@ function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger
     const requestClarificationTool = defineTool({
         id: "request_clarification",
         description: "Terminal. Use when a specific fact you need is missing from the " +
-            "input and cannot be inferred. Pass a short question and optional " +
-            "context. Stop after calling.",
+            "input and cannot be inferred. The question reaches the user through " +
+            "the conversation agent. A call ends the planning session with no " +
+            "plan saved.",
         inputSchema: z.object({
-            question: z.string().min(1),
-            questionContext: z.string().optional(),
+            question: z.string().min(1).describe("One short question that names each missing fact, and the step that needs it."),
+            questionContext: z.string().optional().describe("Optional context: why the plan needs the fact, and what the inputs already say about it."),
         }),
         describeCall: "none",
         execute: async (input) => {
@@ -698,8 +700,11 @@ export function createGeneratePlanTool(deps) {
             "to the planner directly. Do NOT summarize or re-type them into this call; you cannot restate that " +
             "record more faithfully than the record itself. Pass only what the profile cannot hold: the research " +
             "question, facts the user told you (analystNotes), prior run results, and their constraints. " +
-            "Returns a structured plan ready for show_plan and execute_analysis plan mode, or a clarification question if " +
-            "the planner is missing something it cannot infer.",
+            "The planner is a multi-step sub-agent, thus a call can take many minutes. " +
+            "The result carries an `event`: `plan_complete` with {planId, plan} — the plan is saved and ready for show_plan and " +
+            "execute_analysis plan mode, and this call neither shows nor runs it; `clarification_needed` with {question, questionContext?} " +
+            "when the planner is missing a fact it cannot infer; or `error` with {error} when no plan was saved (the planner reported " +
+            "a blocker, the save failed, the call timed out or was cancelled, or parentPlanId is not a plan of this analysis).",
         inputSchema: z.object({
             researchQuestion: z.string().describe("What the user wants to analyze — their goal and specific questions."),
             analystNotes: z

package/dist/tools/research/inspect-data-profile.js

@@ -93,13 +93,14 @@ const FAILURE_SCOPE_NOTE = "This records an earlier attempt; this row cannot est
 export function createInspectDataProfileTool(pool) {
     return defineTool({
         id: "inspect_data_profile",
-        description: "Read this analysis's data profile — the AUTHORITATIVE record of what the input dataset is: " +
+        description: "Read this analysis's data profile — the authoritative record of what the input dataset is: " +
             "organism and taxon id, scientific domain and subtype, tissue, cell type, condition, experimental design, " +
-            "dataset-wide caveats, public accessions, the GROUPS of file the dataset is made of, the DIMENSIONS that vary " +
+            "dataset-wide caveats, public accessions, the groups of files the dataset is made of, the dimensions that vary " +
             "across it with the evidence behind each, and the file census (kept, unclassified, quarantined). " +
-            "There is NO data-profile file in the workspace — this tool is the only way to read it. Do not search for one, " +
+            "There is no data-profile file in the workspace — this tool is the only way to read it. Do not search for one, " +
             "and do not rediscover these facts by listing or reading the raw input files. " +
-            "Call it before you reason about the data (planning, writing analysis code, interpreting results). " +
+            "Call it when a question about the data (for planning, analysis code, or interpretation) is not answered by what " +
+            "you already hold; a step briefing already carries a projection of this profile. " +
             "scope:'overview' (the default) returns the dataset-level orientation plus the partition accounting — how many " +
             "files were kept, how many landed in no group, how many were quarantined — and how many members are described " +
             "individually. That last figure and the dataset's file count differ on purpose: a large dataset is described by " +
@@ -110,10 +111,11 @@ export function createInspectDataProfileTool(pool) {
             "scope:'files' returns the individually annotated members, paged: page (1-based, default 1) and pageSize (default 20, max 100), " +
             "always with the true total and hasMore, so you can see exactly what you have not read yet. " +
             "For the paths of files no record describes, use scope:'groups' for the structure and list the workspace tree for the paths. " +
+            "The file paths of scope:'files' and the display patterns of scope:'groups' are rooted at /{analysisId}/, thus they resolve from any working directory. " +
             "The state field says what you got: 'ready'; 'stale' (a profile is returned but may not describe the current " +
             "inputs — staleReason says why); 'pending' (profiling is still running); 'failed'; or 'absent' (never profiled, " +
             "or the analysis has no input files). " +
-            "A 'failed' state reports a PAST attempt, with failedAt naming when it was recorded — it is not a verdict on the " +
+            "A 'failed' state reports a past attempt, with failedAt naming when it was recorded — it is not a verdict on the " +
             "input files you are holding now, and this tool cannot tell you whether that attempt covered them. Compare failedAt " +
             "against when the input set last changed before you conclude anything: if the data moved since, say the profile " +
             "needs re-running rather than diagnosing the data itself.",

package/dist/tools/research/inspect-run.js

@@ -97,9 +97,13 @@ const inputSchema = z
 export function createInspectRunTool(pool, clock = systemClock) {
     return defineTool({
         id: "inspect_run",
-        description: "Inspect workflow runs for this analysis. Without a runId, returns an active-first paged list (running, suspended, then terminal history). " +
-            "With a runId, returns an explicit inspectionState and advertises output paths only after the run is terminal. " +
+        description: "Inspect workflow runs for this analysis. A run never posts its completion into the conversation; this tool is how you read it. " +
+            "Without a runId, returns an active-first paged list (running, suspended, then terminal history) with total and hasMore. " +
+            "With a runId, returns the run, its steps, and an inspectionState: not_found; in_progress; suspended (the run does not progress until it is resumed); " +
+            "or terminal (run.status completed, partial, failed, or canceled). " +
+            "Output paths appear only on a terminal run: run.synthesisPath when synthesisStatus is produced, and the summaryPath of each step that ran. " +
             "For a user-directed check, waitForTerminalSeconds can wait once for 1-30 seconds; if the cutoff returns in_progress, stop polling for that turn. " +
+            "A wait on the run that the caller itself runs inside returns at once with selfWaitPrevented. " +
             "Default response is lightweight — pass includeDiagnostics:true to add error/duration/retry telemetry.",
         inputSchema,
         // The two calls do different work: one inspects a named run, the other

package/dist/tools/research/literature-reviewer.js

@@ -58,12 +58,17 @@ export function createLiteratureReviewerTool(deps) {
     };
     return defineTool({
         id: "literature_reviewer",
-        description: "Delegate batch literature/biology research: looking up multiple " +
-            "genes or pathways, validating findings against published knowledge, " +
-            "or building evidence profiles. Pass a self-contained brief — the " +
-            "reviewer has no access to this conversation. Returns a structured " +
-            "evidence report. Do NOT delegate simple single-gene lookups; handle " +
-            "those directly with your own bio-lookup tools.",
+        description: "Delegate batch literature/biology research to a sub-agent: looking up " +
+            "multiple genes or pathways, validating findings against published " +
+            "knowledge, or building evidence profiles. The reviewer holds gene, " +
+            "protein, annotation, interaction, PubMed, citation-verification, " +
+            "drug-gene and preclinical-profile lookups. It cannot see this " +
+            "conversation, the workspace, or the analysis files, thus pass a " +
+            "self-contained brief. One call runs a multi-step research loop of up " +
+            "to 30 model turns. Returns {report}: a Markdown evidence report with " +
+            "an evidence summary per target, cross-target patterns, and key " +
+            "references with PMIDs. A run that ends with no report returns a " +
+            "retryable error that names the finish reason.",
         inputSchema: z.object({
             brief: z
                 .string()

package/dist/tools/research/search-arxiv.js

@@ -20,7 +20,8 @@ export const searchArxivTool = defineTool({
         categories: z
             .array(z.string())
             .optional()
-            .describe('Optional arXiv category filters (e.g., ["cs.LG", "math.OC"]). ' + "Combined with the query using AND."),
+            .describe('Optional arXiv category filters (e.g., ["cs.LG", "math.OC"]). A paper matches when it carries any one of them, ' +
+            "and that filter is combined with the query using AND."),
         limit: z.number().int().min(1).max(20).default(10).describe("Maximum results (1–20, default 10)."),
     }),
     describeCall: "none",

package/dist/tools/research/search-github-repos.js

@@ -54,10 +54,16 @@ export function createSearchGithubReposTool(deps) {
     return defineTool({
         id: "search_github_repos",
         description: "Search GitHub for code repositories matching a free-text query, " +
-            "optionally filtered by programming language. Returns URL, full " +
+            "optionally filtered by programming language. Results are sorted by " +
+            "star count, highest first, not by relevance. Returns URL, full " +
             "name (owner/repo), description, star count, primary language, " +
-            "and last-updated timestamp. Use to find implementations of " +
-            "cross-domain methods cited in analogical-reasoning results.",
+            "and last-updated timestamp; description and language are absent " +
+            "when GitHub holds none. Use to find a published implementation of " +
+            "a method or a pipeline.\n" +
+            "ABSENCE IS NORMAL: an empty repos array means no repository matched, " +
+            "and `success: false` with an `error` string means GitHub could not be " +
+            "reached or refused the request (the low unauthenticated rate limit " +
+            "lands here). Report either one and continue, do not retry unchanged.",
         inputSchema: z.object({
             query: z
                 .string()

package/dist/tools/sandbox/list-available-refs.js

@@ -61,7 +61,7 @@ const ListAvailableRefsInputSchema = z.object({
         .string()
         .max(MAX_INPUT_PATH_BYTES)
         .optional()
-        .describe('Shorthand for a top-level group to inspect (e.g. "atlas_singlecell", "msigdb"); the groups present come back in `categories`. Ignored when `path` is given.'),
+        .describe("The name of a top-level directory of the store to inspect, the same as `path` with one segment. A label in `categories` that is not a directory reads as `not_found`; pass such a label as `query`. Ignored when `path` is given."),
     query: z
         .string()
         .optional()
@@ -512,7 +512,8 @@ export function createListAvailableRefsTool(deps) {
             "Results are ALWAYS bounded — prefer a targeted query over a full dump: " +
             '`query` is the main entry point, a case-insensitive substring filter over each entry\'s path and its dataset/title/category/organism/format/contents labels (e.g. "regulon", "hallmark", "mouse"); ' +
             "`path` inspects one directory beneath /mnt/refs (a returned path, or store-relative) — drill in with it when a listing is truncated; " +
-            '`category` is shorthand for a top-level group (e.g. "pathways", "regulatory-networks"), and the groups present come back in `categories`; ' +
+            '`categories` in the response lists the top-level directory names and the dataset group labels (for example "pathways") present; ' +
+            "pass a group label as `query`, because `category` inspects a top-level directory by name and a label that is not a directory reads as `not_found`; " +
             "`limit` caps the entries returned. The response carries `returned`, `total`, and `hasMore`, so truncation is never silent. " +
             "An empty result means the dataset is absent right now — not that it is unobtainable. Say so; never guess a path, and never silently substitute a different dataset. " +
             "The store is provisioned by the host and is NOT frozen: datasets can be added through the host's own provisioning path, and whatever is added shows up on a later call.",

package/dist/tools/sandbox/report-blocker.js

@@ -28,7 +28,12 @@ export function createBlockerHolder() {
     return { outcome: null };
 }
 /** The one input every `report_blocker` takes, wherever it is offered. */
-const ReportBlockerInputSchema = z.object({ reason: z.string().min(1) });
+const ReportBlockerInputSchema = z.object({
+    reason: z
+        .string()
+        .min(1)
+        .describe("What blocks the work, stated as a fact: the missing or unreadable input, or the capability that is not available, and what you tried."),
+});
 /**
  * Build the `report_blocker` tool for one loop. The id, the input schema and
  * the terminal contract ("pass a reason, then stop") are fixed here; the call