webperf-snippets 1.7.0 → 1.8.0

package/README.md

@@ -73,7 +73,7 @@ npx webperf-snippets https://example.com --json
 The JSON output records how the page was measured in `conditions`, so a later run can tell whether it measured the same way: the viewport, the workflow (or the path of the snippet with `--snippet`), the wait and the version of the CLI.
 
 ```json
-"conditions": { "viewport": "mobile", "workflow": "core-web-vitals", "waitMs": 3000, "cliVersion": "1.7.0" }
+"conditions": { "viewport": "mobile", "workflow": "core-web-vitals", "waitMs": 3000, "cliVersion": "1.8.0" }
 ```
 
 Single snippet:
@@ -158,7 +158,7 @@ Without `--report-to` the CLI makes no external calls. With it, the results are
   "timestamp": "2026-05-06T10:00:00.000Z",
   "navMs": 1240,
   "results": [],
-  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "1.7.0" }
+  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "1.8.0" }
 }
 ```
 
@@ -382,12 +382,13 @@ It needs the Chromium of Playwright (`npx playwright install chromium`); without
 | Tool            | What it does                                                                 |
 | --------------- | ---------------------------------------------------------------------------- |
 | `list_snippets` | Lists the snippets with their category, title, short aliases and whether they track interactions. Takes an optional `category`. |
-| `run_snippet`   | Opens a URL in a headless Chromium, runs one snippet and returns the object it returns. Takes `url`, `snippet` (name, alias or `Category/Name`), and optional `viewport` and `waitMs`. The snippets that record interactions run on a page opened with `open_page`. |
+| `run_snippet`   | Opens a URL in a headless Chromium, runs one snippet and returns a summary of its result. Takes `url`, `snippet` (name, alias or `Category/Name`), and optional `viewport` and `waitMs`. The snippets that record interactions run on a page opened with `open_page`. |
 | `run_workflow`  | Runs a workflow of the CLI (`core-web-vitals`, `audit`, `loading`, `interaction`) and the follow-ups of its decision tree. Takes `url`, `workflow`, and optional `viewport` and `waitMs`. |
 | `get_crux`      | Returns the CrUX p75 of LCP, CLS and INP for a URL, or its origin. Takes `url` and an optional `formFactor` (`phone`, `desktop`, `tablet`). Needs `CRUX_API_KEY` in the environment of the server. |
 | `open_page`     | Opens a URL in a page that stays open between calls and installs tracking snippets (`track`, such as `INP`). Returns a `sessionId`. |
 | `interact`      | Runs steps on an open page: `click`, `type`, `hover`, `scroll` or `wait`. |
 | `read_results`  | Returns what the tracking snippets of an open page have recorded. |
+| `get_details`   | Returns the whole object of one snippet of a run, by the `runId` that `run_snippet`, `run_workflow` or `read_results` returned, without measuring again. Takes `runId` and `snippet`. |
 | `close_page`    | Closes an open page. |
 
 The server also offers resources, documents a client can attach to the context:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webperf-snippets",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "mcpName": "io.github.nucliweb/webperf-snippets",
   "description": "Run curated WebPerf Snippets headlessly via Playwright. Diagnose Core Web Vitals beyond what Lighthouse exposes.",
   "type": "module",

package/snippets/Loading/Content-Visibility.js

@@ -34,6 +34,14 @@ function uniqueSelector(el) {
 }
 // @end-shared uniqueSelector
 
+// An element with content-visibility: auto has no size before it first renders unless
+// contain-intrinsic-size gives one, so the page moves when it does. content-visibility: auto adds auto
+// to contain-intrinsic-size, so Chrome reports an element with no size as "auto none", also when the CSS
+// says none: what counts is whether the value has a length, as in "auto 500px".
+function lacksIntrinsicSize(value) {
+  return !/\d/.test(value);
+}
+
 function detectContentVisibility() {
   // Create an object to store the results
   const results = {
@@ -125,7 +133,7 @@ function detectContentVisibility() {
 
     // Check for missing contain-intrinsic-size
     const missingIntrinsicSize = results.autoElements.filter(
-      (el) => el.containIntrinsicSize === "not set" || el.containIntrinsicSize === "none",
+      (el) => lacksIntrinsicSize(el.containIntrinsicSize),
     );
 
     if (missingIntrinsicSize.length > 0) {
@@ -327,7 +335,7 @@ window.analyzeContentVisibilityOpportunities = analyzeContentVisibilityOpportuni
     ],
     issues: [
       ...cvResults.autoElements
-        .filter(el => el.containIntrinsicSize === "not set" || el.containIntrinsicSize === "none")
+        .filter(el => lacksIntrinsicSize(el.containIntrinsicSize))
         .map(el => ({ code: "missing-intrinsic-size", severity: "warning", message: `${el.selector}: missing contain-intrinsic-size (CLS risk)`, target: el.selector })),
       ...(cvResults.autoElements.length + cvResults.hiddenElements.length === 0
         ? [{ code: "not-used", severity: "info", message: "No content-visibility usage found. Consider content-visibility: auto on below-the-fold sections to reduce the initial render cost." }]

package/snippets/Media/Oversized-Images.js

@@ -76,8 +76,13 @@
   }
   // @end-shared uniqueSelector
 
+  // An SVG scales to any size, so its pixels are not measured. The extension names most of them; the
+  // content type of the response names an SVG of the page served without it, such as an image service
+  // that takes the format in the query. The browser gives the content type only for a response it can
+  // read: an SVG of another origin without the extension is measured as a raster image.
+  const typeByUrl = new Map(performance.getEntriesByType("resource").map((e) => [e.name, e.contentType]));
   function isVector(url) {
-    return /^data:image\/svg/i.test(url) || /\.svg([?#]|$)/i.test(url);
+    return /^data:image\/svg/i.test(url) || /\.svg([?#]|$)/i.test(url) || typeByUrl.get(url) === "image/svg+xml";
   }
 
   // The size of the file in pixels. HTMLImageElement.naturalWidth is corrected by the srcset

package/snippets/SCHEMA.md

@@ -1137,7 +1137,7 @@ Returns buffered long tasks immediately. Ongoing tracking continues. `items` lis
 
 #### Oversized-Images (async)
 
-Compares the pixels of each loaded image file with the pixels drawn (rendered size times `devicePixelRatio`, scaled by `object-fit`). `ratio` is file pixels per pixel drawn: `oversized` at 1.5 or more, `undersized` (blurry) under 0.9. `items` lists the flagged images, the most wasted pixels first (at most 50); `count` and `details` cover all of them. `wastedBytes` and `transferBytes` are `null` when the transfer size is hidden (cross-origin without `Timing-Allow-Origin`); `details.wastedBytes` counts each URL once. Images with a zero-size box, unloaded images and SVGs are counted in `details.skipped*`. `selector` matches only the image of its item, built like `details.element` of LCP, so an image with no id or class has a path such as `div.partners > img:nth-of-type(3)` instead of `img`.
+Compares the pixels of each loaded image file with the pixels drawn (rendered size times `devicePixelRatio`, scaled by `object-fit`). `ratio` is file pixels per pixel drawn: `oversized` at 1.5 or more, `undersized` (blurry) under 0.9. `items` lists the flagged images, the most wasted pixels first (at most 50); `count` and `details` cover all of them. `wastedBytes` and `transferBytes` are `null` when the transfer size is hidden (cross-origin without `Timing-Allow-Origin`); `details.wastedBytes` counts each URL once. Images with a zero-size box, unloaded images and SVGs are counted in `details.skipped*`; an SVG is known by its extension, a `data:image/svg` URL, or, for a file of the same origin, the `contentType` of its resource entry. `selector` matches only the image of its item, built like `details.element` of LCP, so an image with no id or class has a path such as `div.partners > img:nth-of-type(3)` instead of `img`.
 
 ```json
 {
@@ -1250,7 +1250,7 @@ An issue about one thing among several, one issue per thing, also names it in `t
 
 | Code | Severity | When |
 |------|----------|------|
-| `missing-intrinsic-size` | warning | An element with `content-visibility: auto` and no `contain-intrinsic-size`; `target` is its selector |
+| `missing-intrinsic-size` | warning | An element with `content-visibility: auto` whose `contain-intrinsic-size` has no length, such as `none` or the `auto none` Chrome reports when no size is declared; `target` is its selector |
 | `not-used` | info | No `content-visibility` on the page |
 
 ### Critical-CSS-Detection

package/src/mcp/next-steps.js

@@ -0,0 +1,29 @@
+import { RULES, nextSteps } from "../decision-tree.js";
+import { loadSnippet } from "../load-snippet.js";
+import { isTrackingSnippet } from "../tracking.js";
+
+const isTrackingPath = (path) => isTrackingSnippet(path, loadSnippet(path));
+
+// The call of the tool that runs a snippet: a tracking snippet needs a page the agent interacts with. A
+// snippet waits as long as the run that called for it, so it reads the same paint.
+const callFor = ({ path, reason, url, viewport, waitMs, isTracking }) =>
+  isTracking(path)
+    ? { tool: "open_page", args: { url, track: [path], viewport }, reason }
+    : { tool: "run_snippet", args: { url, snippet: path, viewport, ...(waitMs !== undefined ? { waitMs } : {}) }, reason };
+
+// The follow-ups the decision tree of the CLI asks for, as the calls an agent makes next. The rules name
+// the steps of a workflow (LCP, CLS, TTFB, FCP), which are the scripts of the snippets, so a result of
+// run_snippet, whose id is Category/Name, is matched by its script. `ran` leaves out what already ran.
+export function followUpCalls({ results, url, viewport, waitMs, ran = [], rules = RULES, isTracking = isTrackingPath }) {
+  const named = results.map((r) => ({ ...r, id: r.script ?? r.id }));
+  return nextSteps(named, rules, ran).map(({ path, reason }) => callFor({ path, reason, url, viewport, waitMs, isTracking }));
+}
+
+// The steps a workflow skipped because they measure clicks and key presses, in one page to open
+export function trackingCall({ paths, url, viewport }) {
+  return {
+    tool: "open_page",
+    args: { url, track: paths, viewport },
+    reason: "These steps measure clicks and key presses: open the page with them, interact with it and read them with read_results",
+  };
+}

package/src/mcp/prompts.js

@@ -31,7 +31,8 @@ export function registerPrompts(server) {
             `1. Call run_workflow with url "${url}", workflow "core-web-vitals" and viewport "${viewport}". It returns LCP and CLS, and adds LCP-Subparts with the reason when LCP is over 2.5 s.`,
             `2. Call get_crux for the same URL with formFactor "${viewport === "desktop" ? "desktop" : "phone"}", to compare the lab with what real users get. If it answers that there is no key, say so and go on with the lab data.`,
             '3. If LCP-Subparts did not run, call run_snippet with snippet "LCP-Subparts".',
-            "4. Report the LCP value and rating in the lab and in the field, the LCP element, the slowest sub-part and what it means, and the fixes for that sub-part, the most effective first.",
+            "4. If the answers are summaries (detail: summary), call get_details with the runId for LCP and LCP-Subparts: a summary leaves out the LCP element and the sub-parts.",
+            "5. Report the LCP value and rating in the lab and in the field, the LCP element, the slowest sub-part and what it means, and the fixes for that sub-part, the most effective first.",
             "",
             `${QUOTE} The result of each snippet is described below.`,
           ].join("\n")
@@ -63,7 +64,7 @@ export function registerPrompts(server) {
             selector
               ? `2. Call interact with a click on "${selector}". Add a few more clicks or key presses if the page has other controls a user would use.`
               : "2. Call interact with clicks on the controls a user would use first: main buttons, links that open menus, form fields. If you cannot tell which ones, ask me.",
-            "3. Call read_results. INP gives the worst interaction and its phases (input delay, processing, presentation); Input-Latency-Breakdown says which phase dominates for each type of event.",
+            "3. Call read_results; if it answers with summaries, call get_details with its runId for INP and Input-Latency-Breakdown. INP gives the worst interaction and its phases (input delay, processing, presentation); Input-Latency-Breakdown says which phase dominates for each type of event.",
             "4. Call close_page.",
             "5. Report the worst interaction, its target, the dominant phase and the fixes for that phase.",
             "",

package/src/mcp/server.js

@@ -13,6 +13,8 @@ import { createSessions, SessionError } from "./sessions.js";
 import { launchChromium, isMissingBrowser, MISSING_BROWSER } from "../browser.js";
 import { registerResources } from "./documents.js";
 import { registerPrompts } from "./prompts.js";
+import { shapeResults, createRuns, RunError } from "./summary.js";
+import { followUpCalls, trackingCall } from "./next-steps.js";
 import { isHttpUrl } from "../url.js";
 
 const VIEWPORTS = Object.keys(VIEWPORT_PRESETS);
@@ -33,6 +35,27 @@ const SnippetResult = z
 
 const SessionId = z.string().describe("The id open_page returned");
 
+const RunId = z.string().describe("The id of the run, for get_details");
+// Only a summary names its run: whole objects leave nothing for get_details to add
+const SummaryRunId = RunId.optional().describe("The id of the run, for get_details; only with summaries");
+
+// auto, the default, returns whole objects when they are small and summaries when they are large: a
+// summary of a small result costs the agent a turn for the details, which is more than it saves
+const Detail = z
+  .enum(["auto", "summary", "full"])
+  .default("auto")
+  .describe("auto: whole objects when small, summaries when large");
+const DetailOut = z.enum(["summary", "full"]).describe("Whether the results are summaries or the whole objects");
+
+// The call an agent makes next, with the arguments it takes as they are
+const NextSteps = z
+  .array(z.object({ tool: z.string(), args: z.record(z.string(), z.unknown()), reason: z.string() }))
+  .optional()
+  .describe("The calls to make next, with their arguments and why, when the results call for them");
+
+const DETAIL_NOTE =
+  "Large results come as summaries with a runId for get_details; nextSteps, when present, is the call to make next.";
+
 // A page can put instructions for the agent in what a snippet returns: an alt text, a class in a
 // selector, the URL of a script. The tools that return what a page holds say how to read it, and so
 // do the instructions of the server, which a client gives the model before any tool.
@@ -98,6 +121,7 @@ function describeSnippet(name) {
 export function createServer({ launchBrowser = () => launchChromium(), maxPages, idleMs, env = process.env } = {}) {
   const server = new McpServer({ name: "webperf-snippets", version: cliVersion }, { instructions: INSTRUCTIONS });
   const sessions = createSessions({ launchBrowser, maxPages, idleMs });
+  const runs = createRuns();
   // The client left (end of stdin, or a closed transport): close the pages and Chromium
   server.server.onclose = () => sessions.closeAll();
   registerResources(server);
@@ -138,24 +162,28 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
     {
       title: "Run a snippet",
       description:
-        `Opens the URL in a headless Chromium, runs one web performance snippet on the loaded page and returns the object the snippet returns, as defined in snippets/SCHEMA.md. Use list_snippets for the names. The snippets that record interactions (INP, Interactions, Input-Latency-Breakdown) run on a page opened with open_page instead. ${PAGE_DATA}`,
+        `Opens the URL in a headless Chromium, runs one web performance snippet on the loaded page and returns the object the snippet returns, as defined in snippets/SCHEMA.md. Use list_snippets for the names. The snippets that record interactions (INP, Interactions, Input-Latency-Breakdown) run on a page opened with open_page instead. ${DETAIL_NOTE} ${PAGE_DATA}`,
       inputSchema: z.object({
         url: HttpUrl,
         snippet: z.string().describe("The snippet: its name (LCP-Subparts), an alias (render-blocking) or Category/Name"),
         viewport: z.enum(VIEWPORTS).default("mobile").describe("Device size of the page"),
         waitMs: z.number().int().min(0).max(10000).default(3000).describe("Wait after the load event before running the snippet, in ms"),
+        detail: Detail,
       }),
       outputSchema: z.object({
         url: z.string(),
+        runId: SummaryRunId,
+        detail: DetailOut,
         snippet: z.string().describe("Category/Name of the snippet that ran"),
         viewport: z.enum(VIEWPORTS),
         navMs: z.number().describe("From the start of the navigation to the end of the wait"),
         pageErrors: z.array(z.string()).describe("Uncaught errors of the page during the run"),
         result: SnippetResult,
+        nextSteps: NextSteps,
       }),
       annotations: { readOnlyHint: true, openWorldHint: true },
     },
-    async ({ url, snippet, viewport, waitMs }, ctx) => {
+    async ({ url, snippet, viewport, waitMs, detail }, ctx) => {
       let path;
       try {
         path = resolveSnippetName(snippet);
@@ -169,8 +197,21 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
 
       try {
         const run = await runSnippets({ url, items: [{ id: path, path, source }], waitMs, viewport: VIEWPORT_PRESETS[viewport], onProgress: progressFor(ctx) });
-        const { id, ...result } = run.results[0];
-        return toolResult({ url, snippet: id, viewport, navMs: run.navMs, pageErrors: run.pageErrors, result });
+        const shaped = shapeResults(run.results.map(({ id, ...result }) => result), detail);
+        const runId = shaped.detail === "summary" ? runs.keep(run.results) : undefined;
+        const id = run.results[0].id;
+        const nextSteps = followUpCalls({ results: run.results, url, viewport, waitMs, ran: [path] });
+        return toolResult({
+          url,
+          ...(runId ? { runId } : {}),
+          detail: shaped.detail,
+          snippet: id,
+          viewport,
+          navMs: run.navMs,
+          pageErrors: run.pageErrors,
+          result: shaped.results[0],
+          ...(nextSteps.length ? { nextSteps } : {}),
+        });
       } catch (err) {
         if (isMissingBrowser(err)) return toolError(MISSING_BROWSER);
         if (/page\.goto/.test(err.message)) return toolError(`Could not load ${url}: ${firstLine(err.message)}`);
@@ -184,15 +225,18 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
     {
       title: "Run a workflow",
       description:
-        `Opens the URL in a headless Chromium and runs a workflow: a sequence of snippets plus the follow-ups its decision tree adds from the results (for example LCP-Subparts when LCP is over 2.5 s, with the reason). core-web-vitals: LCP and CLS. audit: render-blocking resources, resource hints, critical CSS, TTFB, scripts, images and more. loading: TTFB, FCP, render-blocking, scripts and fonts. interaction: long tasks, animation frames, scroll and layout shifts while it scrolls the page. ${PAGE_DATA}`,
+        `Opens the URL in a headless Chromium and runs a workflow: a sequence of snippets plus the follow-ups its decision tree adds from the results (for example LCP-Subparts when LCP is over 2.5 s, with the reason). core-web-vitals: LCP and CLS. audit: render-blocking resources, resource hints, critical CSS, TTFB, scripts, images and more. loading: TTFB, FCP, render-blocking, scripts and fonts. interaction: long tasks, animation frames, scroll and layout shifts while it scrolls the page. ${DETAIL_NOTE} ${PAGE_DATA}`,
       inputSchema: z.object({
         url: HttpUrl,
         workflow: z.enum(Object.keys(WORKFLOWS)).default("core-web-vitals"),
         viewport: z.enum(VIEWPORTS).default("mobile").describe("Device size of the page"),
         waitMs: z.number().int().min(0).max(10000).default(3000).describe("Wait after the load event before running the workflow, in ms"),
+        detail: Detail,
       }),
       outputSchema: z.object({
         url: z.string(),
+        runId: SummaryRunId,
+        detail: DetailOut,
         workflow: z.string(),
         viewport: z.enum(VIEWPORTS),
         navMs: z.number(),
@@ -200,10 +244,11 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
         results: z
           .array(z.looseObject({ id: z.string(), status: z.string() }).meta({ additionalProperties: true }))
           .describe("One object per step, in order, then the follow-ups, each with the reason it was added"),
+        nextSteps: NextSteps,
       }),
       annotations: { readOnlyHint: true, openWorldHint: true },
     },
-    async ({ url, workflow, viewport, waitMs }, ctx) => {
+    async ({ url, workflow, viewport, waitMs, detail }, ctx) => {
       try {
         const run = await runMeasurement({
           url,
@@ -219,7 +264,24 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
             ? { ...r, reason: "This step measures clicks and key presses: open the page with open_page and this snippet in track, use it with interact, and read it with read_results." }
             : r
         );
-        return toolResult({ url, workflow, viewport, navMs: run.navMs, pageErrors: run.pageErrors, results });
+        const shaped = shapeResults(results, detail);
+        const runId = shaped.detail === "summary" ? runs.keep(results) : undefined;
+        // The runner already ran the follow-ups of the decision tree; what is left is the steps it skipped
+        const skipped = results
+          .filter((r) => r.status === "skipped")
+          .map((r) => WORKFLOWS[workflow].steps.find((s) => s.id === r.id)?.path)
+          .filter(Boolean);
+        const nextSteps = skipped.length ? [trackingCall({ paths: skipped, url, viewport })] : [];
+        return toolResult({
+          url,
+          ...(runId ? { runId } : {}),
+          ...shaped,
+          workflow,
+          viewport,
+          navMs: run.navMs,
+          pageErrors: run.pageErrors,
+          ...(nextSteps.length ? { nextSteps } : {}),
+        });
       } catch (err) {
         if (isMissingBrowser(err)) return toolError(MISSING_BROWSER);
         if (/page\.goto/.test(err.message)) return toolError(`Could not load ${url}: ${firstLine(err.message)}`);
@@ -358,22 +420,58 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
     {
       title: "Read the tracking snippets",
       description:
-        `Returns what the tracking snippets installed by open_page have recorded on the page so far, as the objects they return. A snippet with nothing recorded yet, such as INP before any interaction, answers with status tracking and a message: interact with the page and read again. ${PAGE_DATA}`,
-      inputSchema: z.object({ sessionId: SessionId }),
-      outputSchema: z.object({ sessionId: z.string(), pageErrors: z.array(z.string()), results: z.array(SnippetResult) }),
+        `Returns what the tracking snippets installed by open_page have recorded on the page so far, as the objects they return. A snippet with nothing recorded yet, such as INP before any interaction, answers with status tracking and a message: interact with the page and read again. ${DETAIL_NOTE} ${PAGE_DATA}`,
+      inputSchema: z.object({ sessionId: SessionId, detail: Detail }),
+      outputSchema: z.object({ sessionId: z.string(), runId: SummaryRunId, detail: DetailOut, pageErrors: z.array(z.string()), results: z.array(SnippetResult) }),
       annotations: { readOnlyHint: true, openWorldHint: false },
     },
-    withSession(async ({ sessionId }) => {
+    withSession(async ({ sessionId, detail }) => {
       const session = sessions.get(sessionId);
-      const results = [];
-      for (const installed of session.tracking) {
-        const { id, ...result } = await collectTrackingData(session.page, installed, session.hadInput);
-        results.push(result);
-      }
-      return toolResult({ sessionId, pageErrors: session.pageErrors, results });
+      const collected = [];
+      for (const installed of session.tracking) collected.push(await collectTrackingData(session.page, installed, session.hadInput));
+      const shaped = shapeResults(collected.map(({ id, ...result }) => result), detail);
+      const runId = shaped.detail === "summary" ? runs.keep(collected) : undefined;
+      return toolResult({ sessionId, ...(runId ? { runId } : {}), ...shaped, pageErrors: session.pageErrors });
     })
   );
 
+  server.registerTool(
+    "get_details",
+    {
+      title: "Get the details of a result",
+      description:
+        `Returns the whole object of one snippet of a summarized run, by its runId: what the summary leaves out, from the same run, without measuring again. ${PAGE_DATA}`,
+      inputSchema: z.object({
+        runId: RunId,
+        snippet: z.string().describe("The id of the result in the summary, or its script"),
+      }),
+      outputSchema: z.object({ runId: z.string(), snippet: z.string().describe("The id of the result in the run"), result: SnippetResult }),
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    async ({ runId, snippet }) => {
+      // The id the summary shows first, then the Category/Name an alias or a short name stands for
+      let resolved;
+      try {
+        resolved = resolveSnippetName(snippet);
+      } catch {
+        resolved = undefined;
+      }
+      try {
+        let result;
+        try {
+          result = runs.get(runId, snippet);
+        } catch (err) {
+          if (!(err instanceof RunError) || !resolved || resolved === snippet) throw err;
+          result = runs.get(runId, resolved);
+        }
+        return toolResult({ runId, snippet: result.id, result });
+      } catch (err) {
+        if (err instanceof RunError) return toolError(err.message);
+        throw err;
+      }
+    }
+  );
+
   server.registerTool(
     "close_page",
     {

package/src/mcp/summary.js

@@ -0,0 +1,55 @@
+import { randomUUID } from "node:crypto";
+
+// A failure of get_details the model can act on: a run that is not kept, or a snippet it did not run
+export class RunError extends Error {}
+
+// What an agent needs from a result to decide what to do next; the rest (details, items, thresholds)
+// is in get_details, from the same run
+const SUMMARY_FIELDS = ["id", "script", "status", "metric", "value", "unit", "rating", "error", "message", "reason"];
+const ISSUE_FIELDS = ["code", "severity", "message", "target"];
+
+const pick = (object, fields) => Object.fromEntries(fields.filter((f) => object[f] !== undefined).map((f) => [f, object[f]]));
+
+export function summarize(result) {
+  const summary = pick(result, SUMMARY_FIELDS);
+  if (result.issues?.length) summary.issues = result.issues.map((issue) => pick(issue, ISSUE_FIELDS));
+  return summary;
+}
+
+// About 2,000 tokens. Below it the whole objects cost the agent less than the turn it would spend on
+// get_details for what a summary leaves out: in the MCP evals of 2026-10-29, summaries of small results
+// made the agent call get_details in 4 of 9 runs, and each turn sent 8 to 12k tokens of context again.
+export const FULL_UP_TO_CHARS = 8000;
+
+// The results of a call as the agent asked for them; with auto, whole when they are small, and summaries
+// with get_details for the rest when they are large
+export function shapeResults(results, detail = "auto", maxFullChars = FULL_UP_TO_CHARS) {
+  const full = detail === "full" || (detail === "auto" && JSON.stringify(results).length <= maxFullChars);
+  return full ? { detail: "full", results } : { detail: "summary", results: results.map(summarize) };
+}
+
+// The full results of the last runs of an MCP connection, by run id, so get_details answers with the
+// values the summary came from: measuring again would give other ones
+export function createRuns({ max = 20 } = {}) {
+  const runs = new Map();
+
+  function keep(results) {
+    const runId = randomUUID();
+    runs.set(runId, results);
+    // A Map keeps the order of insertion, so the first key is the oldest run
+    if (runs.size > max) runs.delete(runs.keys().next().value);
+    return runId;
+  }
+
+  function get(runId, snippet) {
+    const results = runs.get(runId);
+    if (!results) {
+      throw new RunError(`Unknown runId ${runId}: this server keeps the last ${max} runs of the connection. Run the tool again for a new one.`);
+    }
+    const result = results.find((r) => r.id === snippet) ?? results.find((r) => r.script === snippet);
+    if (!result) throw new RunError(`${snippet} is not in run ${runId}, which has: ${results.map((r) => r.id).join(", ")}.`);
+    return result;
+  }
+
+  return { keep, get };
+}