canli-validation-mcp 0.7.1 → 0.8.1

package/README.md

@@ -378,6 +378,8 @@ HTTP stub. It neither publishes a package nor issues a production API key.
 
 ## Dependencies
 
-Only `@modelcontextprotocol/sdk` (pinned exact) and `zod` (pinned exact). No other runtime
-dependency is added, and nothing in this package touches the site's root `package.json`,
+Only `@modelcontextprotocol/server` (pinned exact; the MCP SDK's server package, which itself
+depends only on `@modelcontextprotocol/core` and `zod`) and `zod` (pinned exact): four packages in
+the installed tree, where 0.7 and earlier pulled in about 95 through `@modelcontextprotocol/sdk`.
+No other runtime dependency is added, and nothing in this package touches the site's root `package.json`,
 `.vercelignore`, `api/`, `scripts/`, `js/`, or `public/`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "canli-validation-mcp",
-  "version": "0.7.1",
-  "description": "MCP server for canlicapital.com's free validation API: deflated Sharpe, CSCV overfitting, paper-evidence conformance, and breadth ceiling, each returned as the full API envelope so the boundary language cannot be dropped.",
+  "version": "0.8.1",
+  "description": "Check whether a backtest is real: deflated Sharpe, CSCV probability of backtest overfitting, minimum track record and backtest length, haircut Sharpe and luck-equivalent trials, as an MCP server. Local mode, hosted endpoint, signed receipts.",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -16,11 +16,11 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test test/*.test.mjs",
+    "test": "node --test test/*.test.mjs test/*.test.js",
     "test:package": "node test/package-smoke.mjs"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.30.0",
+    "@modelcontextprotocol/server": "2.1.0",
     "zod": "4.6.5"
   },
   "mcpName": "io.github.arhancanli/canli-validation-mcp",
@@ -34,6 +34,7 @@
     "url": "https://github.com/arhancanli/canlicapital/issues"
   },
   "devDependencies": {
+    "@modelcontextprotocol/client": "2.1.0",
     "fast-check": "4.10.2"
   }
 }

package/src/schemas.mjs

@@ -47,7 +47,7 @@ export const FIELD_DESCRIPTIONS = Object.freeze({
   autocorrelation: "First-order autocorrelation of the returns, -1 to 1; default 0. Corrects the annualized Sharpe as Lo (2002).",
   other_sharpes: "Annualized Sharpe ratios of the other tests, over the same observations; adds the Holm and BHY haircuts.",
   lt_trials: "Independent trials tried; adds the chance that the best of them reached this Sharpe by luck.",
-  skew: "Skewness of the returns; below -0.5 the reading warns that the counts are too generous.",
+  lt_skew: "Skewness of the returns; below -0.5 the reading warns that the counts are too generous.",
   variants: "Optional returns of every variant tried, this one included, as fractions: one row per period, one column per variant. Adds the overfitting check.",
   returns_file: "Path to a CSV or JSON file of the returns on the machine running this server, instead of returns. Not available on the hosted endpoint.",
   returns_column: "Header name or 1-based position of the returns column when returns_file has several numeric columns.",
@@ -108,7 +108,7 @@ export const deflatedSharpeToolShape = z
 
 export const overfittingInput = z
   .object({
-    matrix: z.array(z.array(z.number())).min(2).max(20000).describe(d.matrix),
+    matrix: z.array(z.array(z.number()).max(200)).min(2).max(20000).describe(d.matrix),
     n_splits: z.number().int().positive().optional().describe(d.n_splits),
     max_combinations: z.number().int().positive().max(2000).optional().describe(d.max_combinations),
     seed: z.number().optional().describe(d.seed),
@@ -192,7 +192,7 @@ export const luckTrialsInput = z
     periods_per_year: z.number().min(1).max(10000).describe(d.periods_per_year),
     observations: z.number().int().min(3).max(1000000).describe(d.hc_observations),
     effective_independent_trials: z.number().int().min(1).max(1000000000).optional().describe(d.lt_trials),
-    skew: z.number().min(-100).max(100).optional().describe(d.skew),
+    skew: z.number().min(-100).max(100).optional().describe(d.lt_skew),
     autocorrelation: z.number().gt(-1).lt(1).optional().describe(d.autocorrelation),
   })
   .strict();
@@ -212,7 +212,7 @@ export const auditBacktestToolShape = z
     cross_trial_sharpe_sd_annualized: z.number().min(0).max(10).describe(d.cross_trial_sharpe_sd_annualized),
     benchmark_sharpe_annualized: z.number().min(-10).max(10).optional().describe(d.benchmark_sharpe_annualized),
     confidence: z.number().gt(0).lt(1).optional().describe(d.confidence),
-    variants: z.array(z.array(z.number())).min(2).max(20000).optional().describe(d.variants),
+    variants: z.array(z.array(z.number()).max(200)).min(2).max(20000).optional().describe(d.variants),
     variants_file: z.string().min(1).max(4096).optional().describe(d.variants_file),
     n_splits: z.number().int().positive().optional().describe(d.n_splits),
   })
@@ -303,17 +303,61 @@ export const REGISTRY_DESCRIPTION_MAX = 100;
 // calls the tool, not only inside the returned envelope.
 export const TOOL_DESCRIPTIONS = Object.freeze({
   get_key: `Issue a free canlicapital.com validation key (POST /api/v1/keys) and hold it in memory for this session. Only needed before a validation when neither CANLI_KEY nor local mode is set; the read tools (get_receipt, service_status, company_financial_history) never need a key. ${LIMITS_SENTENCES.quotas}`,
-  validate_deflated_sharpe: `Whether a Sharpe survives the number of variants tried: probabilistic and deflated Sharpe (0 to 1) and the Sharpe luck alone would reach. Send the seven statistics or a return series, not both. ${LIMITS_SENTENCES.notAdmission}`,
-  audit_backtest: `Audit one strategy's return series in one call: deflated Sharpe, the minimum track record length for its Sharpe to beat the benchmark, and, with every variant's returns, the probability of backtest overfitting. Point returns_file at the backtest's CSV or JSON rather than copying long series into the call. Each check is the matching validate_ tool's result with its own receipt, side by side; the audit does not grade the strategy. Uses one validation per check. ${LIMITS_SENTENCES.notAdmission}`,
-  validate_overfitting: `Probability (0 to 1) that picking the best of several backtested variants was overfitting, by CSCV over every variant's returns. ${LIMITS_SENTENCES.notAdmission}`,
-  validate_paper_evidence: `Whether a paper or simulated performance record meets canli.paper-evidence.v0, with each failure's JSON pointer. ${LIMITS_SENTENCES.scope}`,
-  validate_backtest_length: `Minimum backtest length, in years, before the best of N independent trials is not expected to reach a target Sharpe by luck, and with backtest_years, the most independent trials those years allow. Send effective_independent_trials, backtest_years, or both. ${LIMITS_SENTENCES.notAdmission}`,
-  validate_luck_trials: `How many skill-less strategies a search would have had to try for its best to reach this Sharpe by luck, and, with a trial count, the chance that it did. Calibrated by Monte Carlo. ${LIMITS_SENTENCES.notAdmission}`,
-  validate_haircut_sharpe: `Haircut Sharpe ratio for multiple testing (Harvey and Liu, 2015): the Sharpe a single test would have needed once the number of tests is counted, by Bonferroni and for independent tests, and with the other tests' Sharpe ratios by Holm and BHY. ${LIMITS_SENTENCES.notAdmission}`,
-  validate_track_record: `Minimum track record length, in observations and years, for an observed Sharpe to beat a benchmark at a confidence level, and with observations, the record's probabilistic Sharpe so far. ${LIMITS_SENTENCES.notAdmission}`,
-  validate_breadth: `Highest book Sharpe reachable by adding sleeves of this quality and correlation, the Sharpe at a sleeve count, and the sleeves a target needs. ${LIMITS_SENTENCES.scope}`,
+  validate_deflated_sharpe: `Deflated Sharpe ratio: the probability (0 to 1) that one selected strategy's Sharpe beats the best Sharpe that luck alone would give across the variants tried, with the probabilistic Sharpe and that luck benchmark. Use it for the strategy you kept after a search, when you know how many variants were tried and how their Sharpe ratios spread; send the seven statistics or a return series, not both. With every variant's returns use validate_overfitting; to state luck as a trial count use validate_luck_trials; for a multiple-testing haircut use validate_haircut_sharpe. ${LIMITS_SENTENCES.notAdmission}`,
+  audit_backtest: `Audit one strategy's return series in one call: deflated Sharpe, the minimum track record length for its Sharpe to beat the benchmark, and, with every variant's returns, the probability of backtest overfitting. Point returns_file at the backtest's CSV or JSON rather than copying long series into the call. Each check is the matching validate_ tool's result with its own receipt, side by side; the audit does not grade the strategy. Prefer it to calling those validators one by one when you have one strategy's return series. Uses one validation per check. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_overfitting: `Probability of backtest overfitting (0 to 1) by CSCV: how often the variant that is best in sample falls below the median out of sample. Use it when you have every variant's returns as a matrix (periods by variants); with summary statistics only, use validate_deflated_sharpe. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_paper_evidence: `Whether a paper or simulated performance record meets canli.paper-evidence.v0, with each failure's JSON pointer. Use it on a record document before publishing or relying on it: it checks structure and required disclosures, not whether the returns are good. ${LIMITS_SENTENCES.scope}`,
+  validate_backtest_length: `Minimum backtest length, in years, before the best of N independent trials is not expected to reach a target Sharpe by luck, and with backtest_years, the most independent trials those years allow. Send effective_independent_trials, backtest_years, or both. Use it before or while planning a search, to size the backtest for the number of trials; once a search has a result, use validate_deflated_sharpe. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_luck_trials: `How many skill-less strategies a search would have had to try for its best to reach this Sharpe by luck, and, with a trial count, the chance that it did. Calibrated by Monte Carlo. Use it to state luck as a count ("as good as the best of N random tries") or to test a result against the trials actually run; for a probability that the Sharpe is real, use validate_deflated_sharpe. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_haircut_sharpe: `Haircut Sharpe ratio for multiple testing (Harvey and Liu, 2015): the Sharpe a single test would have needed once the number of tests is counted, by Bonferroni and for independent tests, and with the other tests' Sharpe ratios by Holm and BHY. Use it to report a Sharpe adjusted for the number of tests, as finance papers do; for a probability that the Sharpe is real, use validate_deflated_sharpe. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_track_record: `Minimum track record length, in observations and years, for an observed Sharpe to beat a benchmark at a confidence level, and with observations, the record's probabilistic Sharpe so far. Use it for a live or paper record: how long it must run before its Sharpe is evidence. To size a backtest against the number of trials, use validate_backtest_length. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_breadth: `Highest book Sharpe reachable by adding sleeves of this quality and correlation, the Sharpe at a sleeve count, and the sleeves a target needs. Use it for portfolio construction, to see what adding strategies can and cannot do; it validates no single strategy. ${LIMITS_SENTENCES.scope}`,
   verify_receipt: `Check a validation receipt's Ed25519 signature offline against the canlicapital.com public key bundled in this package, that its output hashes to its output_sha256, and that its content hashes to its id. Send an id to fetch the receipt first, or a receipt already fetched. ${LIMITS_SENTENCES.unsigned}`,
-  get_receipt: `Fetch a stored verdict by receipt id (GET /api/v1/receipts/{id}) to re-check an earlier result. No key. ${LIMITS_SENTENCES.unsigned}`,
+  get_receipt: `Fetch a stored verdict by receipt id (GET /api/v1/receipts/{id}) to re-read an earlier result. No key. To check that the receipt is genuine, use verify_receipt. ${LIMITS_SENTENCES.unsigned}`,
   service_status: `Whether the validation API is up, with quota constants (GET /api/v1/validate/status); check after a timeout before resubmitting. No key. ${LIMITS_SENTENCES.scope}`,
   company_financial_history: `SEC-reported financial history for one company from the canlicapital.com company reference (GET /company-data/{cik}.json), by cik or by ticker (resolved through GET /api/v1/company-tickers.json, companies in the release only). Without a concept it lists the available histories; with one it returns observations, newest first, each with its filing accession, form, filed date and unit, plus the SHA-256 of the original SEC response. No key required. ${COMPANY_REFERENCE_BOUNDARY}`,
 });
+
+// Output schemas (0.8.0). Published OPEN: extra fields always pass. A client validates a tool's
+// structured result against the output schema it listed, so a closed schema turns every field a
+// later version adds into a failed call (2026-09-26, the mcp-factory servers). Every field is
+// optional because refusals and local results carry different subsets. They are kept terse: the
+// tool list is re-sent to the model every turn, and one sentence per schema says what to read.
+const refusal = z.looseObject({}).nullable().optional();
+const sentences = z.array(z.string()).optional();
+const loose = z.looseObject({}).optional();
+
+export const validationOutput = z
+  .looseObject({
+    data: loose,
+    error: refusal,
+    limits: sentences,
+    receipt: z.looseObject({}).nullable().optional(),
+    computed: z.string().optional(),
+    note: z.string().optional(),
+  })
+  .describe("data.result holds the statistics (data.plain_reading states them); limits say what the result does not establish; receipt ({id, url}) is the signed record, null when none was stored; error ({code, message}) is set only on refusal.");
+
+export const auditOutput = z
+  .looseObject({ readings: loose, checks: loose, not_run: loose, limits: sentences, note: z.string().optional(), error: refusal })
+  .describe("checks holds each check's full validate_ result by name; readings one sentence per check; not_run the checks skipped and why.");
+
+export const keyOutput = z
+  .looseObject({ note: z.string().optional(), key_source: z.string().optional(), key_present: z.boolean().optional(), data: loose, error: refusal })
+  .describe("key_source says which key the session uses; data.key is set when a new key was issued.");
+
+export const receiptOutput = z
+  .looseObject({ data: loose, error: refusal, limits: sentences })
+  .describe("data is the stored receipt: validator, input, output, their hashes, source hashes and signature.");
+
+export const verifyReceiptOutput = z
+  .looseObject({ receipt_id: z.string().nullable().optional(), valid: z.boolean().optional(), checks: z.unknown().optional(), key_id: z.string().nullable().optional(), meaning: z.string().optional(), error: refusal })
+  .describe("valid is true only when the signature, output hash and content id all check out; checks lists each.");
+
+export const statusOutput = z
+  .looseObject({ data: loose, limits: sentences, error: refusal })
+  .describe("data.store_reachable, data.quotas and, when available, data.usage for this key.");
+
+export const companyHistoryOutput = z
+  .looseObject({ company: loose, claim_boundary: z.string().optional(), source: loose, histories: z.array(z.unknown()).optional(), history: loose, error: refusal })
+  .describe("Without a concept, histories lists what is available; with one, history holds the observations newest first as columns and rows, each with its filing. Values are as reported to the SEC.");

package/src/series-file.mjs

@@ -41,6 +41,26 @@ function readText(path) {
 }
 
 const isNumber = (cell) => cell.trim() !== "" && Number.isFinite(Number(cell.trim()));
+// Cells a spreadsheet or pandas writes for a missing value.
+const isMissing = (cell) => /^(|nan|na|n\/a|#n\/a|null|none|-)$/i.test(cell.trim());
+const DATE = /^(\d{4}[-/.]\d{1,2}[-/.]\d{1,2}|\d{1,2}[-/.]\d{1,2}[-/.]\d{2,4})([ T].*)?$/;
+const kindOf = (cell) => (isNumber(cell) ? "number" : isMissing(cell) ? "missing" : DATE.test(cell.trim()) ? "date" : "text");
+
+// The first row is a header when one of its cells differs in kind from the cells below it: a label
+// above numbers or dates. A date above dates is data, so a file without a header keeps its first row.
+function hasHeader(first, below) {
+  if (!first.some((cell) => !isNumber(cell))) return false;
+  if (!below.length) return true;
+  return first.some((cell, j) => {
+    if (isNumber(cell)) return false;
+    // Missing values say nothing about what a column holds, so they do not vote.
+    const kinds = below.map((row) => kindOf(row[j] ?? "")).filter((k) => k !== "missing");
+    if (!kinds.length) return true;
+    const count = (k) => kinds.filter((x) => x === k).length;
+    const common = [...new Set(kinds)].sort((a, b) => count(b) - count(a))[0];
+    return kindOf(cell) !== common;
+  });
+}
 
 // A JSON array (of numbers, or of arrays of numbers), or delimited text: comma, semicolon or tab
 // separated, one row per line, with an optional header row naming the columns.
@@ -65,7 +85,7 @@ function parseTable(text, path) {
   const delimiter = [",", ";", "\t"].find((d) => lines[0].includes(d)) ?? ",";
   const split = (line) => line.split(delimiter).map((cell) => cell.trim());
   const first = split(lines[0]);
-  const header = first.some((cell) => !isNumber(cell)) ? first : null;
+  const header = hasHeader(first, lines.slice(1, 6).map(split)) ? first : null;
   const body = header ? lines.slice(1) : lines;
   const width = (header ?? first).length;
   const rows = body.map((line, i) => {
@@ -85,40 +105,58 @@ function isRowCounter(name, values) {
 }
 
 // Numeric columns only: a date or label column is dropped, never parsed; a row counter is skipped.
+// A column of numbers with some empty or NaN cells is not dropped: it is reported as incomplete, so
+// a blank cell can never make the reader pick a different column (a benchmark) in its place.
 function numericColumns({ header, rows }) {
   const width = rows[0]?.length ?? 0;
   const columns = [];
+  const incomplete = [];
   const skipped = [];
+  const offset = header ? 2 : 1; // file line of the first data row
   for (let j = 0; j < width; j += 1) {
-    if (rows.every((row) => typeof row[j] === "number" || isNumber(String(row[j])))) {
-      const values = rows.map((row) => Number(row[j]));
+    const cells = rows.map((row) => (typeof row[j] === "number" ? String(row[j]) : String(row[j])));
+    const numeric = cells.filter(isNumber).length;
+    if (numeric === cells.length) {
+      const values = cells.map(Number);
       if (isRowCounter(header ? header[j] : null, values)) skipped.push(j + 1);
       else columns.push({ index: j, name: header ? header[j] : String(j + 1), values });
+    } else if (numeric > 0 && numeric * 2 >= cells.length && cells.every((c) => isNumber(c) || isMissing(c))) {
+      const gaps = cells.map((c, i) => (isNumber(c) ? null : i + offset)).filter((i) => i !== null);
+      incomplete.push({ index: j, name: header ? header[j] : String(j + 1), gaps });
     }
   }
-  return { columns, skipped };
+  return { columns, incomplete, skipped };
 }
 
+const lineList = (gaps) => (gaps.length > 5 ? `${gaps.slice(0, 5).join(", ")} and ${gaps.length - 5} more` : gaps.join(", "));
+const incompleteError = (path, c) => new Error(`${path}: column ${c.index + 1} holds numbers but is empty or not a number on line${c.gaps.length > 1 ? "s" : ""} ${lineList(c.gaps)}; fill or remove those rows, or pick another column with returns_column`);
+
 // One series. With several numeric columns, `column` (a header name or a 1-based index) picks it.
-// Returns the values and the positions of any row-counter columns skipped.
+// Returns the values, the 1-based position of the column read, and the positions of any row-counter
+// columns skipped. Without `column`, any incomplete numeric column is refused, naming its lines.
 export function readSeriesFile(path, column) {
   const table = parseTable(readText(path), path);
   if (!table.rows.length) throw new Error(`${path}: no data rows`);
-  const { columns, skipped } = numericColumns(table);
-  if (!columns.length) throw new Error(`${path}: no column holds only numbers`);
+  const { columns, incomplete, skipped } = numericColumns(table);
+  const match = (list) => list.find((c) => c.name === String(column)) ?? list.find((c) => String(c.index + 1) === String(column));
   if (column === undefined) {
+    if (incomplete.length) throw incompleteError(path, incomplete[0]);
+    if (!columns.length) throw new Error(`${path}: no column holds only numbers`);
     if (columns.length > 1) throw new Error(`${path}: ${columns.length} numeric columns (positions ${columns.map((c) => c.index + 1).join(", ")}); pick one with returns_column, by header name or position`);
-    return { values: columns[0].values, skipped };
+    return { values: columns[0].values, column: columns[0].index + 1, skipped };
   }
-  const picked = columns.find((c) => c.name === String(column)) ?? columns.find((c) => String(c.index + 1) === String(column));
-  if (!picked) throw new Error(`${path}: returns_column matches no numeric column; numeric columns are at positions ${columns.map((c) => c.index + 1).join(", ")}`);
-  return { values: picked.values, skipped };
+  const gappy = match(incomplete);
+  if (gappy) throw incompleteError(path, gappy);
+  const picked = match(columns);
+  if (!picked) throw new Error(`${path}: returns_column matches no numeric column; numeric columns are at positions ${columns.map((c) => c.index + 1).join(", ") || "none"}`);
+  return { values: picked.values, column: picked.index + 1, skipped };
 }
 
-// Every numeric column is one variant; rows are periods.
+// Every numeric column is one variant; rows are periods. An incomplete column is refused.
 export function readMatrixFile(path) {
   const table = parseTable(readText(path), path);
-  const { columns, skipped } = numericColumns(table);
+  const { columns, incomplete, skipped } = numericColumns(table);
+  if (incomplete.length) throw incompleteError(path, incomplete[0]);
   if (columns.length < 2) throw new Error(`${path}: needs at least 2 numeric columns, one per variant`);
   return { matrix: table.rows.map((_, i) => columns.map((c) => c.values[i])), skipped };
 }

package/src/server.mjs

@@ -8,33 +8,13 @@
 // CANLI_KEY; when CANLI_KEY is set, get_key does not call the network.
 import { readFileSync, realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import { computeLocally } from "./local.mjs";
 import { readMatrixFile, readSeriesFile } from "./series-file.mjs";
 import { verifyReceipt } from "./local/js/receipt-statement.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  breadthInput,
-  trackRecordInput,
-  auditBacktestInput,
-  verifyReceiptToolShape,
-  backtestLengthInput,
-  haircutSharpeInput,
-  luckTrialsInput,
-  auditBacktestToolShape,
-  companyHistoryInput,
-  companyHistoryToolShape,
-  deflatedSharpeInput,
-  deflatedSharpeToolShape,
-  emptyInput,
-  getKeyInput,
-  getReceiptInput,
-  overfittingInput,
-  LIMITS_SENTENCES,
-  paperEvidenceInput,
-  TOOL_DESCRIPTIONS,
-} from "./schemas.mjs";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { breadthInput, trackRecordInput, auditBacktestInput, verifyReceiptToolShape, backtestLengthInput, haircutSharpeInput, luckTrialsInput, auditBacktestToolShape, companyHistoryInput, companyHistoryToolShape, deflatedSharpeInput, deflatedSharpeToolShape, emptyInput, getKeyInput, getReceiptInput, overfittingInput, LIMITS_SENTENCES, paperEvidenceInput, TOOL_DESCRIPTIONS, validationOutput, auditOutput, keyOutput, receiptOutput, verifyReceiptOutput, statusOutput, companyHistoryOutput } from "./schemas.mjs";
 
 export const DEFAULT_BASE = "https://canlicapital.com";
 export const SERVER_NAME = "canlicapital-validation-mcp";
@@ -369,7 +349,7 @@ export async function toolAuditBacktest(session, args) {
     checks,
     ...(input.returns_file || input.variants_file
       ? { source: {
-          ...(returnsRead ? { returns_file: input.returns_file, observations: returns.length, ...(returnsRead.skipped.length ? { skipped_row_counter_columns: returnsRead.skipped } : {}) } : {}),
+          ...(returnsRead ? { returns_file: input.returns_file, returns_column_position: returnsRead.column, observations: returns.length, ...(returnsRead.skipped.length ? { skipped_row_counter_columns: returnsRead.skipped } : {}) } : {}),
           ...(variantsRead ? { variants_file: input.variants_file, variants: variants[0].length, periods: variants.length, ...(variantsRead.skipped.length ? { skipped_variant_row_counter_columns: variantsRead.skipped } : {}) } : {}),
         } }
       : {}),
@@ -392,7 +372,21 @@ export async function toolVerifyReceipt(session, args) {
     data = response.envelope?.data;
   }
   const endpoint = String(data?.endpoint ?? "").replace(/^\/api\/v1\//, "");
-  const result = verifyReceipt({ ...data, endpoint }, session.receiptKeys ?? RECEIPT_KEYS.keys);
+  // A receipt missing a field (output, bindings, input_sha256) cannot be hashed, and that is a
+  // failed check, not a tool error: the answer is still "not issued for this content".
+  let result;
+  try {
+    result = verifyReceipt({ ...data, endpoint }, session.receiptKeys ?? RECEIPT_KEYS.keys);
+  } catch {
+    const missing = ["id", "endpoint", "input_sha256", "output", "bindings", "signature"].filter((k) => data?.[k] === undefined);
+    return asText({
+      receipt_id: data?.id ?? null,
+      valid: false,
+      checks: { well_formed: false, id_matches_content: false, signature_valid: false, key_published: false },
+      key_id: data?.signature?.key_id ?? null,
+      meaning: `The receipt is not well formed${missing.length ? `: it has no ${missing.join(", ")}` : ""}, so it cannot be checked. Send the whole receipt object as get_receipt or the validation result returned it, or send its id.`,
+    });
+  }
   return asText({
     receipt_id: data?.id ?? null,
     valid: result.valid,
@@ -428,7 +422,7 @@ async function resolveTicker(session, ticker) {
     try {
       res = await session.fetchImpl(`${session.base}/api/v1/company-tickers.json`, { headers: { Accept: "application/json" }, signal, redirect: "error" });
     } catch {
-      throw new Error(signal.aborted ? "company_financial_history: the ticker index request timed out" : "company_financial_history: could not reach the ticker index");
+      throw new Error(`company_financial_history: ${signal.aborted ? "the ticker index request timed out" : "could not reach the ticker index"} at ${session.base}. Retry, check service_status, or pass the SEC CIK instead of a ticker.`);
     }
     if (!res.ok) throw new Error(`company_financial_history: the ticker index returned HTTP ${res.status}`);
     session.tickerIndex = await res.json();
@@ -526,72 +520,72 @@ export function registerTools(server, session) {
   const register = (name, ...rest) => { if (enabled.has(name)) server.registerTool(name, ...rest); };
   register(
     "get_key",
-    { title: "Get a free validation key", annotations: { title: "Get a free validation key", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, description: TOOL_DESCRIPTIONS.get_key, inputSchema: getKeyInput },
+    { title: "Get a free validation key", annotations: { title: "Get a free validation key", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, description: TOOL_DESCRIPTIONS.get_key, inputSchema: getKeyInput, outputSchema: keyOutput },
     (args) => toolGetKey(session, args),
   );
   register(
     "validate_deflated_sharpe",
-    { title: "Validate deflated Sharpe", annotations: { title: "Validate deflated Sharpe", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_deflated_sharpe, inputSchema: deflatedSharpeToolShape },
+    { title: "Validate deflated Sharpe", annotations: { title: "Validate deflated Sharpe", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_deflated_sharpe, inputSchema: deflatedSharpeToolShape, outputSchema: validationOutput },
     (args) => toolValidateDeflatedSharpe(session, args),
   );
   register(
     "validate_overfitting",
-    { title: "Validate overfitting (CSCV)", annotations: { title: "Validate overfitting (CSCV)", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_overfitting, inputSchema: overfittingInput },
+    { title: "Validate overfitting (CSCV)", annotations: { title: "Validate overfitting (CSCV)", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_overfitting, inputSchema: overfittingInput, outputSchema: validationOutput },
     (args) => toolValidateOverfitting(session, args),
   );
   register(
     "validate_paper_evidence",
-    { title: "Validate paper evidence", annotations: { title: "Validate paper evidence", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_paper_evidence, inputSchema: paperEvidenceInput },
+    { title: "Validate paper evidence", annotations: { title: "Validate paper evidence", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_paper_evidence, inputSchema: paperEvidenceInput, outputSchema: validationOutput },
     (args) => toolValidatePaperEvidence(session, args),
   );
   register(
     "validate_breadth",
-    { title: "Validate breadth ceiling", annotations: { title: "Validate breadth ceiling", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_breadth, inputSchema: breadthInput },
+    { title: "Validate breadth ceiling", annotations: { title: "Validate breadth ceiling", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_breadth, inputSchema: breadthInput, outputSchema: validationOutput },
     (args) => toolValidateBreadth(session, args),
   );
   register(
     "validate_track_record",
-    { title: "Minimum track record length", annotations: { title: "Minimum track record length", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_track_record, inputSchema: trackRecordInput },
+    { title: "Minimum track record length", annotations: { title: "Minimum track record length", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_track_record, inputSchema: trackRecordInput, outputSchema: validationOutput },
     (args) => toolValidateTrackRecord(session, args),
   );
   register(
     "validate_backtest_length",
-    { title: "Minimum backtest length", annotations: { title: "Minimum backtest length", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_backtest_length, inputSchema: backtestLengthInput },
+    { title: "Minimum backtest length", annotations: { title: "Minimum backtest length", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_backtest_length, inputSchema: backtestLengthInput, outputSchema: validationOutput },
     (args) => toolValidateBacktestLength(session, args),
   );
   register(
     "validate_haircut_sharpe",
-    { title: "Haircut Sharpe ratio", annotations: { title: "Haircut Sharpe ratio", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_haircut_sharpe, inputSchema: haircutSharpeInput },
+    { title: "Haircut Sharpe ratio", annotations: { title: "Haircut Sharpe ratio", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_haircut_sharpe, inputSchema: haircutSharpeInput, outputSchema: validationOutput },
     (args) => toolValidateHaircutSharpe(session, args),
   );
   register(
     "validate_luck_trials",
-    { title: "Luck-equivalent trials", annotations: { title: "Luck-equivalent trials", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_luck_trials, inputSchema: luckTrialsInput },
+    { title: "Luck-equivalent trials", annotations: { title: "Luck-equivalent trials", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_luck_trials, inputSchema: luckTrialsInput, outputSchema: validationOutput },
     (args) => toolValidateLuckTrials(session, args),
   );
   register(
     "audit_backtest",
-    { title: "Audit a backtest", annotations: { title: "Audit a backtest", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.audit_backtest, inputSchema: auditBacktestToolShape },
+    { title: "Audit a backtest", annotations: { title: "Audit a backtest", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.audit_backtest, inputSchema: auditBacktestToolShape, outputSchema: auditOutput },
     (args) => toolAuditBacktest(session, args),
   );
   register(
     "get_receipt",
-    { title: "Get a receipt", annotations: { title: "Get a receipt", ...READ_ONLY }, description: TOOL_DESCRIPTIONS.get_receipt, inputSchema: getReceiptInput },
+    { title: "Get a receipt", annotations: { title: "Get a receipt", ...READ_ONLY }, description: TOOL_DESCRIPTIONS.get_receipt, inputSchema: getReceiptInput, outputSchema: receiptOutput },
     (args) => toolGetReceipt(session, args),
   );
   register(
     "verify_receipt",
-    { title: "Verify a receipt", annotations: { title: "Verify a receipt", ...READ_ONLY }, description: TOOL_DESCRIPTIONS.verify_receipt, inputSchema: verifyReceiptToolShape },
+    { title: "Verify a receipt", annotations: { title: "Verify a receipt", ...READ_ONLY }, description: TOOL_DESCRIPTIONS.verify_receipt, inputSchema: verifyReceiptToolShape, outputSchema: verifyReceiptOutput },
     (args) => toolVerifyReceipt(session, args),
   );
   register(
     "service_status",
-    { title: "Service status", annotations: { title: "Service status", ...READ_ONLY }, description: TOOL_DESCRIPTIONS.service_status, inputSchema: emptyInput },
+    { title: "Service status", annotations: { title: "Service status", ...READ_ONLY }, description: TOOL_DESCRIPTIONS.service_status, inputSchema: emptyInput, outputSchema: statusOutput },
     () => toolServiceStatus(session),
   );
   register(
     "company_financial_history",
-    { title: "Company financial history (SEC)", annotations: { title: "Company financial history (SEC)", ...READ_ONLY }, description: TOOL_DESCRIPTIONS.company_financial_history, inputSchema: companyHistoryToolShape },
+    { title: "Company financial history (SEC)", annotations: { title: "Company financial history (SEC)", ...READ_ONLY }, description: TOOL_DESCRIPTIONS.company_financial_history, inputSchema: companyHistoryToolShape, outputSchema: companyHistoryOutput },
     (args) => toolCompanyFinancialHistory(session, args),
   );
 }