formlab-mcp 0.6.22 → 0.6.24

package/README.md

@@ -29,7 +29,7 @@ Ask Claude (or another MCP client) things like:
 | Tool | Purpose |
 |---|---|
 | `list_formulations` | Filtered list of recipes |
-| `get_formulation` | Full record + flattened wt-% composition (sub-formulas expanded), the ordered **step procedure**, user **custom fields**, and any **process-factor values** (DOE inputs — cure temp, mix time, RPM, pH…) |
+| `get_formulation` | Full record + flattened wt-% composition (sub-formulas expanded), the ordered **step procedure**, user **custom fields**, any **process-factor values** (DOE inputs — cure temp, mix time, RPM, pH…), and the declared **finishedDensity** (g/mL of the mixed product; volume-targeted batches scale by it) |
 | `find_similar_formulations` | Find formulas using a given ingredient ≥ threshold % |
 | `compare_formulations` | Pairwise side-by-side composition diff |
 | `list_ingredients` | Filtered list of raw materials. Filters: `family`, `supplier`, `name_contains`, `in_stock_only`, `ingredient_class` (small-molecule / surfactant / polymer / extract / fragrance / pigment / sequence / mixture), `sequence_contains` (e.g. `KTTKS` → Matrixyl), `taxon_contains` (e.g. `Centella`) |
@@ -39,7 +39,7 @@ Ask Claude (or another MCP client) things like:
 | `get_supplier` | One supplier in full: record, every ingredient it's an approved source for, every lot from it, and the **recall trace** (batches that consumed those lots → products, shipments, samples, sub-batches; lots on hold flagged) |
 | `list_inventory` | Portfolio stock rollup — one row per ingredient with on-hand qty, summed lot balance, nearest expiry, and a low-stock flag (on-hand ≤ `reorderThreshold`, or zero). Filters: `low_stock_only`, `expiring_within_days`, `family` |
 | `list_batches` | Filtered list of production / lab-prep events |
-| `get_batch` | Full record + actual composition, measured/derived **actual volume** (mass ÷ density, never a sum of per-ingredient volumes) and **actual mass** (yield, else summed inputs, else measured volume × density), the **process** method + any **process-factor values** (DOE inputs), samples + blend lineage, and — as a finished-goods lot — its storage **`location`** + finished-goods **`stockLedger`** (shipments out + adjustments; `shippedQty` total) |
+| `get_batch` | Full record + actual composition, measured/derived **actual volume** (mass ÷ density, never a sum of per-ingredient volumes) and **actual mass** (yield, else summed as-prepared inputs — mL rows through that ingredient's density — else measured volume × density), **estimatedVolume** (mass ÷ the formula's finished density when no actual exists, flagged `estimate: true`), **plannedMass** for volume-target batches (target × finished density) and **formulaFinishedDensity**, the **process** method + any **process-factor values** (DOE inputs), samples + blend lineage, and — as a finished-goods lot — its storage **`location`** + finished-goods **`stockLedger`** (shipments out + adjustments; `shippedQty` total) |
 | `list_samples` | Filtered list of physical specimens |
 | `get_sample` | Full record + canonical variant + test reports + blend lineage |
 | `list_test_results` | Filtered list of test reports (by sample, parameter, **measured-value range** (`value_min`/`value_max`), date, or lab) |
@@ -56,13 +56,13 @@ Ask Claude (or another MCP client) things like:
 | `get_doe_design` | One design in full: constraints in plain language, the model it was optimised for, generation settings (run budget, replicates, centre points, seed) and the complete run matrix with the formulation each run became |
 | `find_by_smarts` | SMARTS-pattern substructure search across every ingredient with a SMILES. Requires `@rdkit/rdkit` (optional dependency — install with `npm install @rdkit/rdkit` in `mcp/` if you get a "not installed" error). Examples: `c1ccccc1` (any aromatic 6-ring), `[OX2H1]` (any hydroxyl), `C(=O)O` (carboxylic acid), `[F,Cl,Br,I]` (any halogen). |
 | `list_equipment` | Filtered list of the Equipment registry (mixers, ovens, viscometers, balances…). Filters: `category`, `status`, `manufacturer`, `name_contains` |
