canli-markets-mcp 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.7.2
+
+- `market_overview`: the market at a glance in one call: US indices and the VIX, the eleven S&P sectors
+  ranked by the month, Treasury yields, the dollar and major currencies, oil, gas, gold, silver and copper,
+  bitcoin and ether, and the main markets in Europe and Asia, each over a day, a week, a month, three
+  months, the year to date and a year (yields in percentage points). A market that fails is listed as
+  missing. 64 tools.
+- `shareholder_returns`: what a company has paid its shareholders, year by year from its annual XBRL:
+  dividends per share and in total, buybacks and shares issued for cash, the diluted share count, the
+  payout ratio and the share of free cash flow paid out; the dividend's record on split-adjusted figures
+  (years raised in a row, 5- and 10-year growth; a split shows in older 10-Ks as a cut otherwise); and the
+  dividend and shareholder yields at the last close.
+- `ownership_breadth` finds the CUSIP from a company's name in many more cases: 13F tables shorten
+  issuer names ("COSTCO WHSL CORP NEW", "BANK OF AMER CORP"), write "&" as "&", and some filers
+  slip, so names now match word by word with abbreviations, the CUSIP check digit is checked, the
+  company's own 13F and old text filings are skipped, three tables vote, and among several CUSIPs
+  (share classes, or a CUSIP that changed) the one most filers list is counted, the others shown.
+  A CUSIP new in recent quarters is flagged rather than read as a jump in ownership.
+- `news` tries GDELT three times, each after a longer wait, before reporting its rate limit.
+
+## 0.7.1
+
+- `compute_prices`: compute as a market. The on-demand hourly price of each data-centre GPU (B200,
+  H200, H100, A100, L40S...) across the clouds and GPU marketplaces, every provider's offer for one
+  model, recent list-price changes, and the Cirrun GPU Index, a daily chained index of those prices
+  (cirrun.com, no key, CC BY 4.0). 62 tools.
+
 ## 0.7.0
 
 - `ipo_pipeline`: S-1/F-1 registrations (IPO candidates, SPACs, funds, listed filers) and priced IPOs

package/README.md

@@ -87,9 +87,11 @@ against the BIS (21 of 21 agreed on 2026-10-15).
 | `ownership_breadth` | How many institutions hold a stock, quarter by quarter: 13F filers whose holdings tables list its CUSIP, the change, and a sample of holders (Apple, Q2 2026: 6,776, up 1.9% on the quarter) | EDGAR full-text search over 13F information tables |
 | `forensic_scores` | Beneish's M-score, Piotroski's F-score and Altman's Z-score in one call, every input read from the company's annual XBRL with its tag, and missing inputs named rather than guessed | SEC XBRL company facts, price at the fiscal year end |
 | `funding_rates` | Crypto perpetual funding: each coin's latest eight-hour rate, the window's mean and annualized carry, the last week's, and the share of positive periods (BTC, 90 days to 2026-10-24: 5.6% a year) | OKX public data (no key) |
+| `compute_prices` | Compute as a market: the on-demand hourly price of each data-centre GPU across the clouds (cheapest, median and dearest, and who offers them), every provider's offer for one model, recent list-price changes, and the Cirrun GPU Index (H100 SXM, 2026-10-24: $1.99 to $12.29 an hour, median $3.95) | Cirrun's GPU price index (no key, CC BY 4.0) |
 | `federal_contracts` | What the US government obligated to a company in a fiscal year: the total, by agency and industry code, the entities it contracts under, and its largest contracts with links (Lockheed Martin, fiscal 2026: $53.2 billion from Defense) | USAspending.gov (no key) |
 | `drug_pipeline` | A drug company's active clinical trials by phase, the primary completions due in the coming months (the next readouts), its late-stage trials and its FDA approvals (Vertex: 31 active trials, 16 in phase 3) | ClinicalTrials.gov and Drugs@FDA (no key) |
 | `comment_letters` | What the SEC's staff questioned in a company's filings and how it answered, grouped into reviews, with the topics of the newest letters (Apple, 2024: revenue recognition, segments, MD&A) | SEC EDGAR forms UPLOAD and CORRESP |
+| `shareholder_returns` | What a company has paid its owners each year: dividends per share (with its split-adjusted record: years raised in a row, 5- and 10-year growth) and in total, buybacks and shares issued, the diluted share count, the payout ratio and the share of free cash flow paid out, and the dividend and shareholder yields at the last close | SEC XBRL company facts, the last close |
 | `reverse_dcf` | The free-cash-flow growth a share price implies: a DCF solved for the growth that reaches the market's enterprise value, every input from the annual XBRL with its tag, a sensitivity table and the company's own growth beside it | SEC XBRL company facts, the last close |
 | `filing_drift` | How a 10-K section's language drifts over several years: each year's change from the last (the measure Cohen, Malloy and Nguyen's "Lazy Prices" found preceded weaker returns), hedging and adverse words, readability, and a theme you name, with flags (Nvidia's risk factors: export-control sentences 8, 14, 37, 48, 51 over five reports) | SEC 10-K filings, computed on your machine |
 | `bank_financials` | A US bank's condition quarter by quarter from its call reports: assets, deposits and the share uninsured, loans and the share noncurrent, earnings, margin, returns and capital ratios; with no bank, the latest failures and their cost (Western Alliance, June 2026: 38% of deposits uninsured, tier 1 leverage 8.1%) | FDIC BankFind (no key) |
@@ -116,6 +118,7 @@ against the BIS (21 of 21 agreed on 2026-10-15).
 | `options_chain` | An option chain with IV, greeks, open interest, put/call ratios, max pain and the expected move | Cboe delayed quotes |
 | `volatility_surface` | Implied volatility term structure, 25-delta skew and the smile | Cboe delayed quotes |
 | `futures_curve` | The VIX futures curve (and other Cboe futures) against the index: contango or backwardation | Cboe settlements |
+| `market_overview` | The market at a glance: US indices and the VIX, the eleven sectors ranked by the month, Treasury yields, the dollar and major currencies, oil, gas, gold, silver, copper, bitcoin, ether and the main markets abroad, each over a day, a week, a month, three months, the year to date and a year | Yahoo Finance chart data (no key) |
 | `price_history` | Daily to monthly bars for stocks in the US and abroad, currencies, futures, indices and crypto, adjusted, with dividends and splits, as columns | Yahoo Finance (no key), or Alpaca or Tiingo (your key) for US stocks |
 | `treasury_auctions` | How each Treasury auction went (yield, bid-to-cover, who bought) and which auctions come next | US Treasury Fiscal Data |
 | `federal_debt` | The US debt each business day, and the average rate the Treasury pays on it | US Treasury Fiscal Data |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canli-markets-mcp",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "MCP server for markets, funds and the economy from the sources themselves, no key: European companies' ESEF annual reports, central-bank rates (SOFR, €STR, SONIA, 40 policy rates), Polymarket and Kalshi odds, DeFi value locked and fees, financial statements as filed, the tables in filings, earnings guidance as ranges and a draft's figures checked against the filings, options chains and volatility, short interest, dark pools, futures positioning, fund and ETF holdings, 13D/13G, earnings dates and 8-K press-release headlines, segment revenue, executive pay, Form D, the Fed, Treasury auctions, World Bank and OECD macro, screens, filings and prices. Every result cites its sources.",
   "private": false,
   "type": "module",

package/src/breadth.mjs

@@ -15,7 +15,7 @@ export const ownershipInput = z.object({
 }).strict();
 
 const EFTS = "https://efts.sec.gov/LATEST/search-index";