-| `get_equipment` | Full equipment record + a summary of where it's used (panels, step presets, test methods, formulas, batches) |
+| `get_equipment` | Full equipment record + `usedIn` (panels, step presets, test methods, formula steps, batches, testReports resolved to it), `usage` (reports / formulas / batches / samples / pass rate / top formulas) and `measured` (per parameter: mean here vs mean on other instruments, biasPct) |
 | `list_test_methods` | Filtered list of Test Methods (the parameter library). Filter by `analyte` (the property measured, e.g. `Viscosity` — finds every method for it), `category`, `name_contains`, `include_retired` |
-| `get_test_method` | Full method definition (SOP / sample prep / equipment / calculation / acceptance spec) + sibling methods sharing its analyte |
+| `get_test_method` | One Test Method: full definition, run conditions, analyte siblings, using panels, plus `usage`, `valueSummary` (mean / sd / min / max) and `byInstrument` |
 | `list_step_presets` | Filtered list of Step Presets (reusable procedure steps: duration / temp / RPM / equipment). Filters: `industry`, `name_contains` |
 | `get_step_preset` | Full step-preset record incl. the multi-value equipment list (`{name, equipmentId}`) |
 | `list_test_panels` | Filtered list of Test Panels (reusable column-sets — the parameters measured together on a sample). Filters: `industry`, `name_contains` |
-| `get_test_panel` | Full panel record — ordered parameter list (each with resolved Test Method UID, unit, spec) + instruments |
+| `get_test_panel` | One Test Panel: ordered parameters with resolved method UIDs + specs, plus `usage` (reports created from it) and `performanceByParameter` |
 | `list_projects` | Filtered list of projects (the buckets formulations are filed under) + per-project formulation count. Filters: `status`, `name_contains` |
 | `get_project` | Full project record + the formulations filed under it |
 | `list_notebook_entries` | ELN feed — dated authored notes attached to records. Filters: `entity_type`, `entity_id`, `author`, `text_contains`, `since`, `until` |

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "formlab-mcp",
-  "version": "0.6.22",
+  "version": "0.6.24",
   "mcpName": "io.github.juliu1980/formlab-mcp",
-  "description": "Read-only Model Context Protocol server for FormLab — lets Claude (and other MCP clients) read and analyze your FormLab data, from a local export file OR your live cloud workspace.",
+  "description": "Read-only Model Context Protocol server for FormLab \u2014 lets Claude (and other MCP clients) read and analyze your FormLab data, from a local export file OR your live cloud workspace.",
   "type": "module",
   "bin": {
     "formlab-mcp": "./index.js"

package/tools/analytics.js

@@ -913,6 +913,7 @@ const get_stability = {
   },
 };
 
+export { _evalPassFail };
 export const tools = {
   list_test_results,
   get_test_result,

package/tools/formulations.js

@@ -23,6 +23,11 @@ function _trimFormulation(f) {
     owner: f.owner || '',
     regulatoryCategory: f.regulatoryCategory || '',
     shelfLifeMonths: f.shelfLifeMonths ?? null,
+    // Density of the MIXED product (g/mL), when declared — volume-targeted
+    // batches scale by it instead of the ideal-mix estimate. null = not set.
+    finishedDensity: (f.finishedDensity && isFinite(parseFloat(f.finishedDensity.value)))
+      ? { value: parseFloat(f.finishedDensity.value), temp: f.finishedDensity.temp ?? null, source: f.finishedDensity.source || 'manual', batchId: f.finishedDensity.batchId || null, date: f.finishedDensity.date || null }
+      : null,
     tags: f.tags || [],
     projectId: f.projectId || null,
     compositionRowCount: (f.composition || []).length,

package/tools/lab.js

@@ -25,16 +25,57 @@ function _batchUnitMassKg(b) {
   const v = parseFloat(b.unitMass.value);
   return (isFinite(v) && v > 0) ? _massToKg(v, b.unitMass.unit) : null;
 }
-function _batchActualMassKg(b) {
+// Ingredient density → kg/L (=== g/mL). Mirrors the app's _densityToKgPerL for
+// the units it accepts; unknown unit → treated as g/mL (the app's default).
+const _DENS_TO_KGL = { 'g/ml': 1, 'g/cm3': 1, 'g/cm³': 1, 'g/cc': 1, 'kg/l': 1, 'kg/m3': 0.001, 'kg/m³': 0.001, 'g/l': 0.001, 'lb/gal': 0.119826, 'lb/ft3': 0.0160185, 'lb/ft³': 0.0160185 };
+function _densKgPerL(v, u) { const d = parseFloat(v); if (!isFinite(d) || d <= 0) return null; const f = _DENS_TO_KGL[String(u || 'g/mL').trim().toLowerCase()]; return d * (f == null ? 1 : f); }
+// Density of ONE as-prepared row: the ingredient's own density, or a sub-
+// formula's declared finished density. null when unknown.
+function _rowDensityKgPerL(c, ingredientsById, formulationsById) {
+  if (c.ingredientId && ingredientsById) { const ing = ingredientsById.get(c.ingredientId); return ing ? _densKgPerL(ing.density, ing.densityUnit) : null; }
+  if (c.formulationId && formulationsById) { const sf = formulationsById.get(c.formulationId); return sf ? _formulaFinishedDensity(sf) : null; }
+  return null;
+}
+// The formula's DECLARED finished density (g/mL) — adopted from a measured
+// batch or entered from a spec. The app also has an ideal-mix estimate from
+// ingredient densities; MCP does not reproduce that (estimate) and returns
+// null instead, so a null here means "the app plans with an estimate".
+function _formulaFinishedDensity(f) {
+  const v = f && f.finishedDensity ? parseFloat(f.finishedDensity.value) : NaN;
+  return (isFinite(v) && v > 0) ? v : null;
+}
+function _finishedDensityInfo(f, batchesById) {
+  const v = _formulaFinishedDensity(f);
+  if (v == null) return null;
+  const fd = f.finishedDensity;
+  const src = (fd.batchId && batchesById) ? batchesById.get(fd.batchId) : null;
+  return { value: v, unit: 'g/mL', temp: fd.temp ?? null, source: fd.source || 'manual', fromBatch: src ? src.uid : null, date: fd.date || null };
+}
+// Σ as-prepared row masses in kg, each row through ITS OWN unit: g rows
+// directly, mL rows × that ingredient's density. Mirrors sumActualRowsMassKg
+// in the app (cost.js). Any volume row that can't resolve → null (never a
+// partial sum that silently drops the water).
+function _sumActualRowsKg(rows, ingredientsById, formulationsById) {
+  if (!Array.isArray(rows)) return null;
+  let kg = 0, n = 0;
+  for (const c of rows) {
+    if (!c || !(c.ingredientId || c.formulationId)) continue;
+    const a = parseFloat(c.amount); if (!isFinite(a)) continue;
+    const m = _massToKg(a, c.unit); if (m != null) { kg += m; n++; continue; }
+    const L = _volToL(a, c.unit);
+    if (L != null) { const d = _rowDensityKgPerL(c, ingredientsById, formulationsById); if (d == null) return null; kg += L * d; n++; }
+  }
+  return n ? kg : null;
+}
+function _batchActualMassKg(b, ingredientsById, formulationsById) {
   const y = parseFloat(b.actualYield);
   if (isFinite(y)) {
     const kg = _massToKg(y, b.unit); if (kg != null) return kg;
     const umk = _batchUnitMassKg(b); if (umk != null) return y * umk;   // count unit × per-unit mass
   }
   if (Array.isArray(b.actualComposition)) {
-    let t = 0, any = false;
-    for (const c of b.actualComposition) { const kg = _massToKg(parseFloat(c.amount), c.unit); if (kg != null) { t += kg; any = true; } }
-    if (any) return t;
+    const t = _sumActualRowsKg(b.actualComposition, ingredientsById, formulationsById);
+    if (t != null) return t;
   }
   // Volume-anchored batch (no weighed mass above): mass = measured volume ×
   // measured density (V·ρ — always valid; summing per-ingredient volumes is
@@ -49,25 +90,47 @@ function _batchActualMassKg(b) {
   }
   return null;
 }
-function _batchActualVolume(b) {
+function _batchActualVolume(b, ingredientsById, formulationsById) {
   const mv = parseFloat(b.measuredVolume);
   if (isFinite(mv) && mv > 0) { const L = _volToL(mv, b.measuredVolumeUnit || 'L'); if (L != null) return { liters: L, source: 'measured' }; }
-  const d = parseFloat(b.measuredDensity), m = _batchActualMassKg(b);
+  const d = parseFloat(b.measuredDensity), m = _batchActualMassKg(b, ingredientsById, formulationsById);
   if (isFinite(d) && d > 0 && m != null) return { liters: m / d, source: 'derived' };
   return null;
 }
 // Public shape for a batch's actual volume (or null). Includes the density used
 // (derived case) or implied by the measurement (measured case) for QC.
-function _actualVolumeInfo(b) {
-  const av = _batchActualVolume(b);
+function _actualVolumeInfo(b, ingredientsById, formulationsById) {
+  const av = _batchActualVolume(b, ingredientsById, formulationsById);
   if (!av) return null;
   const out = { liters: +av.liters.toFixed(4), unit: 'L', source: av.source };
   if (av.source === 'derived') { const d = parseFloat(b.measuredDensity); if (isFinite(d)) out.densityUsed = d; }
-  else { const m = _batchActualMassKg(b); if (m != null && av.liters > 0) out.impliedDensity = +(m / av.liters).toFixed(4); }
+  else { const m = _batchActualMassKg(b, ingredientsById, formulationsById); if (m != null && av.liters > 0) out.impliedDensity = +(m / av.liters).toFixed(4); }
   return out;
 }
+// ESTIMATED volume when a batch has no actual: mass (actual, else target) ÷ the
+// formula's declared finished density. Never from an ideal-mix estimate, never
+// an actual. Mirrors the app's _batchEstimatedVolume.
+function _estimatedVolumeInfo(b, f, ingredientsById, formulationsById, batchesById) {
+  if (!f || _batchActualVolume(b, ingredientsById, formulationsById)) return null;
+  const fd = _finishedDensityInfo(f, batchesById);
+  if (!fd) return null;
+  let kg = _batchActualMassKg(b, ingredientsById, formulationsById), basis = 'actual-mass';
+  if (kg == null) { const t = _massToKg(parseFloat(b.targetQuantity), b.unit); if (t != null) { kg = t; basis = 'target-mass'; } }
+  if (kg == null || !(kg > 0)) return null;
+  return { liters: +(kg / fd.value).toFixed(4), unit: 'L', basis, densityUsed: fd.value, densityFromBatch: fd.fromBatch, estimate: true };
+}
+// A VOLUME-target batch's planned mass = target volume × the formula's finished
+// density (what the weigh-out scales by). null density → the app used its
+// ideal-mix estimate; say so rather than reproduce it.
+function _plannedMassInfo(b, f, batchesById) {
+  const L = _volToL(parseFloat(b.targetQuantity), b.unit);
+  if (L == null || !(L > 0)) return null;
+  const fd = _finishedDensityInfo(f, batchesById);
+  if (!fd) return { kg: null, note: 'No finished density declared on the formula — the app scaled this volume target with an ideal-mix estimate from ingredient densities (volumes assumed additive).' };
+  return { kg: +(L * fd.value).toFixed(4), unit: 'kg', densityUsed: fd.value, densitySource: fd.source, densityFromBatch: fd.fromBatch, note: 'Each recipe row weighs out to its wt% of this mass; the balance (q.s.) row is filled to the volume mark, so pure-ingredient volumes do not sum to the target.' };
+}
 
-function _trimBatch(b, formulationsById) {
+function _trimBatch(b, formulationsById, ingredientsById, batchesById) {
   if (!b) return null;
   const f = b.formulationId ? formulationsById.get(b.formulationId) : null;
   return {
@@ -89,11 +152,20 @@ function _trimBatch(b, formulationsById) {
     densityTempC: (b.densityTemp != null && b.densityTemp !== '') ? b.densityTemp : null,
     measuredVolume: b.measuredVolume ?? null,
     measuredVolumeUnit: b.measuredVolumeUnit || '',
-    actualVolume: _actualVolumeInfo(b),
+    actualVolume: _actualVolumeInfo(b, ingredientsById, formulationsById),
+    // No actual volume → an ESTIMATE at the formula's declared finished density
+    // (actual mass, else target mass). `estimate: true`; never an actual.
+    estimatedVolume: _estimatedVolumeInfo(b, f, ingredientsById, formulationsById, batchesById),
     // Actual MASS in kg (the conserved, additive quantity). From actual yield
-    // (mass-unit batch), else summed weighed inputs, else measured volume ×
-    // measured density. null when none is determinable.
-    actualMass: (function () { const m = _batchActualMassKg(b); return (m != null && isFinite(m)) ? { kg: +m.toFixed(4), unit: 'kg' } : null; })(),
+    // (mass-unit batch), else summed as-prepared inputs — each row through its
+    // OWN unit (g directly, mL × that ingredient's density) — else measured
+    // volume × measured density. null when none is determinable.
+    actualMass: (function () { const m = _batchActualMassKg(b, ingredientsById, formulationsById); return (m != null && isFinite(m)) ? { kg: +m.toFixed(4), unit: 'kg' } : null; })(),
+    // Volume-target batches only: the planned mass the weigh-out scaled to.
+    plannedMass: _plannedMassInfo(b, f, batchesById),
+    // The formula's declared finished density (g/mL of the mixed product) that
+    // volume targets and estimates use; null = the app is on its ideal-mix estimate.
+    formulaFinishedDensity: _finishedDensityInfo(f, batchesById),
     preparedDate: b.preparedDate || '',
     preparedBy: b.preparedBy || '',
     // Finished-goods storage location for this batch's produced stock (Production
@@ -167,7 +239,7 @@ const list_batches = {
     return {
       totalMatching: filtered.length,
       returned: Math.min(filtered.length, limit),
-      batches: filtered.slice(0, limit).map(b => _trimBatch(b, indexes.formulationsById)),
+      batches: filtered.slice(0, limit).map(b => _trimBatch(b, indexes.formulationsById, indexes.ingredientsById, indexes.batchesById)),
     };
   },
 };
@@ -202,7 +274,7 @@ const get_batch = {
         })
       : null;
     return {
-      ..._trimBatch(b, indexes.formulationsById),
+      ..._trimBatch(b, indexes.formulationsById, indexes.ingredientsById, indexes.batchesById),
       notes: b.notes || '',
       equipmentUsed: b.equipmentUsed || '',
       // Multi-select equipment: full list [{name, equipmentId}]; falls back to

package/tools/library.js

@@ -12,6 +12,55 @@
 // ============================================================
 
 import { getStore, resolveById } from '../data.js';
+import { _evalPassFail } from './analytics.js';
+
+// ── Usage roll-ups (mirror the Usage tabs on the Panel / Method / Equipment
+//    detail pages) ────────────────────────────────────────────────────────
+// Resolve a measurement's instrument the way the app does: named on the row →
+// the parameter's Test Method equipment → the report's run default.
+function _resolveInstrument(m, t, db) {
+  if (m.equipmentId || m.instrument) return { equipmentId: m.equipmentId || '', name: m.instrument || '', source: 'row' };
+  const pm = m.parameterId ? (db.parameters || []).find(p => p.id === m.parameterId)
+    : (db.parameters || []).find(p => _norm(p.name) === _norm(m.parameter));
+  if (pm && (pm.equipmentId || pm.equipment)) return { equipmentId: pm.equipmentId || '', name: pm.equipment || '', source: 'method' };
+  if (t && (t.equipmentId || t.instrument)) return { equipmentId: t.equipmentId || '', name: t.instrument || '', source: 'run' };
+  return { equipmentId: '', name: '', source: '' };
+}
+function _num(m) { const v = parseFloat(m && m.value); return Number.isFinite(v) ? v : null; }
+function _mean(a) { return a.length ? a.reduce((x, y) => x + y, 0) / a.length : null; }
+function _sd(a) { if (a.length < 2) return null; const mu = _mean(a); return Math.sqrt(a.reduce((acc, x) => acc + (x - mu) ** 2, 0) / (a.length - 1)); }
+function _r(v, d = 3) { return v == null ? null : +v.toFixed(d); }
+// Where a set of reports (optionally restricted to measurements passing
+// `measFilter`) landed: totals + by-formula breakdown (top 10). `fails` uses the
+// measurement's own acceptance criteria (panel spec inheritance is app-side).
+function _usageRollup(db, tests, measFilter) {
+  const sById = new Map((db.samples || []).map(s => [s.id, s]));
+  const bById = new Map((db.batches || []).map(b => [b.id, b]));
+  const fById = new Map((db.formulations || []).map(f => [f.id, f]));
+  const date = t => String(t.testDate || (t.createdAt || '').slice(0, 10) || '');
+  const byF = new Map(); const forms = new Set(), batches = new Set(), samples = new Set(), labs = new Set();
+  let readings = 0, fails = 0, withSpec = 0, last = '';
+  tests.forEach(t => {
+    const s = sById.get(t.sampleId) || null; const b = s ? bById.get(s.batchId) : null;
+    const f = (s && s.formulationId) ? fById.get(s.formulationId) : (b ? fById.get(b.formulationId) : null);
+    if (s) samples.add(s.id); if (b) batches.add(b.id); if (f) forms.add(f.id); if (t.lab) labs.add(t.lab);
+    const d = date(t); if (d > last) last = d;
+    let tf = 0;
+    (t.measurements || []).filter(m => !measFilter || measFilter(m, t)).forEach(m => {
+      readings++;
+      const pf = _evalPassFail(m); if (pf !== 'no-criteria' && pf !== 'untested') withSpec++; if (pf === 'fail') { fails++; tf++; }
+    });
+    const key = f ? f.id : '(no formula)';
+    if (!byF.has(key)) byF.set(key, { formula: f ? (f.uid || f.name) : null, formulaName: f ? f.name : null, reports: 0, lastRun: '', fails: 0 });
+    const g = byF.get(key); g.reports++; if (d > g.lastRun) g.lastRun = d; g.fails += tf;
+  });
+  return {
+    reports: tests.length, readings, lastUsed: last || null,
+    formulas: forms.size, batches: batches.size, samples: samples.size, labs: labs.size,
+    fails, passRate: withSpec ? _r(100 * (withSpec - fails) / withSpec, 0) : null,
+    byFormula: [...byF.values()].sort((a, b) => b.reports - a.reports).slice(0, 10),
+  };
+}
 
 const _norm = (s) => String(s == null ? '' : s).toLowerCase();
 const _clampLimit = (n) => Math.min(1000, Math.max(1, n || 100));
@@ -99,7 +148,7 @@ const list_equipment = {
 const get_equipment = {
   definition: {
     name: 'get_equipment',
-    description: 'Get one equipment record by UID (e.g. EQP-001) or id, including a summary of everywhere it is referenced (test panels, step presets, test methods, formulas, batches).',
+    description: 'Get one equipment record by UID (e.g. EQP-001) or id, including `usedIn` (everywhere its DEFINITION is referenced: test panels, step presets, test methods, formula steps, batches, plus testReports = reports with a measurement resolved to it), `usage` (those reports: totals, last used, distinct formulas/batches/samples, pass rate, top formulas) and `measured` (per parameter: readings and mean on this unit vs readings/mean on all OTHER instruments, with biasPct — the calibration question). Instrument resolution follows the app: named on the measurement → the Test Method\'s equipment → the report\'s run default.',
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string', description: 'Equipment UID or internal id.' } },
@@ -110,7 +159,25 @@ const get_equipment = {
     const { db } = getStore();
     const e = resolveById('equipment', args.id);
     if (!e) return { error: `No equipment found for "${args.id}".` };
-    return { ...(_trimEquipment(e)), usedIn: _equipUsage(e, db) };
+    // Measurements whose RESOLVED instrument is this unit (row → method → run).
+    const nm = _norm(e.name);
+    const mine = (m, t) => { const r = _resolveInstrument(m, t, db); return r.equipmentId ? r.equipmentId === e.id : (!!nm && _norm(r.name) === nm); };
+    const tests = (db.testResults || []).filter(t => (t.measurements || []).some(m => mine(m, t)));
+    const here = new Map(), fleet = new Map();
+    (db.testResults || []).forEach(t => (t.measurements || []).forEach(m => {
+      const pn = (m.parameter || '').trim(); if (!pn) return;
+      const v = _num(m); const isMine = mine(m, t); const bucket = isMine ? here : fleet;
+      if (!bucket.has(pn)) bucket.set(pn, { parameter: pn, readings: 0, vals: [], fails: 0 });
+      const g = bucket.get(pn); g.readings++; if (v != null) g.vals.push(v); if (isMine && _evalPassFail(m) === 'fail') g.fails++;
+    }));
+    const measured = [...here.values()].map(g => {
+      const f = fleet.get(g.parameter); const mh = _mean(g.vals), me = f ? _mean(f.vals) : null;
+      return { parameter: g.parameter, readings: g.readings, mean: _r(mh), fails: g.fails, readingsElsewhere: f ? f.readings : 0, meanElsewhere: _r(me),
+        biasPct: (mh != null && me != null && me !== 0) ? _r((mh - me) / Math.abs(me) * 100, 1) : null };
+    }).sort((a, b) => b.readings - a.readings);
+    const usedIn = _equipUsage(e, db);
+    usedIn.testReports = tests.length;
+    return { ...(_trimEquipment(e)), usedIn, usage: _usageRollup(db, tests, mine), measured };
   },
 };
 
@@ -187,7 +254,7 @@ const list_test_methods = {
 const get_test_method = {
   definition: {
     name: 'get_test_method',
-    description: 'Get one Test Method by UID (e.g. PARAM-001) or id — full definition including SOP / sample prep / equipment / calculation / acceptance spec, the declared runConditions this method varies by (the vocabulary — e.g. Storage temp/RH, spindle RPM; each measurement captures a value per condition), plus sibling methods that share its analyte (the same property measured at other conditions) and the Test Panels that use this method.',
+    description: 'Get one Test Method by UID (e.g. PARAM-001) or id — full definition including SOP / sample prep / equipment / calculation / acceptance spec, the declared runConditions this method varies by (the vocabulary — e.g. Storage temp/RH, spindle RPM; each measurement captures a value per condition), sibling methods that share its analyte, the Test Panels that use it, plus `usage` (reports / readings linked to this method: totals, last used, distinct formulas/batches/samples, pass rate, top formulas), `valueSummary` (mean / sd / min / max over numeric readings) and `byInstrument` (readings, mean and fails per resolved instrument — a mean that differs between units is a calibration question).',
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string', description: 'Test Method UID or internal id.' } },
@@ -208,7 +275,19 @@ const get_test_method = {
       (row.parameterId && row.parameterId === p.id) ||
       (!row.parameterId && _norm(row.parameter || row.name) === nm)
     )).map(t => t.uid || t.name).slice(0, 40);
-    return { ...(_trimMethod(p, { full: true })), analyteSiblings: siblings, usingPanels };
+    // Usage = every measurement linked to this method (by id, else by exact name).
+    const match = (m) => (m.parameterId && m.parameterId === p.id) || (!m.parameterId && _norm(m.parameter) === nm);
+    const tests = (db.testResults || []).filter(r => (r.measurements || []).some(match));
+    const vals = [], byInst = new Map();
+    tests.forEach(r => (r.measurements || []).filter(match).forEach(m => {
+      const v = _num(m); if (v != null) vals.push(v);
+      const inst = _resolveInstrument(m, r, db); const key = inst.name || inst.equipmentId || '(unresolved)';
+      if (!byInst.has(key)) byInst.set(key, { instrument: key, readings: 0, vals: [], fails: 0 });
+      const g = byInst.get(key); g.readings++; if (v != null) g.vals.push(v); if (_evalPassFail(m) === 'fail') g.fails++;
+    }));
+    const byInstrument = [...byInst.values()].map(g => ({ instrument: g.instrument, readings: g.readings, mean: _r(_mean(g.vals)), fails: g.fails })).sort((a, b) => b.readings - a.readings);
+    const valueSummary = { readings: vals.length, mean: _r(_mean(vals)), sd: _r(_sd(vals)), min: vals.length ? Math.min(...vals) : null, max: vals.length ? Math.max(...vals) : null, unit: p.defaultUnit || '' };
+    return { ...(_trimMethod(p, { full: true })), analyteSiblings: siblings, usingPanels, usage: _usageRollup(db, tests, match), valueSummary, byInstrument };
   },
 };
 
@@ -356,7 +435,7 @@ const list_test_panels = {
 const get_test_panel = {
   definition: {
     name: 'get_test_panel',
-    description: 'Get one Test Panel by UID (e.g. TMPL-001) or id — full ordered parameter list (each with its resolved Test Method UID, unit, and spec), instruments, and notes.',
+    description: 'Get one Test Panel by UID (e.g. TMPL-001) or id — full ordered parameter list (each with its resolved Test Method UID, unit, and spec), instruments, notes, plus `usage` (reports created from this panel: totals, last used, distinct formulas/batches/samples, pass rate, top formulas) and `performanceByParameter` (readings / fails per parameter). Usage counts reports created from the panel, not parameter overlap.',
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string', description: 'Test Panel UID or internal id.' } },
@@ -367,7 +446,19 @@ const get_test_panel = {
     const { db } = getStore();
     const t = resolveById('templates', args.id);
     if (!t) return { error: `No test panel found for "${args.id}".` };
-    return _trimPanel(t, db, { full: true });
+    // Usage = reports created FROM this panel (templateId) — not parameter overlap.
+    const tests = (db.testResults || []).filter(r => r.templateId === t.id);
+    const perf = (t.parameters || []).map(row => {
+      const nm = _norm(row.parameter || row.name), pid = row.parameterId || '';
+      let n = 0, fails = 0, withSpec = 0;
+      tests.forEach(r => (r.measurements || []).forEach(m => {
+        const hit = (pid && m.parameterId === pid) || ((!m.parameterId || !pid) && _norm(m.parameter) === nm);
+        if (!hit) return; n++;
+        const pf = _evalPassFail(m); if (pf !== 'no-criteria' && pf !== 'untested') withSpec++; if (pf === 'fail') fails++;
+      }));
+      return { parameter: row.parameter || row.name, readings: n, fails, failRatePct: withSpec ? _r(100 * fails / withSpec, 0) : null };
+    });
+    return { ...(_trimPanel(t, db, { full: true })), usage: _usageRollup(db, tests, null), performanceByParameter: perf };
   },
 };