-const key = (s) => String(s ?? "").toUpperCase().replace(/&/g, " AND ").replace(/[^A-Z0-9 ]+/g, " ").replace(/\b(INC|CORP|CORPORATION|CO|COMPANY|LTD|PLC|HOLDINGS?|GROUP|THE|CL [A-C]|CLASS [A-C]|COM|NEW|DEL)\b/g, " ").replace(/\s+/g, " ").trim();
+const key = (s) => String(s ?? "").replace(/&(amp|apos|#39);/gi, (_, e) => (e.toLowerCase() === "amp" ? "&" : "'")).toUpperCase().replace(/\/[A-Z]{2,3}\/?/g, " ").replace(/&/g, " AND ").replace(/[^A-Z0-9 ]+/g, " ").replace(/\b(INC|CORP|CORPORATION|CO|COMPANY|LTD|PLC|HOLDINGS?|GROUP|THE|CL [A-C]|CLASS [A-C]|COM|NEW|DEL)\b/g, " ").replace(/\s+/g, " ").trim();
 
 // 13F reports are due 45 days after a quarter ends: filings made in a calendar quarter report the
 // quarter before it. Each window is a calendar quarter of filing dates.
@@ -33,35 +33,90 @@ export function filingQuarters(today, n) {
   return out;
 }
 
-// The CUSIP 13F filers give a company: from information tables that name it, the CUSIP most often
-// beside a matching issuer name.
+// 13F tables shorten issuer names ("COSTCO WHSL CORP NEW" for Costco Wholesale): two names match when
+// they have the same words, each the same or one an abbreviation of the other (its letters in order,
+// starting with the same letter), and the same first word.
+const abbreviates = (a, b) => { if (a.length > b.length) [a, b] = [b, a]; if (a.length < 2 || a[0] !== b[0]) return false; let i = 0; for (const ch of b) if (ch === a[i]) i += 1; return i === a.length; };
+export function sameIssuer(a, b) {
+  const x = key(a).split(" ").filter(Boolean), y = key(b).split(" ").filter(Boolean);
+  return x.length > 0 && x.length === y.length && x[0] === y[0] && x.every((w, i) => w === y[i] || abbreviates(w, y[i]));
+}
+// A CUSIP's ninth character is a check digit (the "modulus 10 double add double" of the first eight).
+export function cusipValid(c) {
+  if (!/^[0-9A-Z*@#]{8}[0-9]$/.test(c)) return false;
+  let sum = 0;
+  for (let i = 0; i < 8; i += 1) {
+    const ch = c[i], v = /\d/.test(ch) ? Number(ch) : /[A-Z]/.test(ch) ? ch.charCodeAt(0) - 55 : { "*": 36, "@": 37, "#": 38 }[ch];
+    const d = i % 2 ? v * 2 : v;
+    sum += Math.floor(d / 10) + (d % 10);
+  }
+  return (10 - (sum % 10)) % 10 === Number(c[8]);
+}
+
+// The CUSIP 13F filers give a company: from information tables that name it, the valid CUSIP most
+// often beside a matching issuer name, and the other classes seen (Alphabet's A and C shares share a
+// name). The search is by the name's first word, since the tables abbreviate the rest; the company's
+// own 13Fs are skipped (a bank's or insurer's can be too large to read).
 async function cusipOf(session, name) {
-  const p = new URLSearchParams({ q: `"${name}"`, forms: "13F-HR" });
-  const r = await getJson(session, `${EFTS}?${p}`);
-  const want = key(name), votes = new Map();
-  for (const h of (r?.hits?.hits ?? []).slice(0, 4)) {
+  const words = key(name).split(" ").filter(Boolean);
+  // The first two words as a phrase when there are two ("JPMORGAN CHASE", not every JPMorgan ETF), then
+  // the first alone ("COSTCO", whose tables say "COSTCO WHSL").
+  const queries = [...new Set([words.slice(0, 2).join(" "), words[0]].filter(Boolean))];
+  // Last year's filings only: their information tables are XML, and the CUSIP is the current one.
+  const day = (t) => new Date(t).toISOString().slice(0, 10), now = session.now();
+  const hits = [];
+  for (const q of queries) {
+    const p = new URLSearchParams({ q: `"${q}"`, forms: "13F-HR", dateRange: "custom", startdt: day(now - 400 * 86400000), enddt: day(now) });
+    hits.push(...((await getJson(session, `${EFTS}?${p}`))?.hits?.hits ?? []).filter((h) => /\.xml$/i.test(String(h._id))));
+  }
+  const votes = new Map(), seen = new Set();
+  let read = 0, matched = 0;
+  for (const h of hits) {
+    if (read >= 8) break;
+    if (seen.has(h._id)) continue;
+    seen.add(h._id);
+    const filer = (h._source.display_names ?? [])[0]?.replace(/\s+\(CIK \d+\)$/, "") ?? "";
+    if (sameIssuer(filer, name)) continue;
     const [adsh, file] = String(h._id).split(":");
     const cik = Number((h._source.ciks ?? [])[0]);
     if (!adsh || !file || !cik) continue;
+    read += 1;
     const xml = await getText(session, `https://www.sec.gov/Archives/edgar/data/${cik}/${adsh.replace(/-/g, "")}/${file}`, { maxBytes: 8 * 1024 * 1024 }).catch(() => "");
+    const here = new Map();
     for (const m of xml.matchAll(/<(?:\w+:)?infoTable>([\s\S]*?)<\/(?:\w+:)?infoTable>/g)) {
       const issuer = /<(?:\w+:)?nameOfIssuer>([^<]*)</.exec(m[1])?.[1], cusip = /<(?:\w+:)?cusip>([^<]*)</.exec(m[1])?.[1]?.trim().toUpperCase();
-      if (issuer && cusip && key(issuer) === want) votes.set(cusip, (votes.get(cusip) ?? 0) + 1);
+      const title = /<(?:\w+:)?titleOfClass>([^<]*)</.exec(m[1])?.[1]?.trim() ?? null;
+      if (!issuer || !cusip || !cusipValid(cusip) || !sameIssuer(issuer, name)) continue;
+      if (!here.has(cusip)) here.set(cusip, title);
+    }
+    // One vote per table, and three tables that name it: one filer's slip does not decide it.
+    for (const [cusip, title] of here) { const v = votes.get(cusip) ?? { cusip, title_of_class: title, tables: 0 }; v.tables += 1; votes.set(cusip, v); }
+    if (here.size) matched += 1;
+    if (matched >= 3) break;
+  }
+  let classes = [...votes.values()].sort((a, b) => b.tables - a.tables).slice(0, 4);
+  // More than one: the one most filers list in the latest quarter (a class most hold, or the CUSIP
+  // most still use after a change), each with its count.
+  if (classes.length > 1) {
+    const w = filingQuarters(now, 1)[0];
+    for (const c of classes) {
+      const p = new URLSearchParams({ q: `"${c.cusip}"`, forms: "13F-HR", dateRange: "custom", startdt: w.filed_from, enddt: w.filed_to });
+      c.filers = (await getJson(session, `${EFTS}?${p}`))?.hits?.total?.value ?? 0;
     }
-    if (votes.size) break;
+    classes = classes.sort((a, b) => b.filers - a.filers);
   }
-  return [...votes].sort((a, b) => b[1] - a[1])[0]?.[0] ?? null;
+  return { cusip: classes[0]?.cusip ?? null, classes };
 }
 
 export async function ownershipBreadth(session, args) {
   const a = ownershipInput.parse(args);
   if (!a.company && !a.cusip) throw new Error("ownership_breadth needs company or cusip.");
-  let who = null, cusip = a.cusip?.toUpperCase() ?? null;
+  let who = null, cusip = a.cusip?.toUpperCase() ?? null, classes = null;
   if (a.company) {
     const e = await resolveEntity(session, a.company);
     who = { cik: e.cik, name: e.name, ticker: e.ticker ?? null };
     if (!cusip) {
-      cusip = await cusipOf(session, e.name ?? a.company);
+      ({ cusip, classes } = await cusipOf(session, e.name ?? a.company));
       if (!cusip) throw new Error(`No 13F information table names ${e.name ?? a.company} in a way that gives its CUSIP; pass cusip (the share class's 9-character CUSIP).`);
     }
   }
@@ -76,13 +131,18 @@ export async function ownershipBreadth(session, args) {
     latest ??= r;
   }
   const counts = rows.map((x) => x[3]);
+  // Filers in recent quarters and none before: a CUSIP new in that time (a company's CUSIP changes in a
+  // reorganisation or redomicile), not a jump in ownership.
+  const firstSeen = counts.findIndex((n, i) => n > 0 && counts.slice(i + 1).length > 0 && counts.slice(i + 1).every((m) => m === 0));
   const change = counts.length > 1 && counts[1] ? Math.round((counts[0] / counts[1] - 1) * 10000) / 10000 : null;
   const holders = (latest?.hits?.hits ?? []).slice(0, a.holders ?? 20).map((h) => [(h._source.display_names ?? [])[0]?.replace(/\s+\(CIK \d+\)$/, "").replace(/\s+/g, " ") ?? null, Number((h._source.ciks ?? [])[0]) || null, h._source.file_date, String(h._id).split(":")[0]]);
   return {
     ...(who ? { company: who } : {}), cusip,
+    ...(classes?.length > 1 ? { other_cusips: { note: "CUSIPs 13F tables list under this name (share classes, or a CUSIP that changed); the one most filers list in the latest quarter is counted. Pass cusip to count another.", columns: ["cusip", "title_of_class", "filers_latest_quarter"], rows: classes.map((c) => [c.cusip, c.title_of_class, c.filers]) } } : {}),
     columns: ["holdings_quarter", "filed_from", "filed_to", "filers", "at_least"],
     rows,
     change_latest_vs_prior: change,
+    ...(firstSeen >= 0 ? { warning: `No 13F lists ${cusip} before ${rows[firstSeen][0]}: a CUSIP new then, as when a company's CUSIP changes in a reorganisation; earlier quarters were filed under the old one (pass it as cusip to count them).` } : {}),
     holders_sample: { note: "13F filers whose latest-quarter information table lists the CUSIP, in search order (not by size).", columns: ["manager", "cik", "filed", "accession"], rows: holders },
     meaning: "filers counts the 13F information tables filed in each window that list the CUSIP: the number of institutions (managers with over $100 million in US equities) reporting the stock. The newest window may still be filling: 13Fs are due 45 days after the quarter. Chen, Hong and Stein (2002): a fall in breadth predicted lower returns.",
     source: `${EFTS} (EDGAR full-text search over 13F information tables)`,

package/src/compute.mjs

@@ -0,0 +1,85 @@
+// Compute as a market: what an hour of each data-centre GPU costs on demand across the clouds, and
+// the Cirrun GPU Index, a daily chained index of those prices (public data, no key, CC BY 4.0).
+// Every price is the provider's own list price, confirmed on its pricing page on the date shown.
+import { z } from "zod";
+
+import { getJson, getText } from "./sources.mjs";
+
+const BASE = "https://cirrun.com/api/v1";
+
+export const computeInput = z.object({
+  gpu: z.string().min(2).max(40).regex(/^[A-Za-z0-9 .\-]+$/, "a GPU model such as H100 or B200").optional().describe("A GPU model (H100, H200, B200, A100, L40S, RTX 4090...): every provider's offer for it. Default: one row per model."),
+  provider: z.string().min(2).max(40).regex(/^[A-Za-z0-9 .\-]+$/, "a provider's name").optional().describe("Only this provider's offers, e.g. RunPod or AWS."),
+  changes: z.number().int().min(0).max(200).optional().describe("Latest list-price changes to return; default 20."),
+}).strict();
+
+const norm = (s) => String(s ?? "").toLowerCase().replace(/[^a-z0-9]/g, "");
+const pct = (a, b) => (Number.isFinite(a) && Number.isFinite(b) && b ? Math.round((a / b - 1) * 1e4) / 1e4 : null);
+
+function parseCsv(text) {
+  const rows = [];
+  for (const line of String(text).split(/\r?\n/).filter(Boolean)) {
+    const out = [];
+    let cur = "", quoted = false;
+    for (let i = 0; i < line.length; i += 1) {
+      const ch = line[i];
+      if (quoted) { if (ch === "\"" && line[i + 1] === "\"") { cur += "\""; i += 1; } else if (ch === "\"") quoted = false; else cur += ch; }
+      else if (ch === "\"") quoted = true;
+      else if (ch === ",") { out.push(cur); cur = ""; }
+      else cur += ch;
+    }
+    out.push(cur);
+    rows.push(out);
+  }
+  return rows;
+}
+
+export async function computePrices(session, args) {
+  const a = computeInput.parse(args);
+  const [ref, prices] = await Promise.all([getJson(session, `${BASE}/reference`), getJson(session, `${BASE}/prices`)]);
+  const byProvider = (p) => !a.provider || norm(p).includes(norm(a.provider));
+  const index = ref.index ?? {};
+  const out = {
+    date: ref.date ?? null, currency: ref.currency ?? "USD", unit: ref.unit ?? "per GPU-hour, on-demand list price",
+    index: { name: index.name ?? "Cirrun GPU Index", level: index.level ?? null, started: index.started ?? null, start_level: index.start_level ?? null, gpu_models: index.gpu_models ?? null, offers: index.offers ?? null },
+  };
+  if (a.gpu) {
+    const partial = (prices.gpus ?? []).filter((x) => norm(x.name).includes(norm(a.gpu)));
+    const g = (prices.gpus ?? []).find((x) => norm(x.name) === norm(a.gpu) || norm(x.id) === norm(a.gpu)) ?? partial[0];
+    if (g && partial.length > 1 && norm(g.name) !== norm(a.gpu)) out.also_matched = partial.filter((x) => x !== g).map((x) => x.name);
+    if (!g) throw new Error(`No GPU model ${a.gpu} in the index; models: ${(prices.gpus ?? []).map((x) => x.name).join(", ")}.`);
+    const summary = (ref.gpus ?? []).find((x) => norm(x.gpu) === norm(g.name)) ?? {};
+    const rows = (g.rows ?? []).filter((r) => byProvider(r[0])).map(([provider, tier, price, billing, confirmed]) => [provider, tier, price, prices.billing?.[billing] ?? billing, confirmed]).sort((x, y) => x[2] - y[2]);
+    Object.assign(out, {
+      gpu: g.name, vram_gb: g.vram ?? summary.vram_gb ?? null,
+      summary: { offers: summary.offers ?? rows.length, low: summary.low ?? null, low_from: summary.low_from ?? null, median: summary.median ?? null, high: summary.high ?? null, high_from: summary.high_from ?? null, low_datacentre: summary.low_datacentre ?? null, low_datacentre_from: summary.low_datacentre_from ?? null, median_change_since_first_day: pct(summary.median, summary.first_day_median), first_day: summary.first_day ?? null },
+      columns: ["provider", "tier", "price", "billing", "confirmed"], rows,
+      sources: Object.fromEntries(Object.entries(prices.sources ?? {}).filter(([p]) => rows.some((r) => r[0] === p))),
+    });
+  } else {
+    const rows = (ref.gpus ?? []).map((x) => [x.gpu, x.vram_gb ?? null, x.offers ?? null, x.low ?? null, x.low_from ?? null, x.median ?? null, x.high ?? null, x.high_from ?? null, x.low_datacentre ?? null, pct(x.median, x.first_day_median)]);
+    Object.assign(out, { columns: ["gpu", "vram_gb", "offers", "low", "low_from", "median", "high", "high_from", "low_datacentre", "median_change_since_first_day"], rows });
+    if (a.provider) {
+      const offers = [];
+      for (const g of prices.gpus ?? []) for (const [provider, tier, price, billing, confirmed] of g.rows ?? []) if (byProvider(provider)) offers.push([g.name, provider, tier, price, prices.billing?.[billing] ?? billing, confirmed]);
+      if (!offers.length) throw new Error(`No offers from ${a.provider}; providers: ${Object.keys(prices.sources ?? {}).join(", ")}.`);
+      out.provider_offers = { columns: ["gpu", "provider", "tier", "price", "billing", "confirmed"], rows: offers.sort((x, y) => x[3] - y[3]) };
+    }
+  }
+  const n = a.changes ?? 20;
+  if (n) {
+    try {
+      const [head, ...body] = parseCsv(await getText(session, `${BASE}/changes.csv`, { maxBytes: 4 * 1024 * 1024 }));
+      const at = (k) => head.indexOf(k);
+      const rows = body.filter((r) => (!a.gpu || norm(r[at("gpu")]) === norm(out.gpu)) && byProvider(r[at("provider")])).map((r) => [r[at("date")], r[at("gpu")], r[at("provider")], r[at("tier")], Number(r[at("old")]) || null, Number(r[at("new")]) || null, pct(Number(r[at("new")]), Number(r[at("old")]))]);
+      out.changes = { note: "List-price changes the daily check found, newest first.", columns: ["date", "gpu", "provider", "tier", "old", "new", "change"], rows: rows.reverse().slice(0, n) };
+    } catch (err) { out.changes = { not_read: String(err.message).slice(0, 160) }; }
+  }
+  return {
+    ...out,
+    method: ref.method ?? null,
+    source: `${BASE}/reference and ${BASE}/prices (Cirrun GPU price index)`,
+    cite: ref.cite ?? "Cirrun GPU price index, https://cirrun.com/prices.html, CC BY 4.0",
+    limits: ["On-demand list prices from each provider's pricing page; spot, reserved and negotiated prices are lower, and availability is not shown.", "The index began on 2026-10-23, so its history is short.", "Not investment advice."],
+  };
+}

package/src/news.mjs

@@ -51,8 +51,9 @@ function refused(err) {
   return /429/.test(String(err?.message)) ? new Error("GDELT is limiting requests from this address (HTTP 429); it allows about one every five seconds. Ask again in a minute.") : err;
 }
 
-// attempts: GDELT requests to try before giving up (explain_move asks once, to stay quick).
-export async function news(session, args, { attempts = 2 } = {}) {
+// attempts: GDELT requests to try before giving up, each after a longer wait (GDELT counts requests
+// per address and often refuses one in a burst); explain_move asks once, to stay quick.
+export async function news(session, args, { attempts = 3 } = {}) {
   const a = newsInput.parse(args);
   if (!a.query && !a.company) throw new Error("news needs query or company.");
   let who = null;

package/src/overview.mjs

@@ -0,0 +1,62 @@
+// The market at a glance: the main US indices and volatility, the eleven S&P sectors (by their SPDR
+// funds), Treasury yields, the dollar, oil, gold and copper, bitcoin and ether, and the main markets
+// abroad, each with its last close and its change over a day, a week, a month, three months, the
+// year to date and a year. Prices are daily closes from price_history's sources; nothing is a quote.
+import { z } from "zod";
+
+import { priceHistory } from "./tools.mjs";
+
+export const GROUPS = Object.freeze({
+  us: [["^GSPC", "S&P 500"], ["^IXIC", "Nasdaq Composite"], ["^NDX", "Nasdaq 100"], ["^DJI", "Dow Jones Industrial Average"], ["^RUT", "Russell 2000"], ["^VIX", "VIX (S&P 500 volatility)"]],
+  sectors: [["XLK", "Technology"], ["XLC", "Communication services"], ["XLY", "Consumer discretionary"], ["XLP", "Consumer staples"], ["XLF", "Financials"], ["XLV", "Health care"], ["XLI", "Industrials"], ["XLE", "Energy"], ["XLB", "Materials"], ["XLU", "Utilities"], ["XLRE", "Real estate"]],
+  rates: [["^IRX", "13-week Treasury bill yield"], ["^FVX", "5-year Treasury yield"], ["^TNX", "10-year Treasury yield"], ["^TYX", "30-year Treasury yield"]],
+  currencies: [["DX-Y.NYB", "US dollar index"], ["EURUSD=X", "EUR/USD"], ["USDJPY=X", "USD/JPY"], ["GBPUSD=X", "GBP/USD"]],
+  commodities: [["CL=F", "WTI crude oil"], ["BZ=F", "Brent crude oil"], ["NG=F", "US natural gas"], ["GC=F", "Gold"], ["SI=F", "Silver"], ["HG=F", "Copper"]],
+  crypto: [["BTC-USD", "Bitcoin"], ["ETH-USD", "Ether"]],
+  world: [["^STOXX50E", "Euro Stoxx 50"], ["^FTSE", "FTSE 100"], ["^GDAXI", "DAX"], ["^N225", "Nikkei 225"], ["^HSI", "Hang Seng"], ["000001.SS", "Shanghai Composite"], ["^BSESN", "Sensex"]],
+});
+// Yields are quoted in percent, so their changes are in percentage points, not percent of the level.
+const YIELDS = new Set(GROUPS.rates.map(([s]) => s));
+
+export const overviewInput = z.object({
+  groups: z.array(z.enum(Object.keys(GROUPS))).min(1).max(7).optional().describe(`Which groups to show (${Object.keys(GROUPS).join(", ")}); default all.`),
+}).strict();
+
+const round = (x, d = 4) => (Number.isFinite(x) ? Math.round(x * 10 ** d) / 10 ** d : null);
+
+// Changes from closes (oldest first) to the last: n sessions back, and from the last close of the
+// year before the last date's.
+export function changes(dates, closes, { points = false } = {}) {
+  const last = closes.at(-1), at = (n) => closes.at(-1 - n);
+  const year = dates.at(-1).slice(0, 4), before = dates.findLastIndex((d) => d.slice(0, 4) < year);
+  const ch = (base) => (base == null || !Number.isFinite(base) ? null : points ? round(last - base, 3) : base ? round(last / base - 1) : null);
+  return { day: ch(at(1)), week: ch(at(5)), month: ch(at(21)), three_months: ch(at(63)), year_to_date: ch(before >= 0 ? closes[before] : null), year: ch(at(252)) };
+}
+
+export async function marketOverview(session, args) {
+  const a = overviewInput.parse(args ?? {});
+  const groups = a.groups ?? Object.keys(GROUPS);
+  const start = new Date(session.now() - 400 * 86400000).toISOString().slice(0, 10);
+  const sources = new Set(), missing = [];
+  const out = {};
+  await Promise.all(groups.map(async (g) => {
+    const rows = await Promise.all(GROUPS[g].map(async ([symbol, name]) => {
+      const p = await priceHistory(session, { symbol, start, adjusted: false }).catch((err) => { missing.push(`${symbol}: ${String(err.message).slice(0, 120)}`); return null; });
+      if (!p?.close?.length) return null;
+      if (p.source) sources.add(p.source);
+      const c = changes(p.dates, p.close, { points: YIELDS.has(symbol) });
+      return [symbol, name, p.dates.at(-1), round(p.close.at(-1), 4), c.day, c.week, c.month, c.three_months, c.year_to_date, c.year];
+    }));
+    out[g] = rows.filter(Boolean);
+    // Sectors are easiest read best to worst over the month.
+    if (g === "sectors") out[g].sort((x, y) => (y[6] ?? -Infinity) - (x[6] ?? -Infinity));
+  }));
+  return {
+    columns: ["symbol", "name", "date", "close", "day", "week", "month", "three_months", "year_to_date", "year"],
+    ...Object.fromEntries(groups.map((g) => [g, out[g]])),
+    ...(missing.length ? { missing } : {}),
+    meaning: "Changes are close to close over 1, 5, 21, 63 and 252 sessions and from the last close of the year before, as fractions (0.012 is 1.2%); for Treasury yields (quoted in percent) they are percentage points. Sectors are ranked by the month. Dates are each market's last close, so markets abroad and crypto can be a day apart.",
+    sources: [...sources],
+    limits: ["Daily closes, not live quotes; intraday moves are not shown.", "Index levels are price indices, without dividends; sector funds are SPDR ETFs.", "Not investment advice."],
+  };
+}

package/src/payouts.mjs

@@ -0,0 +1,140 @@
+// Shareholder returns: what a company has paid its owners, year by year, from its own annual XBRL.
+// Dividends per share and in total, buybacks and new shares issued, the share count, and those set
+// against earnings and free cash flow; with the last close, the dividend yield and the shareholder
+// yield (dividends plus net buybacks over the market value). Each figure names its tag.
+import { z } from "zod";
+
+import { getJson, resolveEntity, tickerTable } from "./sources.mjs";
+import { priceHistory } from "./tools.mjs";
+
+export const payoutsInput = z.object({
+  company: z.string().min(1).max(120).describe("Ticker, CIK or name."),
+  years: z.number().int().min(2).max(20).optional().describe("Fiscal years to show, newest first; default 10."),
+  price: z.boolean().optional().describe("Add the dividend and shareholder yields at the last close; default true."),
+}).strict();
+
+const ANNUAL = new Set(["10-K", "10-K/A", "20-F", "20-F/A", "40-F", "40-F/A"]);
+const days = (a, b) => (Date.parse(a) - Date.parse(b)) / 86400000;
+// [tags, unit, flow]: a flow is a full fiscal year (a duration of about a year), the rest are balances.
+export const MEASURES = {
+  dps_declared: [["CommonStockDividendsPerShareDeclared"], "USD/shares", true],
+  dps_paid: [["CommonStockDividendsPerShareCashPaid"], "USD/shares", true],
+  dividends_paid: [["PaymentsOfDividendsCommonStock", "PaymentsOfDividends", "PaymentsOfOrdinaryDividends"], "USD", true],
+  buybacks: [["PaymentsForRepurchaseOfCommonStock", "PaymentsForRepurchaseOfEquity"], "USD", true],
+  issued: [["ProceedsFromIssuanceOfCommonStock", "ProceedsFromStockOptionsExercised", "ProceedsFromIssuanceOfSharesUnderIncentiveAndShareBasedCompensationPlans"], "USD", true],
+  net_income: [["NetIncomeLoss", "ProfitLoss", "NetIncomeLossAvailableToCommonStockholdersBasic"], "USD", true],
+  cfo: [["NetCashProvidedByUsedInOperatingActivities", "NetCashProvidedByUsedInOperatingActivitiesContinuingOperations"], "USD", true],
+  capex: [["PaymentsToAcquirePropertyPlantAndEquipment", "PaymentsToAcquireProductiveAssets"], "USD", true],
+  diluted_shares: [["WeightedAverageNumberOfDilutedSharesOutstanding"], "shares", true],
+};
+const round = (x, d = 4) => (Number.isFinite(x) ? Math.round(x * 10 ** d) / 10 ** d : null);
+
+// One measure's annual values by fiscal-year end (the latest filing's figure for each), from the tag
+// the company reports most recently.
+export function annualValues(facts, name) {
+  const [tags, unit, flow] = MEASURES[name];
+  let best = null;
+  for (const tag of tags) {
+    const rows = (facts[tag]?.units?.[unit] ?? []).filter((x) => ANNUAL.has(x.form) && (flow ? x.start && days(x.end, x.start) >= 350 && days(x.end, x.start) <= 380 : !x.start));
+    if (!rows.length) continue;
+    const by = new Map();
+    for (const r of rows) if (!by.has(r.end) || r.filed > by.get(r.end).filed) by.set(r.end, r);
+    const values = new Map([...by].sort((x, y) => x[0].localeCompare(y[0])).map(([end, r]) => [end, r.val]));
+    const last = [...values.keys()].at(-1);
+    if (!best || last > best.last || (last === best.last && values.size > best.values.size)) best = { tag, values, last };
+  }
+  return best && { tag: best.tag, values: best.values };
+}
+
+// Years in a row, back from the latest, that the yearly dividend per share rose (a cut or a flat year
+// ends the run).
+export function raisedYears(dps) {
+  const v = [...dps.values()];
+  let n = 0;
+  for (let i = v.length - 1; i > 0 && v[i] > v[i - 1]; i -= 1) n += 1;
+  return n;
+}
+
+// Dividends per share on today's shares: a year whose diluted share count jumps by a whole factor
+// (2, 3, 4...) while the dividend per share falls by about the same is a split, and the years before
+// it are divided by the factor. Older 10-Ks are not restated, so without this a split reads as a cut.
+export function splitAdjusted(dps, shares) {
+  const ends = [...dps.keys()], out = new Map(dps), splits = [];
+  for (let i = ends.length - 1; i > 0; i -= 1) {
+    const s1 = shares?.get(ends[i]), s0 = shares?.get(ends[i - 1]), d1 = dps.get(ends[i]), d0 = dps.get(ends[i - 1]);
+    if (!s1 || !s0 || !d1 || !d0) continue;
+    const factor = Math.round(s1 / s0);
+    if (factor >= 2 && Math.abs(s1 / s0 / factor - 1) < 0.1 && d0 / d1 > factor * 0.6) {
+      splits.push({ fiscal_year_end: ends[i], factor });
+      for (const k of ends.slice(0, i)) out.set(k, out.get(k) / factor);
+    }
+  }
+  return { values: out, splits };
+}
+
+const cagr = (values, n) => {
+  const v = [...values.values()];
+  if (v.length < n + 1) return null;
+  const a = v.at(-1 - n), b = v.at(-1);
+  return a > 0 && b > 0 ? (b / a) ** (1 / n) - 1 : null;
+};
+
+// The dividend's record on split-adjusted figures: years raised in a row (within the years tagged in
+// XBRL, which began in 2009-2011) and its growth.
+function dividendRecord(dps, shares) {
+  const adj = splitAdjusted(dps, shares);
+  return {
+    raised_years_in_a_row: raisedYears(adj.values), years_tagged: adj.values.size,
+    growth_5y: round(cagr(adj.values, 5)), growth_10y: round(cagr(adj.values, 10)),
+    ...(adj.splits.length ? { splits_adjusted: adj.splits } : {}),
+  };
+}
+
+export async function shareholderReturns(session, args) {
+  const a = payoutsInput.parse(args);
+  const e = await resolveEntity(session, a.company);
+  const url = `https://data.sec.gov/api/xbrl/companyfacts/CIK${String(e.cik).padStart(10, "0")}.json`;
+  const cf = await getJson(session, url, { maxBytes: 96 * 1024 * 1024 });
+  const f = cf.facts?.["us-gaap"] ?? {};
+  const m = Object.fromEntries(Object.keys(MEASURES).map((k) => [k, annualValues(f, k)]));
+  const dps = m.dps_declared ?? m.dps_paid;
+  const ends = [...new Set(Object.values(m).filter(Boolean).flatMap((s) => [...s.values.keys()]))].sort();
+  if (!ends.length || !(m.dividends_paid || m.buybacks || dps)) throw new Error(`${cf.entityName ?? a.company} (CIK ${e.cik}) tags no annual dividends or buybacks in its XBRL.`);
+  const v = (k, end) => m[k]?.values.get(end) ?? null;
+  const rows = ends.slice(-(a.years ?? 10)).reverse().map((end, i, list) => {
+    const div = v("dividends_paid", end), back = v("buybacks", end), iss = v("issued", end), ni = v("net_income", end), cfo = v("cfo", end), capex = v("capex", end);
+    const fcf = cfo != null ? cfo - (capex ?? 0) : null, paid = (div ?? 0) + (back ?? 0);
+    const sh = v("diluted_shares", end), prior = list[i + 1] ? v("diluted_shares", list[i + 1]) : null;
+    return [end, dps?.values.get(end) ?? null, div, back, iss, round(ni ? (div ?? 0) / ni : null), round(fcf ? paid / fcf : null), sh, round(sh && prior ? sh / prior - 1 : null)];
+  });
+  let yields = null;
+  if (a.price !== false) {
+    const symbol = e.ticker ?? Object.values(await tickerTable(session)).find((t) => t.cik_str === e.cik)?.ticker;
+    const shares = (cf.facts?.dei?.EntityCommonStockSharesOutstanding?.units?.shares ?? []).sort((x, y) => (x.end < y.end ? 1 : -1))[0]?.val ?? null;
+    if (symbol && shares) {
+      const today = new Date(session.now()).toISOString().slice(0, 10);
+      const px = await priceHistory(session, { symbol, start: new Date(session.now() - 12 * 86400000).toISOString().slice(0, 10), end: today, adjusted: false }).catch(() => null);
+      const price = px?.close?.at(-1) ?? null, end = ends.at(-1);
+      if (price) {
+        const cap = price * shares, div = v("dividends_paid", end) ?? 0, net = (v("buybacks", end) ?? 0) - (v("issued", end) ?? 0);
+        yields = {
+          price, price_date: px?.dates?.at(-1) ?? px?.date?.at(-1) ?? null, market_value: round(cap, 0), fiscal_year_end: end,
+          dividend_yield: dps?.values.has(end) ? round(dps.values.get(end) / price) : round(div / cap),
+          net_buyback_yield: round(net / cap), shareholder_yield: round((div + net) / cap),
+          source: px?.source ?? null,
+        };
+      }
+    }
+  }
+  return {
+    company: { cik: e.cik, name: cf.entityName ?? e.name, ticker: e.ticker ?? null },
+    columns: ["fiscal_year_end", "dividend_per_share", "dividends_paid", "buybacks", "shares_issued_for_cash", "payout_ratio", "paid_out_of_free_cash_flow", "diluted_shares", "diluted_shares_change"],
+    rows,
+    dividends: dps ? { per_share_tag: dps.tag, ...dividendRecord(dps.values, m.diluted_shares?.values) } : { note: "No dividend per share tagged for full years." },
+    ...(yields ? { yields } : {}),
+    tags: Object.fromEntries(Object.entries(m).map(([k, s]) => [k, s?.tag ?? null])),
+    sources: [url, ...(yields?.source ? [yields.source] : [])],
+    meaning: "payout_ratio is common dividends paid over net income; paid_out_of_free_cash_flow is dividends plus buybacks over operating cash flow less capital spending (above 1 means more was paid out than the business made in cash). A falling diluted share count means buybacks outran new shares. shareholder_yield is the latest year's dividends plus buybacks less shares issued for cash, over the market value at the last close.",
+    limits: ["Figures are the full fiscal years in annual reports; the current year's payments are not in until its 10-K.", "Dividends per share are as declared (or paid, when only that is tagged) and are not adjusted for later splits; a split shows as a step in the share count.", "Buybacks are cash paid for repurchases, which can include shares withheld for taxes on stock awards.", "For banks, brokers and insurers, operating cash flow moves with loans, deposits and trading, so paid_out_of_free_cash_flow says little; use payout_ratio.", "raised_years_in_a_row counts only the years tagged in XBRL (filings since 2009-2011), so a longer record is cut at its start.", "Not investment advice."],
+  };
+}

package/src/server.mjs

@@ -27,6 +27,9 @@ import * as DB from "./credit.mjs";
 import * as OB from "./breadth.mjs";
 import * as FO from "./forensic.mjs";
 import * as FU from "./funding.mjs";
+import * as CO from "./compute.mjs";
+import * as PO from "./payouts.mjs";
+import * as MO from "./overview.mjs";
 import * as FC from "./contracts.mjs";
 import * as PL from "./pipeline.mjs";
 import * as CL from "./letters.mjs";
@@ -56,7 +59,7 @@ import * as CR from "./crypto.mjs";
 
 export const SERVER_NAME = "canli-markets-mcp";
 export const SERVER_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
-export const SERVER_INSTRUCTIONS = "Market data and research from the public sources themselves. Before answering with a company's reported figures, check them with verify_claims: each comes back confirmed, contradicted (with the filed figure and what the wrong one matches) or not reported. Across the market: screen_companies ranks every US-listed company on fundamentals, company_report gives one company's financials, segment_revenue its revenue by segment, product and region, valuation, risk, insiders and filings in one call, event_study measures price reactions to earnings or insider trades, mentions_trend counts a phrase in filings over time. Analyst work: financial_statements gives the income statement, balance sheet and cash flows exactly as filed (several years joined, restatements and splits shown, never mixed); filing_tables finds the table that holds a figure in a filing, or follows it through several years of filings (members, stores, ARPU, guidance tables); earnings_release reads a results press release: results, guidance as ranges, and last quarter's guidance against this quarter's results. Companies: company_profile, list_filings, then read_filing (section \"risk factors\", \"md&a\" and so on for a 10-K or 10-Q; document \"EX-99.1\" for an 8-K press release); search_filings finds words across all filings; executive_pay reads a proxy's pay-versus-performance table; company_events gives a company's 8-K news (or, by event, the whole market's: restatements, bankruptcies, cyber incidents); latest_filings is what has just been filed, across every company, by form and event; filing_diff shows what changed in a 10-K's risk factors (or any item) since the last one; filing_drift follows a section over several years (how much its wording moved, hedging, readability, and a theme such as \"supply chain\"), flagging the years and themes that moved most; news gives the world's press coverage of a company or topic, with its tone; explain_move puts a day's move beside the filings and headlines around it; portfolio_xray opens a portfolio's funds into the companies they hold; comps sets a company beside its industry peers; debt_profile gives its debt, when it falls due and what it costs; ownership_breadth counts the institutions holding it, quarter by quarter; forensic_scores runs the Beneish, Piotroski and Altman screens on its filings; reverse_dcf solves for the growth its share price implies; comment_letters gives what the SEC questioned in its filings and how it answered; federal_contracts what the US government paid it (USAspending); drug_pipeline a drug company's active trials by phase, its next readouts and its FDA approvals; bank_financials a US bank's quarterly call-report condition (uninsured deposits, bad loans, capital ratios) or the latest bank failures (FDIC). earnings_calendar gives a company's results dates and the next one estimated, or who reports in a window. Ownership: insider_trades (Form 4), planned_insider_sales (Form 144, filed before an insider sells) and fund_holdings (a manager's 13F); large_holders (13D/13G: 5 percent holders and activists), investment_advisers (Form ADV); funds: fund_portfolio (what a mutual fund or ETF holds, its flows and returns, from N-PORT); private markets: private_offerings (Form D raises by startups and funds) and ipo_pipeline (S-1/F-1 registrations and priced IPOs); positioning: short_interest, off_exchange_volume (FINRA dark pools), fails_to_deliver (SEC) and futures_positioning (CFTC Commitments of Traders). Rates and the economy: economic_calendar (when the data comes out), fomc (the Fed's decisions, votes and projections), treasury_yields, treasury_auctions, federal_debt, economic_series (FRED), world_economy (World Bank, every country) and economic_outlook (OECD projections). Beyond the US: european_filings (a company's ESEF annual report, the figures it tagged), reference_rates (SOFR, EFFR, €STR, ECB and Bank of England rates from the central banks, and about forty central banks' policy rates), prediction_markets (Polymarket and Kalshi prices for an outcome) and crypto_fundamentals (DefiLlama: a protocol's value locked, fees and revenue, a chain's value locked, a stablecoin's supply) and funding_rates (perpetual funding and its annualized carry, OKX). Options: options_chain, volatility_surface and futures_curve (Cboe delayed data). Prices: price_history for stocks in the US and abroad, currencies, futures, indices and crypto (no key needed; the user's Alpaca or Tiingo key is used for US stocks when set). Every result has its source URL; cite it.";
+export const SERVER_INSTRUCTIONS = "Market data and research from the public sources themselves. Before answering with a company's reported figures, check them with verify_claims: each comes back confirmed, contradicted (with the filed figure and what the wrong one matches) or not reported. Across the market: screen_companies ranks every US-listed company on fundamentals, company_report gives one company's financials, segment_revenue its revenue by segment, product and region, valuation, risk, insiders and filings in one call, event_study measures price reactions to earnings or insider trades, mentions_trend counts a phrase in filings over time. Analyst work: financial_statements gives the income statement, balance sheet and cash flows exactly as filed (several years joined, restatements and splits shown, never mixed); filing_tables finds the table that holds a figure in a filing, or follows it through several years of filings (members, stores, ARPU, guidance tables); earnings_release reads a results press release: results, guidance as ranges, and last quarter's guidance against this quarter's results. Companies: company_profile, list_filings, then read_filing (section \"risk factors\", \"md&a\" and so on for a 10-K or 10-Q; document \"EX-99.1\" for an 8-K press release); search_filings finds words across all filings; executive_pay reads a proxy's pay-versus-performance table; company_events gives a company's 8-K news (or, by event, the whole market's: restatements, bankruptcies, cyber incidents); latest_filings is what has just been filed, across every company, by form and event; filing_diff shows what changed in a 10-K's risk factors (or any item) since the last one; filing_drift follows a section over several years (how much its wording moved, hedging, readability, and a theme such as \"supply chain\"), flagging the years and themes that moved most; news gives the world's press coverage of a company or topic, with its tone; explain_move puts a day's move beside the filings and headlines around it; portfolio_xray opens a portfolio's funds into the companies they hold; comps sets a company beside its industry peers; debt_profile gives its debt, when it falls due and what it costs; ownership_breadth counts the institutions holding it, quarter by quarter; forensic_scores runs the Beneish, Piotroski and Altman screens on its filings; reverse_dcf solves for the growth its share price implies; shareholder_returns what it has paid its owners each year (dividends, buybacks, the share count, payout ratios, its dividend record and yields); comment_letters gives what the SEC questioned in its filings and how it answered; federal_contracts what the US government paid it (USAspending); drug_pipeline a drug company's active trials by phase, its next readouts and its FDA approvals; bank_financials a US bank's quarterly call-report condition (uninsured deposits, bad loans, capital ratios) or the latest bank failures (FDIC). earnings_calendar gives a company's results dates and the next one estimated, or who reports in a window. Ownership: insider_trades (Form 4), planned_insider_sales (Form 144, filed before an insider sells) and fund_holdings (a manager's 13F); large_holders (13D/13G: 5 percent holders and activists), investment_advisers (Form ADV); funds: fund_portfolio (what a mutual fund or ETF holds, its flows and returns, from N-PORT); private markets: private_offerings (Form D raises by startups and funds) and ipo_pipeline (S-1/F-1 registrations and priced IPOs); positioning: short_interest, off_exchange_volume (FINRA dark pools), fails_to_deliver (SEC) and futures_positioning (CFTC Commitments of Traders). Rates and the economy: economic_calendar (when the data comes out), fomc (the Fed's decisions, votes and projections), treasury_yields, treasury_auctions, federal_debt, economic_series (FRED), world_economy (World Bank, every country) and economic_outlook (OECD projections). Beyond the US: european_filings (a company's ESEF annual report, the figures it tagged), reference_rates (SOFR, EFFR, €STR, ECB and Bank of England rates from the central banks, and about forty central banks' policy rates), prediction_markets (Polymarket and Kalshi prices for an outcome) and crypto_fundamentals (DefiLlama: a protocol's value locked, fees and revenue, a chain's value locked, a stablecoin's supply) and funding_rates (perpetual funding and its annualized carry, OKX). Compute: compute_prices (what an hour of each data-centre GPU costs on demand across the clouds, and the Cirrun GPU Index). Options: options_chain, volatility_surface and futures_curve (Cboe delayed data). The market at a glance: market_overview (US indices and the VIX, the eleven sectors ranked by the month, Treasury yields, the dollar, oil, gold, bitcoin and markets abroad, each over a day, a week, a month, three months, the year to date and a year). Prices: price_history for stocks in the US and abroad, currencies, futures, indices and crypto (no key needed; the user's Alpaca or Tiingo key is used for US stocks when set). Every result has its source URL; cite it.";
 export const SERVER_INFO = Object.freeze({
   name: SERVER_NAME, version: SERVER_VERSION, title: "Canli Markets",
   websiteUrl: "https://canlicapital.com/developers",
@@ -100,6 +103,9 @@ export const TOOL_DESCRIPTIONS = Object.freeze({
   filing_drift: "How a 10-K section's language drifts over several years: each year's change from the year before (the Lazy Prices measure), hedging and adverse words, readability, and how much it says about a theme you name and how that wording moves, with flags for the years and themes that moved most.",
   planned_insider_sales: "Insiders' planned sales from Form 144, filed before they sell: seller, role, shares, market value, share of the company, approximate sale date, how the shares were acquired and any 10b5-1 plan date, with totals by seller.",
   ipo_pipeline: "The IPO pipeline from EDGAR: companies that filed or amended a registration (S-1, F-1) in a window, labelled IPO candidate, SPAC, fund or already listed, and offerings priced (424B4) with price, shares and proceeds from the prospectus cover.",
+  shareholder_returns: "What a company has paid its shareholders, year by year from its annual XBRL: dividends per share (split-adjusted record: years raised in a row, 5- and 10-year growth) and in total, buybacks and shares issued for cash, the diluted share count and its change, the payout ratio and the share of free cash flow paid out, and at the last close the dividend yield and shareholder yield.",
+  market_overview: "The market at a glance, no key: the S&P 500, Nasdaq, Dow, Russell 2000 and VIX, the eleven S&P sectors (SPDR funds) ranked by the month, Treasury yields from 13 weeks to 30 years, the dollar and major currencies, oil, gas, gold, silver and copper, bitcoin and ether, and the main markets in Europe and Asia, each with its last close and its change over a day, a week, a month, three months, the year to date and a year.",
+  compute_prices: "Compute as a market, no key: the on-demand hourly price of each data-centre GPU (B200, H200, H100, A100, L40S...) across the clouds and GPU marketplaces, the cheapest, median and dearest offer with who offers it, every provider's offer for one model, recent list-price changes, and the Cirrun GPU Index (a daily chained index of those prices). Each price is the provider's own list price with the date it was confirmed.",
   funding_rates: "Crypto perpetual funding on OKX's USDT perpetuals, no key: each coin's latest eight-hour rate, the window's mean and its annualized carry (short the perpetual against long spot), the last week's, and the share of positive periods.",
   private_offerings: "Private markets from Form D, filed when startups and funds sell securities without registering: amount offered and sold, number of investors, minimum investment, exemption (Rule 506(b) or 506(c)), industry, fund type and the people behind it, for one issuer or across the market (newest first, filtered by industry or amount sold).",
   fails_to_deliver: "Shares that failed to settle, from the SEC's fails-to-deliver data (NSCC): a stock's outstanding fail balance on each settlement date over the latest half-month files, with prices and dollar values, or the securities with the largest fails across the market.",
@@ -166,6 +172,9 @@ export const TOOL_KEYWORDS = Object.freeze({
   filing_drift: "language drift text change lazy prices semantic drift wording change over years risk factor creep obfuscation hedging uncertainty readability fog theme trend supply chain tariff mentions over time",
   planned_insider_sales: "form 144 planned insider sales intends to sell insider selling notice proposed sale officer director executive selling 10b5-1 plan upcoming insider sales",
   ipo_pipeline: "ipo ipos initial public offering going public s-1 f-1 registration statement priced offering 424b4 spac blank check new listings ipo calendar pipeline upcoming ipos",
+  shareholder_returns: "dividend dividends yield payout ratio dividend history dividend growth aristocrat king raised increases buyback buybacks repurchase repurchases share count dilution shareholder yield capital return returned cash to shareholders per share",
+  market_overview: "market today how is the market doing stocks overview snapshot summary indices index s&p nasdaq dow russell vix sectors sector performance rotation best worst yields bonds treasury dollar oil gold bitcoin crypto world markets europe asia week month year to date ytd",
+  compute_prices: "gpu compute price prices cost per hour cloud rental rent h100 h200 b200 a100 l40s rtx 4090 nvidia ai training inference data centre center index commodity aws runpod lambda coreweave modal cheapest",
   funding_rates: "crypto funding rate perpetual perp swap carry basis cash and carry bitcoin ethereum longs pay shorts okx",
   private_offerings: "private placement placements form d raise raised fundraising funding round startup startups venture capital vc private equity hedge fund real estate syndication reg d 506b 506c accredited investors",
   fails_to_deliver: "fails to deliver ftd failed settlement naked short selling short squeeze reg sho threshold securities settlement fails nscc",
@@ -233,6 +242,9 @@ export const OUTPUT_SCHEMAS = Object.freeze({
   filing_drift: z.looseObject({ company: opt(z.looseObject({})), section: opt(z.looseObject({})), theme: opt(z.string()), flags: opt(z.array(z.string())), filings: opt(z.array(z.string())), not_read: opt(z.looseObject({})), ...table, ...common }).describe("rows are annual reports, newest first, in the order of columns; flags are plain sentences."),
   planned_insider_sales: z.looseObject({ company: opt(z.looseObject({})), notices: opt(z.number()), planned_value_total: opt(z.number()), by_seller: opt(z.looseObject({})), not_read: opt(z.array(z.unknown())), ...table, ...common }).describe("rows are Form 144 notices, newest first, in the order of columns."),
   ipo_pipeline: z.looseObject({ from: opt(z.string()), to: opt(z.string()), kind: opt(z.string()), registrations: opt(z.looseObject({})), counts: opt(z.looseObject({})), priced: opt(z.looseObject({})), ...common }).describe("registrations.rows and priced.rows, newest first, in the order of their columns."),
+  shareholder_returns: z.looseObject({ company: opt(z.looseObject({})), dividends: opt(z.looseObject({})), yields: opt(z.looseObject({})), tags: opt(z.looseObject({})), ...table, ...common }).describe("rows are fiscal years, newest first, in the order of columns; dividends is the split-adjusted record; yields use the last close."),
+  market_overview: z.looseObject({ columns: opt(z.array(z.string())), us: opt(z.array(z.unknown())), sectors: opt(z.array(z.unknown())), rates: opt(z.array(z.unknown())), currencies: opt(z.array(z.unknown())), commodities: opt(z.array(z.unknown())), crypto: opt(z.array(z.unknown())), world: opt(z.array(z.unknown())), ...common }).describe("each group's rows in the order of columns; changes are fractions, and percentage points for yields."),
+  compute_prices: z.looseObject({ date: opt(z.string()), index: opt(z.looseObject({})), gpu: opt(z.string()), summary: opt(z.looseObject({})), provider_offers: opt(z.looseObject({})), changes: opt(z.looseObject({})), cite: opt(z.string()), ...table, ...common }).describe("Without gpu, rows are GPU models with their cheapest, median and dearest offers; with gpu, rows are every provider's offer for it, cheapest first. Prices are USD per GPU-hour."),
   funding_rates: z.looseObject({ days: opt(z.number()), series: opt(z.looseObject({})), missing: opt(z.array(z.unknown())), ...table, ...common }).describe("rows are coins by annualized funding, in the order of columns."),
   private_offerings: z.looseObject({ issuer: opt(z.looseObject({})), people: opt(z.array(z.unknown())), ...table, ...common }).describe("rows are Form D offerings, newest first, in the order of columns; sold and offered are dollars (offered may be indefinite)."),
   fails_to_deliver: z.looseObject({ symbol: opt(z.string()), largest: opt(z.looseObject({})), files: opt(z.array(z.string())), ...table, ...common }).describe("rows are settlement dates with the outstanding fail balance (one stock) or securities ranked by their largest balance by value (the market)."),
@@ -260,7 +272,7 @@ export const OUTPUT_SCHEMAS = Object.freeze({
   price_history: z.looseObject({ symbol: opt(z.string()), change: opt(z.looseObject({})), dates: opt(z.array(z.string())), close: opt(z.array(z.number())), ...common }).describe("dates, open, high, low, close and volume are aligned columns, oldest first; change.total_return is the window's return with dividends reinvested (a fraction)."),
 });
 
-const TITLES = { european_filings: "European filings (ESEF)", reference_rates: "Reference and policy rates", prediction_markets: "Prediction markets", crypto_fundamentals: "Crypto fundamentals (DefiLlama)", verify_claims: "Verify claims against filings", financial_statements: "Financial statements as filed", filing_tables: "Tables in filings", earnings_release: "Earnings release and guidance", screen_companies: "Screen companies", company_report: "Company report", event_study: "Event study", mentions_trend: "Mentions over time", company_profile: "Company profile", list_filings: "List filings", read_filing: "Read a filing", search_filings: "Search filings", insider_trades: "Insider trades", fund_holdings: "Fund holdings (13F)", fund_portfolio: "Fund or ETF portfolio (N-PORT)", large_holders: "Large holders (13D/13G)", earnings_calendar: "Earnings calendar", investment_advisers: "Investment advisers (Form ADV)", company_events: "Company events (8-K)", latest_filings: "Latest filings (EDGAR feed)", filing_diff: "What changed in a filing", news: "News and tone (GDELT)", explain_move: "Explain a stock move", portfolio_xray: "Portfolio X-ray (look-through)", comps: "Comparable companies", debt_profile: "Debt profile", ownership_breadth: "Breadth of institutional ownership (13F)", forensic_scores: "Forensic accounting screens", funding_rates: "Crypto funding rates (OKX)", federal_contracts: "Federal contracts (USAspending)", drug_pipeline: "Drug pipeline and FDA approvals", comment_letters: "SEC comment letters", reverse_dcf: "Reverse DCF (implied growth)", bank_financials: "Bank financials (FDIC call reports)", filing_drift: "Language drift across filings", planned_insider_sales: "Planned insider sales (Form 144)", ipo_pipeline: "IPO pipeline (S-1, F-1, 424B4)", private_offerings: "Private offerings (Form D)", short_interest: "Short interest (FINRA)", off_exchange_volume: "Dark pool and OTC volume (FINRA)", fails_to_deliver: "Fails to deliver (SEC)", executive_pay: "Executive pay vs performance", fomc: "Fed rate decisions (FOMC)", economic_calendar: "Economic calendar", index_constituents: "Index constituents", options_chain: "Options chain (Cboe)", volatility_surface: "Volatility surface (Cboe)", futures_curve: "Futures curve (Cboe)", segment_revenue: "Revenue by segment", futures_positioning: "Futures positioning (CFTC COT)", treasury_yields: "Treasury yields", economic_series: "Economic series (FRED)", world_economy: "World economy (World Bank)", economic_outlook: "Economic outlook (OECD projections)", treasury_auctions: "Treasury auctions", federal_debt: "US federal debt", price_history: "Price history" };
+const TITLES = { european_filings: "European filings (ESEF)", reference_rates: "Reference and policy rates", prediction_markets: "Prediction markets", crypto_fundamentals: "Crypto fundamentals (DefiLlama)", verify_claims: "Verify claims against filings", financial_statements: "Financial statements as filed", filing_tables: "Tables in filings", earnings_release: "Earnings release and guidance", screen_companies: "Screen companies", company_report: "Company report", event_study: "Event study", mentions_trend: "Mentions over time", company_profile: "Company profile", list_filings: "List filings", read_filing: "Read a filing", search_filings: "Search filings", insider_trades: "Insider trades", fund_holdings: "Fund holdings (13F)", fund_portfolio: "Fund or ETF portfolio (N-PORT)", large_holders: "Large holders (13D/13G)", earnings_calendar: "Earnings calendar", investment_advisers: "Investment advisers (Form ADV)", company_events: "Company events (8-K)", latest_filings: "Latest filings (EDGAR feed)", filing_diff: "What changed in a filing", news: "News and tone (GDELT)", explain_move: "Explain a stock move", portfolio_xray: "Portfolio X-ray (look-through)", comps: "Comparable companies", debt_profile: "Debt profile", ownership_breadth: "Breadth of institutional ownership (13F)", forensic_scores: "Forensic accounting screens", funding_rates: "Crypto funding rates (OKX)", compute_prices: "GPU compute prices (Cirrun index)", shareholder_returns: "Dividends and buybacks", market_overview: "Market overview", federal_contracts: "Federal contracts (USAspending)", drug_pipeline: "Drug pipeline and FDA approvals", comment_letters: "SEC comment letters", reverse_dcf: "Reverse DCF (implied growth)", bank_financials: "Bank financials (FDIC call reports)", filing_drift: "Language drift across filings", planned_insider_sales: "Planned insider sales (Form 144)", ipo_pipeline: "IPO pipeline (S-1, F-1, 424B4)", private_offerings: "Private offerings (Form D)", short_interest: "Short interest (FINRA)", off_exchange_volume: "Dark pool and OTC volume (FINRA)", fails_to_deliver: "Fails to deliver (SEC)", executive_pay: "Executive pay vs performance", fomc: "Fed rate decisions (FOMC)", economic_calendar: "Economic calendar", index_constituents: "Index constituents", options_chain: "Options chain (Cboe)", volatility_surface: "Volatility surface (Cboe)", futures_curve: "Futures curve (Cboe)", segment_revenue: "Revenue by segment", futures_positioning: "Futures positioning (CFTC COT)", treasury_yields: "Treasury yields", economic_series: "Economic series (FRED)", world_economy: "World economy (World Bank)", economic_outlook: "Economic outlook (OECD projections)", treasury_auctions: "Treasury auctions", federal_debt: "US federal debt", price_history: "Price history" };
 export const TOOLS = Object.freeze({
   verify_claims: [VC.verifyInput, VC.verifyClaims],
   european_filings: [EU.esefInput, EU.europeanFilings], reference_rates: [RT.ratesInput, RT.referenceRates], prediction_markets: [PM.predictionsInput, PM.predictionMarkets], crypto_fundamentals: [CR.cryptoInput, CR.cryptoFundamentals],
@@ -269,7 +281,7 @@ export const TOOLS = Object.freeze({
   company_profile: [T.profileInput, T.companyProfile], list_filings: [T.listInput, T.listFilings], read_filing: [T.readInput, T.readFiling],
   search_filings: [T.searchInput, T.searchFilings], insider_trades: [T.insiderInput, T.insiderTrades], fund_holdings: [T.holdingsInput, T.fundHoldings],
   treasury_yields: [T.treasuryInput, T.treasuryYields], economic_series: [T.fredInput, T.economicSeries], price_history: [T.priceInput, T.priceHistory],
-  fund_portfolio: [F.portfolioInput, F.fundPortfolio], options_chain: [Opt.chainInput, Opt.optionsChain], volatility_surface: [Opt.surfaceInput, Opt.volatilitySurface], futures_curve: [Opt.curveInput, Opt.futuresCurve], segment_revenue: [Seg.segmentInput, Seg.segmentRevenue], index_constituents: [F.indexInput, F.indexConstituents], fomc: [CB.fomcInput, CB.fomc], economic_calendar: [Cal.calendarInput, Cal.economicCalendar], executive_pay: [Pay.payInput, Pay.executivePay], short_interest: [Pos.shortInput, Pos.shortInterest], off_exchange_volume: [Pos.offExchangeInput, Pos.offExchangeVolume], fails_to_deliver: [Pos.ftdInput, Pos.failsToDeliver], futures_positioning: [Pos.cotInput, Pos.futuresPositioning], private_offerings: [P.offeringsInput, P.privateOfferings], company_events: [E.eventsInput, E.companyEvents], latest_filings: [LF.latestInput, LF.latestFilings], filing_diff: [DF.diffInput, DF.filingDiff], news: [NW.newsInput, NW.news], explain_move: [EX.explainInput, EX.explainMove], portfolio_xray: [XR.xrayInput, XR.portfolioXray], comps: [CP.compsInput, CP.comps], debt_profile: [DB.debtInput, DB.debtProfile], ownership_breadth: [OB.ownershipInput, OB.ownershipBreadth], forensic_scores: [FO.forensicInput, FO.forensicScores], funding_rates: [FU.fundingInput, FU.fundingRates], federal_contracts: [FC.contractsInput, FC.federalContracts], drug_pipeline: [PL.pipelineInput, PL.drugPipeline], comment_letters: [CL.lettersInput, CL.commentLetters], reverse_dcf: [VA.reverseDcfInput, VA.reverseDcf], bank_financials: [BK.bankInput, BK.bankFinancials], filing_drift: [DR.driftInput, DR.filingDrift], planned_insider_sales: [PS.plannedInput, PS.plannedInsiderSales], ipo_pipeline: [IP.ipoInput, IP.ipoPipeline], large_holders: [O.holdersInput, O.largeHolders], earnings_calendar: [Earn.earningsInput, Earn.earningsCalendar], investment_advisers: [Adv.adviserInput, Adv.investmentAdvisers], world_economy: [G.worldInput, G.worldEconomy], economic_outlook: [G.outlookInput, G.economicOutlook], treasury_auctions: [G.auctionInput, G.treasuryAuctions], federal_debt: [G.debtInput, G.federalDebt],
+  fund_portfolio: [F.portfolioInput, F.fundPortfolio], options_chain: [Opt.chainInput, Opt.optionsChain], volatility_surface: [Opt.surfaceInput, Opt.volatilitySurface], futures_curve: [Opt.curveInput, Opt.futuresCurve], segment_revenue: [Seg.segmentInput, Seg.segmentRevenue], index_constituents: [F.indexInput, F.indexConstituents], fomc: [CB.fomcInput, CB.fomc], economic_calendar: [Cal.calendarInput, Cal.economicCalendar], executive_pay: [Pay.payInput, Pay.executivePay], short_interest: [Pos.shortInput, Pos.shortInterest], off_exchange_volume: [Pos.offExchangeInput, Pos.offExchangeVolume], fails_to_deliver: [Pos.ftdInput, Pos.failsToDeliver], futures_positioning: [Pos.cotInput, Pos.futuresPositioning], private_offerings: [P.offeringsInput, P.privateOfferings], company_events: [E.eventsInput, E.companyEvents], latest_filings: [LF.latestInput, LF.latestFilings], filing_diff: [DF.diffInput, DF.filingDiff], news: [NW.newsInput, NW.news], explain_move: [EX.explainInput, EX.explainMove], portfolio_xray: [XR.xrayInput, XR.portfolioXray], comps: [CP.compsInput, CP.comps], debt_profile: [DB.debtInput, DB.debtProfile], ownership_breadth: [OB.ownershipInput, OB.ownershipBreadth], forensic_scores: [FO.forensicInput, FO.forensicScores], funding_rates: [FU.fundingInput, FU.fundingRates], compute_prices: [CO.computeInput, CO.computePrices], shareholder_returns: [PO.payoutsInput, PO.shareholderReturns], market_overview: [MO.overviewInput, MO.marketOverview], federal_contracts: [FC.contractsInput, FC.federalContracts], drug_pipeline: [PL.pipelineInput, PL.drugPipeline], comment_letters: [CL.lettersInput, CL.commentLetters], reverse_dcf: [VA.reverseDcfInput, VA.reverseDcf], bank_financials: [BK.bankInput, BK.bankFinancials], filing_drift: [DR.driftInput, DR.filingDrift], planned_insider_sales: [PS.plannedInput, PS.plannedInsiderSales], ipo_pipeline: [IP.ipoInput, IP.ipoPipeline], large_holders: [O.holdersInput, O.largeHolders], earnings_calendar: [Earn.earningsInput, Earn.earningsCalendar], investment_advisers: [Adv.adviserInput, Adv.investmentAdvisers], world_economy: [G.worldInput, G.worldEconomy], economic_outlook: [G.outlookInput, G.economicOutlook], treasury_auctions: [G.auctionInput, G.treasuryAuctions], federal_debt: [G.debtInput, G.federalDebt],
 });
 const ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };