@components-kit/open-workbook 0.1.7 → 0.1.9

package/assets/mcp-server/dist/index.js

@@ -14,6 +14,9 @@ const standalone = hasArg("--standalone") || process.env.OPEN_WORKBOOK_MCP_STAND
 const catalogOptions = {
     includePreview: process.env.OPEN_WORKBOOK_PREVIEW_TOOLS === "1"
 };
+const toolProfile = readArg("--tool-profile") ?? process.env.OPEN_WORKBOOK_TOOL_PROFILE ?? "full";
+const explicitToolNames = parseToolNameList(readArg("--tools") ?? process.env.OPEN_WORKBOOK_TOOLS);
+const disabledToolNames = parseToolNameList(readArg("--disable-tools") ?? process.env.OPEN_WORKBOOK_DISABLE_TOOLS);
 const STYLE_DIMENSIONS = [
     "columnWidths",
     "rowHeights",
@@ -44,8 +47,106 @@ const STYLE_COPY_TOOL_DIMENSIONS = {
     "excel.style.copy_page_layout": "pageLayout",
     "excel.style.copy_hidden_rows_columns": "hiddenRowsColumns"
 };
+const COMPACT_PROFILE_TOOLS = new Set([
+    "excel.runtime.get_status",
+    "excel.runtime.get_capabilities",
+    "excel.runtime.get_active_context",
+    "excel.runtime.get_selection",
+    "excel.runtime.connect_addin",
+    "excel.runtime.ping_addin",
+    "excel.runtime.set_active_workbook",
+    "excel.runtime.set_active_sheet",
+    "excel.workbook.list_open_workbooks",
+    "excel.workbook.get_workbook_info",
+    "excel.workbook.get_workbook_map",
+    "excel.workbook.get_summary",
+    "excel.workbook.get_used_range_summary",
+    "excel.workbook.detect_external_changes",
+    "excel.workbook.calculate",
+    "excel.workbook.save",
+    "excel.sheet.list",
+    "excel.sheet.get_info",
+    "excel.sheet.get_summary",
+    "excel.sheet.get_used_range",
+    "excel.lookup.search_workbook",
+    "excel.lookup.find_headers",
+    "excel.lookup.find_tables_by_columns",
+    "excel.lookup.find_entity",
+    "excel.lookup.resolve_range",
+    "excel.lookup.inspect_match",
+    "excel.range.get_summary",
+    "excel.range.read_compact",
+    "excel.range.find_errors",
+    "excel.table.list",
+    "excel.table.get_info",
+    "excel.table.get_schema",
+    "excel.table.read_compact",
+    "excel.batch.validate",
+    "excel.batch.preflight",
+    "excel.batch.dry_run",
+    "excel.batch.apply",
+    "excel.batch.submit",
+    "excel.batch.submit_chunked",
+    "excel.job.list",
+    "excel.job.get",
+    "excel.job.wait",
+    "excel.workflow.prepare_session",
+    "excel.workflow.create_formula_sheet",
+    "excel.workflow.create_template_report",
+    "excel.workflow.create_pivot_chart_summary",
+    "excel.workflow.repair_formula_errors",
+    "excel.workflow.preview_risky_edit",
+    "excel.plan.create",
+    "excel.plan.preview",
+    "excel.plan.apply",
+    "excel.plan.rollback",
+    "excel.compact.get_resource",
+    "excel.compact.list_resources",
+    "excel.compact.clear_resources",
+    "excel.compact.get_cache_status",
+    "excel.compact.clear_cache",
+    "excel.snapshot.create",
+    "excel.snapshot.get_compact",
+    "excel.snapshot.compare_compact",
+    "excel.diff.summarize",
+    "excel.diff.get_compact",
+    "excel.validate.compact",
+    "excel.validate.no_formula_errors",
+    "excel.validate.no_broken_references",
+    "excel.validate.no_unintended_changes",
+    "excel.collab.get_status",
+    "excel.transaction.list",
+    "excel.transaction.get",
+    "excel.transaction.wait",
+    "excel.transaction.preview_rollback",
+    "excel.transaction.rollback"
+]);
+const READ_ONLY_PROFILE_TOOLS = new Set([...COMPACT_PROFILE_TOOLS].filter((name) => name.startsWith("excel.runtime.") ||
+    name.startsWith("excel.workbook.get_") ||
+    name === "excel.workbook.list_open_workbooks" ||
+    name.startsWith("excel.sheet.") ||
+    name.startsWith("excel.lookup.") ||
+    name.startsWith("excel.range.read_") ||
+    name === "excel.range.get_summary" ||
+    name === "excel.range.find_errors" ||
+    name.startsWith("excel.table.get_") ||
+    name === "excel.table.list" ||
+    name === "excel.table.read_compact" ||
+    name.startsWith("excel.compact.") ||
+    name.startsWith("excel.snapshot.get_") ||
+    name === "excel.snapshot.compare_compact" ||
+    name.startsWith("excel.diff.") ||
+    name.startsWith("excel.validate.") ||
+    name === "excel.collab.get_status"));
 const runtime = await createRuntimeFacade();
-const runtimeVersion = process.env.OPEN_WORKBOOK_VERSION ?? "0.1.7";
+const runtimeVersion = process.env.OPEN_WORKBOOK_VERSION ?? "0.1.9";
+const COMPACT_RESOURCE_LIMIT = 100;
+const COMPACT_DEFAULT_RESOURCE_THRESHOLD_BYTES = 24_000;
+const compactResources = new Map();
+const compactCache = new Map();
+let compactCacheInvalidationCount = 0;
+let compactCacheLastInvalidatedAt;
+let compactLastObservedEventId;
 const server = new McpServer({
     name: "open-workbook",
     version: runtimeVersion
@@ -55,6 +156,7 @@ registerWorkbookTools(server);
 registerBackupTools(server);
 registerSheetTools(server);
 registerRangeTools(server);
+registerLookupTools(server);
 registerBatchTools(server);
 registerWorkflowTools(server);
 registerPlanTools(server);
@@ -81,6 +183,7 @@ registerRepairTools(server);
 registerSnapshotTools(server);
 registerDiffTools(server);
 registerEventTools(server);
+registerCompactTools(server);
 registerResources(server);
 registerPrompts(server);
 await server.connect(new StdioServerTransport());
@@ -211,6 +314,7 @@ function registerResources(mcp) {
         const planId = resourceVariable(variables, "plan_id");
         return runtime.getPlanDiffResource(workbookId, planId);
     });
+    registerJsonTemplateResource(mcp, "compact detail resource", "excel://compact/{resource_id}", "Stored compact-context detail payload returned by token-saving Open Workbook tools.", async (_uri, variables) => getCompactResource(resourceVariable(variables, "resource_id")));
 }
 function registerJsonResource(mcp, name, uri, description, read) {
     mcp.registerResource(name, uri, {
@@ -371,14 +475,15 @@ function registerRuntimeTools(mcp) {
         title: "Get Open Workbook capabilities",
         description: "Return complete tool/resource/prompt catalog status and runtime capability metadata.",
         inputSchema: {
-            includePreview: z.boolean().optional()
+            includePreview: z.boolean().optional(),
+            includeFullCatalog: z.boolean().optional()
         },
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
             openWorldHint: false
         }
-    }, async ({ includePreview }) => jsonResult(runtime.getCapabilities(includePreview === undefined ? {} : { includePreview })));
+    }, async ({ includePreview, includeFullCatalog }) => jsonResult(runtimeCapabilities(includePreview, includeFullCatalog)));
     registerMcpTool(mcp, "excel.runtime.get_active_context", {
         title: "Get active Excel context",
         description: "Return active workbook context from the connected Excel add-in.",
@@ -424,6 +529,44 @@ function registerRuntimeTools(mcp) {
         }
     }, async ({ sheetName }) => jsonResult(await runtime.setActiveSheet(sheetName)));
 }
+function runtimeCapabilities(includePreview, includeFullCatalog) {
+    const capabilities = runtime.getCapabilities(includePreview === undefined ? {} : { includePreview });
+    if (toolProfile === "full" || includeFullCatalog === true) {
+        return capabilities;
+    }
+    const typed = capabilities;
+    const catalog = typed.catalog;
+    const exposedToolNames = exposedProfileToolNames();
+    return {
+        ...typed,
+        catalog: catalog
+            ? {
+                total: catalog.total,
+                stable: catalog.stable,
+                preview: catalog.preview,
+                planned: catalog.planned,
+                unsupported: catalog.unsupported,
+                profile: toolProfile,
+                exposed: exposedToolNames.length,
+                tools: exposedToolNames
+            }
+            : undefined,
+        resources: Array.isArray(typed.resources) ? { count: typed.resources.length } : typed.resources,
+        prompts: Array.isArray(typed.prompts) ? { count: typed.prompts.length } : typed.prompts
+    };
+}
+function exposedProfileToolNames() {
+    if (explicitToolNames !== undefined) {
+        return [...explicitToolNames].filter((name) => shouldExposeMcpTool(name)).sort();
+    }
+    if (toolProfile === "compact") {
+        return [...COMPACT_PROFILE_TOOLS].filter((name) => shouldExposeMcpTool(name)).sort();
+    }
+    if (toolProfile === "read-only" || toolProfile === "readonly") {
+        return [...READ_ONLY_PROFILE_TOOLS].filter((name) => shouldExposeMcpTool(name)).sort();
+    }
+    return [];
+}
 function registerWorkbookTools(mcp) {
     registerMcpTool(mcp, "excel.workbook.list_open_workbooks", {
         title: "List open Excel workbooks",
@@ -460,6 +603,26 @@ function registerWorkbookTools(mcp) {
             openWorldHint: false
         }
     }, async () => jsonResult(await runtime.getWorkbookMap()));
+    registerMcpTool(mcp, "excel.workbook.get_summary", {
+        title: "Get compact workbook summary",
+        description: "Return compact workbook structure, sheet counts, table names, used-range dimensions, and token telemetry without cell bodies.",
+        inputSchema: { workbookId: z.string().optional() },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false
+        }
+    }, async ({ workbookId }) => jsonResult(await workbookSummary(workbookId)));
+    registerMcpTool(mcp, "excel.workbook.get_used_range_summary", {
+        title: "Get compact workbook used-range summary",
+        description: "Return used-range dimensions for workbook sheets without loading cell payloads.",
+        inputSchema: { workbookId: z.string().optional() },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false
+        }
+    }, async ({ workbookId }) => jsonResult(await workbookUsedRangeSummary(workbookId)));
     registerMcpTool(mcp, "excel.workbook.snapshot", {
         title: "Create workbook snapshot",
         description: "Capture a restorable snapshot of used ranges or specific ranges.",
@@ -879,6 +1042,12 @@ function registerSheetTools(mcp) {
         inputSchema: { sheetName: z.string() },
         annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
     }, async ({ sheetName }) => jsonResult(await selectSheetInfo(sheetName)));
+    registerMcpTool(mcp, "excel.sheet.get_summary", {
+        title: "Get compact worksheet summary",
+        description: "Return one worksheet's used-range dimensions, table names, and token telemetry without cell bodies.",
+        inputSchema: { workbookId: z.string().optional(), sheetName: z.string() },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, async ({ workbookId, sheetName }) => jsonResult(await sheetSummary(sheetName, workbookId)));
     registerMcpTool(mcp, "excel.sheet.get_used_range", {
         title: "Get worksheet used range",
         description: "Return the used range for a worksheet.",
@@ -986,6 +1155,46 @@ function registerRangeTools(mcp) {
             }
         }, async ({ workbookId, sheetName, address }) => jsonResult(await readRangeSnapshot(workbookId, sheetName, address, rangeReadFacets(name))));
     }
+    const compactReadSchema = {
+        ...readSchema,
+        mode: z.enum(["window", "summary", "sample"]).optional(),
+        rowOffset: z.number().int().min(0).optional(),
+        columnOffset: z.number().int().min(0).optional(),
+        maxRows: z.number().int().min(0).max(10000).optional(),
+        maxColumns: z.number().int().min(0).max(1000).optional(),
+        maxCells: z.number().int().min(0).max(1000000).optional(),
+        maxPayloadBytes: z.number().int().min(0).optional(),
+        maxEstimatedTokens: z.number().int().min(0).optional(),
+        includeValues: z.boolean().optional(),
+        includeFormulas: z.boolean().optional(),
+        includeText: z.boolean().optional(),
+        includeNumberFormats: z.boolean().optional(),
+        includeStyles: z.boolean().optional()
+    };
+    registerMcpTool(mcp, "excel.range.read_compact", {
+        title: "Read compact Excel range",
+        description: "Read a bounded values-first range window with opt-in facets, truncation metadata, and token telemetry.",
+        inputSchema: compactReadSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false
+        }
+    }, async (args) => jsonResult(await compactRangeRead(args)));
+    registerMcpTool(mcp, "excel.range.get_summary", {
+        title: "Get compact range summary",
+        description: "Return range dimensions, cell count, default compact-read window, and token telemetry without cell bodies.",
+        inputSchema: {
+            workbookId: z.string(),
+            sheetName: z.string(),
+            address: z.string()
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false
+        }
+    }, async ({ workbookId, sheetName, address }) => jsonResult(rangeSummary(workbookId, sheetName, address)));
     for (const [name, method] of [
         ["excel.range.read_hyperlinks", "range.read_hyperlinks"],
         ["excel.range.read_comments", "range.read_comments"],
@@ -1214,6 +1423,111 @@ function registerRangeTools(mcp) {
         }));
     }
 }
+function registerLookupTools(mcp) {
+    const budgetSchema = {
+        maxRows: z.number().int().min(0).max(10000).optional(),
+        maxColumns: z.number().int().min(0).max(1000).optional(),
+        maxCells: z.number().int().min(0).max(1000000).optional(),
+        maxPayloadBytes: z.number().int().min(0).optional(),
+        maxEstimatedTokens: z.number().int().min(0).optional()
+    };
+    const lookupAnnotations = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };
+    registerMcpTool(mcp, "excel.lookup.search_workbook", {
+        title: "Search workbook compactly",
+        description: "Search sheet names, table schemas, and used ranges across a workbook, returning ranked compact matches instead of full sheets.",
+        inputSchema: {
+            workbookId: z.string(),
+            query: z.string(),
+            sheetNames: z.array(z.string()).optional(),
+            includeSheets: z.boolean().optional(),
+            includeTables: z.boolean().optional(),
+            completeMatch: z.boolean().optional(),
+            matchCase: z.boolean().optional(),
+            maxMatches: z.number().int().min(1).max(1000).optional(),
+            maxPreviewRows: z.number().int().min(0).max(25).optional(),
+            ...budgetSchema
+        },
+        annotations: lookupAnnotations
+    }, async (args) => jsonResult(await lookupSearchWorkbook(args)));
+    registerMcpTool(mcp, "excel.lookup.find_headers", {
+        title: "Find workbook headers compactly",
+        description: "Find matching table columns and likely header cells from bounded top-of-sheet scans.",
+        inputSchema: {
+            workbookId: z.string(),
+            query: z.string().optional(),
+            headers: z.array(z.string()).optional(),
+            sheetNames: z.array(z.string()).optional(),
+            maxRowsPerSheet: z.number().int().min(1).max(100).optional(),
+            maxMatches: z.number().int().min(1).max(1000).optional(),
+            ...budgetSchema
+        },
+        annotations: lookupAnnotations
+    }, async (args) => jsonResult(await lookupFindHeaders(args)));
+    registerMcpTool(mcp, "excel.lookup.find_tables_by_columns", {
+        title: "Find tables by column set",
+        description: "Rank workbook tables by required and optional column names without reading table rows.",
+        inputSchema: {
+            workbookId: z.string(),
+            requiredColumns: z.array(z.string()),
+            optionalColumns: z.array(z.string()).optional(),
+            minScore: z.number().min(0).max(1).optional(),
+            maxMatches: z.number().int().min(1).max(1000).optional(),
+            ...budgetSchema
+        },
+        annotations: lookupAnnotations
+    }, async (args) => jsonResult(await lookupFindTablesByColumns(args)));
+    registerMcpTool(mcp, "excel.lookup.find_entity", {
+        title: "Find entity compactly",
+        description: "Locate a text, number, date, or generic entity across workbook used ranges with compact ranked results.",
+        inputSchema: {
+            workbookId: z.string(),
+            entity: z.string(),
+            kind: z.enum(["text", "number", "date", "any"]).optional(),
+            sheetNames: z.array(z.string()).optional(),
+            completeMatch: z.boolean().optional(),
+            matchCase: z.boolean().optional(),
+            maxMatches: z.number().int().min(1).max(1000).optional(),
+            maxPreviewRows: z.number().int().min(0).max(25).optional(),
+            ...budgetSchema
+        },
+        annotations: lookupAnnotations
+    }, async (args) => jsonResult(await lookupFindEntity(args)));
+    registerMcpTool(mcp, "excel.lookup.resolve_range", {
+        title: "Resolve workbook range target",
+        description: "Resolve a natural target string to a table, column, header, entity, sheet, or A1 range candidate before reading data.",
+        inputSchema: {
+            workbookId: z.string(),
+            target: z.string(),
+            kind: z.enum(["table", "column", "header", "entity", "range", "any"]).optional(),
+            preferredSheetName: z.string().optional(),
+            preferredTableName: z.string().optional(),
+            maxMatches: z.number().int().min(1).max(1000).optional(),
+            ...budgetSchema
+        },
+        annotations: lookupAnnotations
+    }, async (args) => jsonResult(await lookupResolveRange(args)));
+    registerMcpTool(mcp, "excel.lookup.inspect_match", {
+        title: "Inspect lookup match compactly",
+        description: "Read a bounded preview for one lookup match, preserving compact telemetry and avoiding broad sheet reads.",
+        inputSchema: {
+            workbookId: z.string(),
+            matchId: z.string().optional(),
+            kind: z.enum(["sheet", "table", "column", "header", "entity", "range"]).optional(),
+            sheetName: z.string().optional(),
+            tableName: z.string().optional(),
+            columnName: z.string().optional(),
+            address: z.string().optional(),
+            maxRows: z.number().int().min(0).max(10000).optional(),
+            maxColumns: z.number().int().min(0).max(1000).optional(),
+            includeValues: z.boolean().optional(),
+            includeFormulas: z.boolean().optional(),
+            includeText: z.boolean().optional(),
+            maxPayloadBytes: z.number().int().min(0).optional(),
+            maxEstimatedTokens: z.number().int().min(0).optional()
+        },
+        annotations: lookupAnnotations
+    }, async (args) => jsonResult(await lookupInspectMatch(args)));
+}
 function registerBatchTools(mcp) {
     registerMcpTool(mcp, "excel.batch.validate", {
         title: "Validate Excel batch",
@@ -1909,7 +2223,7 @@ async function workflowPreflight(workbookId, includePreview = true) {
     return {
         status,
         activeContext,
-        capabilities: runtime.getCapabilities({ includePreview }),
+        capabilities: runtimeCapabilities(includePreview),
         workbookMap: await runtime.getWorkbookMap(),
         collaboration: runtime.getCollaborationStatus(resolvedWorkbookId),
         workbookId: resolvedWorkbookId
@@ -2596,6 +2910,12 @@ function registerTableTools(mcp) {
         inputSchema: tableSelectorSchema(),
         annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
     }, async (args) => jsonResult(await runtime.getTableInfo(tableSelector(args))));
+    registerMcpTool(mcp, "excel.table.get_schema", {
+        title: "Get compact Excel table schema",
+        description: "Return table columns, dimensions, style flags, and token telemetry without row data.",
+        inputSchema: tableSelectorSchema(),
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, async (args) => jsonResult(await tableSchema(tableSelector(args))));
     registerMcpTool(mcp, "excel.table.read", {
         title: "Read Excel table",
         description: "Read table headers, selected data facets, optional columns, optional row page, and metadata.",
@@ -2611,6 +2931,26 @@ function registerTableTools(mcp) {
         },
         annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
     }, async (args) => jsonResult(await runtime.readTable(tableReadRequest(args))));
+    registerMcpTool(mcp, "excel.table.read_compact", {
+        title: "Read compact Excel table",
+        description: "Read a bounded values-first table page with projection, opt-in facets, truncation metadata, and token telemetry.",
+        inputSchema: {
+            ...tableSelectorSchema(),
+            mode: z.enum(["window", "summary", "sample"]).optional(),
+            includeValues: z.boolean().optional(),
+            includeFormulas: z.boolean().optional(),
+            includeText: z.boolean().optional(),
+            includeNumberFormats: z.boolean().optional(),
+            columns: z.array(z.union([z.string(), z.number().int().min(0)])).optional(),
+            rowOffset: z.number().int().min(0).optional(),
+            maxRows: z.number().int().min(0).max(10000).optional(),
+            maxColumns: z.number().int().min(0).max(1000).optional(),
+            maxCells: z.number().int().min(0).max(1000000).optional(),
+            maxPayloadBytes: z.number().int().min(0).optional(),
+            maxEstimatedTokens: z.number().int().min(0).optional()
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, async (args) => jsonResult(await compactTableRead(args)));
     registerMcpTool(mcp, "excel.table.create", {
         title: "Create Excel table",
         description: "Create a structured table from a range, optionally writing values first.",
@@ -3641,6 +3981,36 @@ function registerValidateTools(mcp) {
         inputSchema: { workbookId: z.string() },
         annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
     }, async ({ workbookId }) => jsonResult(await runtime.validateWorkbook({ workbookId: workbookId })));
+    registerMcpTool(mcp, "excel.validate.compact", {
+        title: "Run compact validation",
+        description: "Run a validator and return concise issue counts/examples with full details stored behind a compact resource URI.",
+        inputSchema: {
+            workbookId: z.string(),
+            validator: z.enum([
+                "workbook",
+                "sheet",
+                "formulas",
+                "styles",
+                "tables",
+                "filters",
+                "print_layout",
+                "no_broken_references",
+                "no_formula_errors",
+                "no_unintended_changes"
+            ]),
+            sheetName: z.string().optional(),
+            address: z.string().optional(),
+            tableName: z.string().optional(),
+            templateId: z.string().optional(),
+            snapshotId: z.string().optional(),
+            leftSnapshotId: z.string().optional(),
+            rightSnapshotId: z.string().optional(),
+            maxIssues: z.number().int().min(0).max(100).optional(),
+            maxPayloadBytes: z.number().int().min(0).optional(),
+            maxEstimatedTokens: z.number().int().min(0).optional()
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, async (args) => jsonResult(await compactValidation(args)));
     registerMcpTool(mcp, "excel.validate.sheet", {
         title: "Validate sheet",
         description: "Validate one worksheet's used range and formula-error state.",
@@ -3861,13 +4231,13 @@ function registerSnapshotTools(mcp) {
                 if (!existing.ok || !("snapshot" in existing)) {
                     return jsonResult(existing);
                 }
-                return jsonResult(await runtime.createWorkbookSnapshot({
+                return jsonResult(compactSnapshotCreationResult(await runtime.createWorkbookSnapshot({
                     workbookId: existing.snapshot.workbookId,
                     reason: args.reason ?? `Refresh snapshot ${args.snapshotId}`,
                     ranges: existing.snapshot.affectedRanges
-                }));
+                })));
             }
-            return jsonResult(await runtime.createWorkbookSnapshot(snapshotRequest(args.workbookId, args.reason, args.ranges)));
+            return jsonResult(compactSnapshotCreationResult(await runtime.createWorkbookSnapshot(snapshotRequest(args.workbookId, args.reason, args.ranges))));
         });
     }
     registerMcpTool(mcp, "excel.snapshot.get", {
@@ -3876,6 +4246,12 @@ function registerSnapshotTools(mcp) {
         inputSchema: { snapshotId: z.string() },
         annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
     }, async ({ snapshotId }) => jsonResult(runtime.getSnapshot(snapshotId)));
+    registerMcpTool(mcp, "excel.snapshot.get_compact", {
+        title: "Get compact snapshot",
+        description: "Return snapshot metadata and store full snapshot payload behind a compact resource URI.",
+        inputSchema: { snapshotId: z.string(), maxPayloadBytes: z.number().int().min(0).optional(), maxEstimatedTokens: z.number().int().min(0).optional() },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, ({ snapshotId, maxPayloadBytes, maxEstimatedTokens }) => jsonResult(compactSnapshot(snapshotId, maxPayloadBytes, maxEstimatedTokens)));
     registerMcpTool(mcp, "excel.snapshot.list", {
         title: "List snapshots",
         description: "List stored snapshots for a workbook.",
@@ -3891,6 +4267,17 @@ function registerSnapshotTools(mcp) {
         },
         annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
     }, async ({ leftSnapshotId, rightSnapshotId }) => jsonResult(runtime.compareSnapshots(leftSnapshotId, rightSnapshotId)));
+    registerMcpTool(mcp, "excel.snapshot.compare_compact", {
+        title: "Compare snapshots compactly",
+        description: "Return a compact snapshot diff summary and store full diff details behind a compact resource URI.",
+        inputSchema: {
+            leftSnapshotId: z.string(),
+            rightSnapshotId: z.string(),
+            maxPayloadBytes: z.number().int().min(0).optional(),
+            maxEstimatedTokens: z.number().int().min(0).optional()
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, ({ leftSnapshotId, rightSnapshotId, maxPayloadBytes, maxEstimatedTokens }) => jsonResult(compactSnapshotDiff(leftSnapshotId, rightSnapshotId, maxPayloadBytes, maxEstimatedTokens)));
     registerMcpTool(mcp, "excel.snapshot.invalidate", {
         title: "Invalidate snapshot",
         description: "Mark a snapshot as stale without deleting it.",
@@ -3919,6 +4306,17 @@ function registerDiffTools(mcp) {
             return jsonResult(name.endsWith("export_json") ? { ok: true, json: JSON.stringify(diff, null, 2) } : diff);
         });
     }
+    registerMcpTool(mcp, "excel.diff.get_compact", {
+        title: "Get compact diff",
+        description: "Return a compact diff summary and store full diff details behind a compact resource URI.",
+        inputSchema: {
+            leftSnapshotId: z.string(),
+            rightSnapshotId: z.string(),
+            maxPayloadBytes: z.number().int().min(0).optional(),
+            maxEstimatedTokens: z.number().int().min(0).optional()
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, ({ leftSnapshotId, rightSnapshotId, maxPayloadBytes, maxEstimatedTokens }) => jsonResult(compactSnapshotDiff(leftSnapshotId, rightSnapshotId, maxPayloadBytes, maxEstimatedTokens)));
     registerMcpTool(mcp, "excel.diff.export_html", {
         title: "Export diff HTML",
         description: "Return a small HTML representation of a snapshot diff.",
@@ -3965,6 +4363,53 @@ function registerEventTools(mcp) {
         annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     }, async ({ debounceMs }) => jsonResult(runtime.setEventDebounce(debounceMs)));
 }
+function registerCompactTools(mcp) {
+    registerMcpTool(mcp, "excel.compact.get_resource", {
+        title: "Get compact detail resource",
+        description: "Fetch stored compact detail metadata by default. Set includePayload only when full detail is required.",
+        inputSchema: {
+            resourceId: z.string().optional(),
+            resourceUri: z.string().optional(),
+            mode: z.enum(["metadata", "preview", "page", "full"]).optional(),
+            includePayload: z.boolean().optional(),
+            maxPayloadBytes: z.number().int().min(0).optional(),
+            maxEstimatedTokens: z.number().int().min(0).optional(),
+            offset: z.number().int().min(0).optional(),
+            limit: z.number().int().min(1).max(24000).optional()
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, ({ resourceId, resourceUri, mode, includePayload, maxPayloadBytes, maxEstimatedTokens, offset, limit }) => jsonResult(getCompactResource(resourceId ?? compactResourceIdFromUri(resourceUri ?? ""), compactResourceReadOptions({ mode, includePayload, maxPayloadBytes, maxEstimatedTokens, offset, limit }))));
+    registerMcpTool(mcp, "excel.compact.list_resources", {
+        title: "List compact detail resources",
+        description: "List stored compact detail resources without returning their payloads.",
+        inputSchema: { kind: z.string().optional(), limit: z.number().int().min(1).max(COMPACT_RESOURCE_LIMIT).optional() },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, ({ kind, limit }) => jsonResult(listCompactResources(kind, limit)));
+    registerMcpTool(mcp, "excel.compact.delete_resource", {
+        title: "Delete compact detail resource",
+        description: "Delete one stored compact detail payload.",
+        inputSchema: { resourceId: z.string().optional(), resourceUri: z.string().optional() },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, ({ resourceId, resourceUri }) => jsonResult(deleteCompactResource(resourceId ?? compactResourceIdFromUri(resourceUri ?? ""))));
+    registerMcpTool(mcp, "excel.compact.clear_resources", {
+        title: "Clear compact detail resources",
+        description: "Clear stored compact detail payloads from this MCP process.",
+        inputSchema: { kind: z.string().optional() },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, ({ kind }) => jsonResult(clearCompactResources(kind)));
+    registerMcpTool(mcp, "excel.compact.get_cache_status", {
+        title: "Get compact cache status",
+        description: "Return compact summary/schema cache size and invalidation metadata.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, () => jsonResult(getCompactCacheStatus()));
+    registerMcpTool(mcp, "excel.compact.clear_cache", {
+        title: "Clear compact cache",
+        description: "Clear compact summary/schema cache entries from this MCP process.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    }, () => jsonResult(clearCompactCache("manual")));
+}
 function rangeReadFacets(toolName) {
     switch (toolName) {
         case "excel.range.read_values":
@@ -4048,137 +4493,1652 @@ function tableReadRequest(args) {
     }
     return request;
 }
-function tableCreateRequest(args) {
-    const request = {
-        workbookId: args.workbookId,
-        sheetName: args.sheetName,
-        address: args.address,
-        hasHeaders: args.hasHeaders
-    };
-    if (args.tableName !== undefined) {
-        request.tableName = args.tableName;
-    }
-    if (args.values !== undefined) {
-        request.values = args.values;
-    }
-    if (args.style !== undefined) {
-        request.style = args.style;
-    }
-    if (args.showTotals !== undefined) {
-        request.showTotals = args.showTotals;
-    }
-    return request;
-}
-function tableFilterSchema() {
-    return {
-        ...tableSelectorSchema(),
-        filters: z.array(z.object({
-            column: z.union([z.string(), z.number().int().min(0)]),
-            criteria: z.record(z.string(), z.any())
-        }))
-    };
-}
-function tableSortSchema() {
+function withCompactTelemetry(payload, options) {
+    const originalPayloadBytes = Buffer.byteLength(JSON.stringify(payload), "utf8");
+    const originalEstimatedTokens = Math.ceil(originalPayloadBytes / 4);
+    const maxPayloadBytes = options.maxPayloadBytes ?? (options.budgetSummary !== undefined ? COMPACT_DEFAULT_RESOURCE_THRESHOLD_BYTES : undefined);
+    const overBudget = (maxPayloadBytes !== undefined && originalPayloadBytes > maxPayloadBytes) ||
+        (options.maxEstimatedTokens !== undefined && originalEstimatedTokens > options.maxEstimatedTokens);
+    const stored = options.storeResource || overBudget
+        ? storeCompactResource(options.resourceKind ?? "generic", options.resourcePayload ?? payload, options.resourceTitle)
+        : undefined;
+    const output = overBudget && options.budgetSummary !== undefined
+        ? {
+            ...options.budgetSummary,
+            budgetExceeded: true,
+            warnings: [
+                ...asWarningArray(options.budgetSummary.warnings),
+                {
+                    code: "COMPACT_BUDGET_EXCEEDED",
+                    message: "Full compact detail exceeded the response budget and was stored behind resourceUri."
+                }
+            ],
+            resourcePayloadBytes: originalPayloadBytes,
+            resourceEstimatedTokens: originalEstimatedTokens
+        }
+        : payload;
+    const payloadBytes = Buffer.byteLength(JSON.stringify(output), "utf8");
     return {
-        ...tableSelectorSchema(),
-        fields: z.array(z.object({
-            key: z.number().int().min(0),
-            ascending: z.boolean().optional(),
-            sortOn: z.enum(["Value", "CellColor", "FontColor", "Icon"]).optional(),
-            color: z.string().optional(),
-            dataOption: z.enum(["Normal", "TextAsNumber"]).optional()
-        })),
-        matchCase: z.boolean().optional(),
-        method: z.enum(["PinYin", "StrokeCount"]).optional()
+        ...output,
+        payloadBytes,
+        estimatedTokens: Math.ceil(payloadBytes / 4),
+        truncated: options.truncated ?? false,
+        detailLevel: options.detailLevel,
+        ...(options.nextPage !== undefined ? { nextPage: options.nextPage } : {}),
+        ...(stored !== undefined ? { resourceUri: stored.uri } : options.resourceUri !== undefined ? { resourceUri: options.resourceUri } : {})
     };
 }
-function nameSelectorSchema() {
-    return {
-        workbookId: z.string(),
-        name: z.string(),
-        sheetName: z.string().optional()
-    };
+function asWarningArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "object" && item !== null) : [];
 }
-function nameMutationSchema() {
-    return {
-        ...nameSelectorSchema(),
-        reference: z.string().optional(),
-        formula: z.string().optional(),
-        comment: z.string().optional(),
-        visible: z.boolean().optional()
+function storeCompactResource(kind, payload, title) {
+    const resourceId = makeId("compact");
+    const payloadBytes = Buffer.byteLength(JSON.stringify(payload), "utf8");
+    const resource = {
+        resourceId,
+        uri: `excel://compact/${resourceId}`,
+        kind,
+        title,
+        createdAt: new Date().toISOString(),
+        payloadBytes,
+        estimatedTokens: Math.ceil(payloadBytes / 4),
+        payload
     };
+    compactResources.set(resourceId, resource);
+    while (compactResources.size > COMPACT_RESOURCE_LIMIT) {
+        const oldestKey = compactResources.keys().next().value;
+        if (oldestKey === undefined) {
+            break;
+        }
+        compactResources.delete(oldestKey);
+    }
+    return resource;
 }
-function nameSelector(args) {
-    const request = {
-        workbookId: args.workbookId,
-        name: args.name
-    };
-    if (args.sheetName !== undefined) {
-        request.sheetName = args.sheetName;
+function getCompactResource(resourceId, options = {}) {
+    const resource = compactResources.get(compactResourceIdFromUri(resourceId));
+    if (!resource) {
+        return { ok: false, error: { code: "COMPACT_RESOURCE_NOT_FOUND", message: "Compact detail resource was not found or has expired." } };
     }
-    return request;
+    const { payload, ...summary } = resource;
+    const mode = options.mode ?? (options.includePayload === true ? "full" : "metadata");
+    if (mode === "metadata") {
+        return {
+            ok: true,
+            ...summary,
+            payloadAvailable: true,
+            payloadIncluded: false,
+            message: "Use mode=preview or mode=page for bounded inspection, or mode=full/includePayload=true for full detail."
+        };
+    }
+    if (mode === "preview" || mode === "page") {
+        const serialized = JSON.stringify(payload, null, 2);
+        const defaultLimit = mode === "preview" ? 4000 : COMPACT_DEFAULT_RESOURCE_THRESHOLD_BYTES;
+        const limit = Math.max(1, Math.min(options.limit ?? defaultLimit, COMPACT_DEFAULT_RESOURCE_THRESHOLD_BYTES));
+        const offset = Math.max(0, Math.min(options.offset ?? 0, serialized.length));
+        const text = serialized.slice(offset, offset + limit);
+        const nextOffset = offset + text.length < serialized.length ? offset + text.length : undefined;
+        return {
+            ok: true,
+            ...summary,
+            payloadAvailable: true,
+            payloadIncluded: false,
+            mode,
+            format: "json-text",
+            offset,
+            limit,
+            text,
+            textBytes: Buffer.byteLength(text, "utf8"),
+            totalCharacters: serialized.length,
+            totalBytes: Buffer.byteLength(serialized, "utf8"),
+            ...(nextOffset !== undefined ? { nextOffset } : {})
+        };
+    }
+    const overBudget = (options.maxPayloadBytes !== undefined && resource.payloadBytes > options.maxPayloadBytes) ||
+        (options.maxEstimatedTokens !== undefined && resource.estimatedTokens > options.maxEstimatedTokens);
+    if (overBudget) {
+        return {
+            ok: true,
+            ...summary,
+            payloadAvailable: true,
+            payloadIncluded: false,
+            budgetExceeded: true,
+            warnings: [
+                {
+                    code: "COMPACT_RESOURCE_BUDGET_EXCEEDED",
+                    message: "Stored detail exceeded the requested response budget. Raise the budget or inspect a smaller resource."
+                }
+            ]
+        };
+    }
+    return { ok: true, ...summary, payloadAvailable: true, payloadIncluded: true, payload };
 }
-function nameCreateRequest(args) {
-    const request = nameSelector(args);
-    if (args.reference !== undefined) {
-        request.reference = args.reference;
+function compactResourceReadOptions(options) {
+    const normalized = {};
+    if (options.mode !== undefined) {
+        normalized.mode = options.mode;
     }
-    if (args.formula !== undefined) {
-        request.formula = args.formula;
+    if (options.includePayload !== undefined) {
+        normalized.includePayload = options.includePayload;
     }
-    if (args.comment !== undefined) {
-        request.comment = args.comment;
+    if (options.maxPayloadBytes !== undefined) {
+        normalized.maxPayloadBytes = options.maxPayloadBytes;
     }
-    if (args.visible !== undefined) {
-        request.visible = args.visible;
+    if (options.maxEstimatedTokens !== undefined) {
+        normalized.maxEstimatedTokens = options.maxEstimatedTokens;
     }
-    return request;
+    if (options.offset !== undefined) {
+        normalized.offset = options.offset;
+    }
+    if (options.limit !== undefined) {
+        normalized.limit = options.limit;
+    }
+    return normalized;
 }
-function nameUpdateRequest(args) {
-    return nameCreateRequest(args);
+function listCompactResources(kind, limit = COMPACT_RESOURCE_LIMIT) {
+    const resources = [...compactResources.values()]
+        .filter((resource) => kind === undefined || resource.kind === kind)
+        .slice(-limit)
+        .map(({ payload, ...summary }) => summary);
+    return { ok: true, resources };
 }
-function regionSelectorSchema() {
-    return {
-        workbookId: z.string(),
-        regionName: z.string()
-    };
+function deleteCompactResource(resourceId) {
+    const normalized = compactResourceIdFromUri(resourceId);
+    return { ok: compactResources.delete(normalized), resourceId: normalized };
 }
-function regionSelector(args) {
-    return {
-        workbookId: args.workbookId,
-        regionName: args.regionName
-    };
+function clearCompactResources(kind) {
+    let deleted = 0;
+    for (const [resourceId, resource] of compactResources) {
+        if (kind === undefined || resource.kind === kind) {
+            compactResources.delete(resourceId);
+            deleted += 1;
+        }
+    }
+    return { ok: true, deleted };
 }
-function pivotSelectorSchema() {
-    return {
-        workbookId: z.string(),
-        pivotTableName: z.string()
-    };
+function compactResourceIdFromUri(value) {
+    return value.startsWith("excel://compact/") ? value.slice("excel://compact/".length) : value;
 }
-function pivotSelector(args) {
-    return {
-        workbookId: args.workbookId,
-        pivotTableName: args.pivotTableName
-    };
+async function compactCacheValue(key, producer) {
+    await invalidateCompactCacheForWorkbookEvents();
+    const cached = compactCache.get(key);
+    if (cached !== undefined) {
+        return cached.value;
+    }
+    const value = await producer();
+    compactCache.set(key, { key, createdAt: new Date().toISOString(), value });
+    return value;
 }
-function pivotValidateSourceRequest(args) {
+async function invalidateCompactCacheForWorkbookEvents() {
+    try {
+        const recent = await runtime.getRecentEvents(1);
+        const event = recent.events?.[0];
+        if (!event?.eventId || event.eventId === compactLastObservedEventId) {
+            return;
+        }
+        compactLastObservedEventId = event.eventId;
+        if (event.method !== "addin.heartbeat") {
+            clearCompactCache(`event:${event.method ?? "unknown"}`);
+        }
+    }
+    catch {
+        // Compact caching must never make read-only workbook discovery fail.
+    }
+}
+function getCompactCacheStatus() {
     return {
-        ...pivotSelector(args),
-        ...(args.expectedFields !== undefined ? { expectedFields: args.expectedFields } : {}),
-        ...(args.expectedRowFields !== undefined ? { expectedRowFields: args.expectedRowFields } : {}),
-        ...(args.expectedColumnFields !== undefined ? { expectedColumnFields: args.expectedColumnFields } : {}),
-        ...(args.expectedFilterFields !== undefined ? { expectedFilterFields: args.expectedFilterFields } : {}),
-        ...(args.expectedDataFields !== undefined ? { expectedDataFields: args.expectedDataFields } : {}),
-        ...(args.expectedDataFieldSettings !== undefined ? { expectedDataFieldSettings: args.expectedDataFieldSettings } : {}),
-        ...(args.expectedLayout !== undefined ? { expectedLayout: args.expectedLayout } : {})
+        ok: true,
+        size: compactCache.size,
+        invalidationCount: compactCacheInvalidationCount,
+        lastInvalidatedAt: compactCacheLastInvalidatedAt,
+        keys: [...compactCache.keys()]
     };
 }
-function pivotCreateRequest(args) {
-    const request = {
-        workbookId: args.workbookId,
-        pivotTableName: args.pivotTableName,
-        destinationSheetName: args.destinationSheetName,
-        destinationAddress: args.destinationAddress
+function clearCompactCache(reason) {
+    const cleared = compactCache.size;
+    compactCache.clear();
+    compactCacheInvalidationCount += 1;
+    compactCacheLastInvalidatedAt = new Date().toISOString();
+    return { ok: true, cleared, reason, invalidationCount: compactCacheInvalidationCount, invalidatedAt: compactCacheLastInvalidatedAt };
+}
+async function workbookSummary(workbookId) {
+    return compactCacheValue(`workbookSummary:${workbookId ?? "active"}`, async () => {
+        const result = await runtime.getWorkbookMap();
+        const map = "map" in result ? result.map : undefined;
+        if (!result.ok || !map) {
+            return withCompactTelemetry({ ok: false, workbookId, source: result }, { detailLevel: "summary" });
+        }
+        const sheets = map.sheets ?? [];
+        const tableNames = sheets.flatMap((sheet) => (sheet.tables ?? []).map((table) => table.name));
+        const usedRangeCells = sheets.reduce((sum, sheet) => sum + usedRangeCellCount(sheet.usedRange), 0);
+        return withCompactTelemetry({
+            ok: true,
+            workbook: map.workbook,
+            workbookId: workbookId ?? map.workbook?.workbookId,
+            sheetCount: sheets.length,
+            tableCount: tableNames.length,
+            usedRangeCells,
+            sheets: sheets.map((sheet) => ({
+                name: sheet.name,
+                position: sheet.position,
+                visibility: sheet.visibility,
+                usedRange: sheet.usedRange,
+                tableCount: sheet.tables?.length ?? 0,
+                tables: (sheet.tables ?? []).map((table) => table.name)
+            }))
+        }, { detailLevel: "summary" });
+    });
+}
+async function workbookUsedRangeSummary(workbookId) {
+    return compactCacheValue(`workbookUsedRangeSummary:${workbookId ?? "active"}`, async () => {
+        const result = await runtime.getWorkbookMap();
+        const map = "map" in result ? result.map : undefined;
+        if (!result.ok || !map) {
+            return withCompactTelemetry({ ok: false, workbookId, source: result }, { detailLevel: "summary" });
+        }
+        const sheets = map.sheets ?? [];
+        return withCompactTelemetry({
+            ok: true,
+            workbookId: workbookId ?? map.workbook?.workbookId,
+            usedRanges: sheets.map((sheet) => ({
+                sheetName: sheet.name,
+                usedRange: sheet.usedRange,
+                cellCount: usedRangeCellCount(sheet.usedRange)
+            })),
+            totalCells: sheets.reduce((sum, sheet) => sum + usedRangeCellCount(sheet.usedRange), 0)
+        }, { detailLevel: "summary" });
+    });
+}
+async function sheetSummary(sheetName, workbookId) {
+    return compactCacheValue(`sheetSummary:${workbookId ?? "active"}:${sheetName}`, async () => {
+        const info = await selectSheetInfo(sheetName);
+        const workbook = info.result.map?.workbook;
+        return withCompactTelemetry({
+            ok: info.ok,
+            workbookId: workbookId ?? workbook?.workbookId,
+            sheetName,
+            usedRange: info.sheet?.usedRange,
+            cellCount: usedRangeCellCount(info.sheet?.usedRange),
+            tableCount: info.sheet?.tables?.length ?? 0,
+            tables: (info.sheet?.tables ?? []).map((table) => table.name),
+            sheet: info.sheet
+        }, { detailLevel: "summary" });
+    });
+}
+function rangeSummary(workbookId, sheetName, address) {
+    const parsed = parseCompactA1Address(address);
+    const rowCount = parsed.endRow - parsed.startRow + 1;
+    const columnCount = parsed.endColumn - parsed.startColumn + 1;
+    const defaultRows = Math.min(rowCount, 50);
+    const defaultColumns = Math.min(columnCount, 25);
+    return withCompactTelemetry({
+        ok: true,
+        workbookId,
+        sheetName,
+        address,
+        rowCount,
+        columnCount,
+        cellCount: rowCount * columnCount,
+        defaultCompactWindow: {
+            address: compactWindowAddress(address, 0, 0, defaultRows, defaultColumns),
+            rowCount: defaultRows,
+            columnCount: defaultColumns,
+            cellCount: defaultRows * defaultColumns
+        }
+    }, { detailLevel: "summary", truncated: rowCount > defaultRows || columnCount > defaultColumns });
+}
+async function compactRangeRead(args) {
+    const mode = args.mode ?? "window";
+    const parsed = parseCompactA1Address(args.address);
+    const sourceRowCount = parsed.endRow - parsed.startRow + 1;
+    const sourceColumnCount = parsed.endColumn - parsed.startColumn + 1;
+    const rowOffset = Math.min(args.rowOffset ?? 0, sourceRowCount);
+    const columnOffset = Math.min(args.columnOffset ?? 0, sourceColumnCount);
+    const maxRows = args.maxRows ?? 50;
+    const maxColumns = args.maxColumns ?? 25;
+    const availableRows = Math.max(0, sourceRowCount - rowOffset);
+    const availableColumns = Math.max(0, sourceColumnCount - columnOffset);
+    const columnLimit = Math.min(maxColumns, availableColumns);
+    const maxRowsByCells = args.maxCells !== undefined && columnLimit > 0 ? Math.floor(args.maxCells / columnLimit) : maxRows;
+    const rowLimit = Math.min(maxRows, maxRowsByCells, availableRows);
+    const windowAddress = rowLimit > 0 && columnLimit > 0
+        ? compactWindowAddress(args.address, rowOffset, columnOffset, rowLimit, columnLimit)
+        : compactWindowAddress(args.address, rowOffset, columnOffset, 1, 1);
+    const truncated = rowOffset + rowLimit < sourceRowCount || columnOffset + columnLimit < sourceColumnCount;
+    const summary = {
+        workbookId: args.workbookId,
+        sheetName: args.sheetName,
+        address: args.address,
+        mode,
+        source: {
+            rowCount: sourceRowCount,
+            columnCount: sourceColumnCount,
+            cellCount: sourceRowCount * sourceColumnCount
+        },
+        window: {
+            address: windowAddress,
+            rowOffset,
+            columnOffset,
+            rowCount: rowLimit,
+            columnCount: columnLimit,
+            cellCount: rowLimit * columnLimit
+        },
+        sampled: mode === "sample"
+    };
+    const nextPage = truncated ? { rowOffset: rowOffset + rowLimit, columnOffset } : undefined;
+    if (mode === "summary" || rowLimit === 0 || columnLimit === 0) {
+        return withCompactTelemetry({ ok: true, ...summary }, { detailLevel: "summary", truncated, nextPage, maxPayloadBytes: args.maxPayloadBytes, maxEstimatedTokens: args.maxEstimatedTokens, resourceKind: "read", resourceTitle: "Compact range summary", budgetSummary: { ok: true, ...summary } });
+    }
+    const facets = compactRangeFacets(args);
+    if (facets.length === 0) {
+        return withCompactTelemetry({ ok: true, ...summary }, { detailLevel: "compact", truncated, nextPage, maxPayloadBytes: args.maxPayloadBytes, maxEstimatedTokens: args.maxEstimatedTokens, resourceKind: "read", resourceTitle: "Compact range read", budgetSummary: { ok: true, ...summary } });
+    }
+    if (mode === "sample" && sourceRowCount > rowLimit) {
+        const samples = await Promise.all(compactSampleWindows(sourceRowCount, rowLimit).map(async (sample) => {
+            const sampleAddress = compactWindowAddress(args.address, sample.rowOffset, columnOffset, sample.rowCount, columnLimit);
+            const sampleResult = await readRangeSnapshot(args.workbookId, args.sheetName, sampleAddress, facets);
+            const sampleSnapshot = (sampleResult.data ?? [])[0]?.snapshot;
+            const compactSnapshot = compactRangeSnapshotPayload(sampleSnapshot, facets);
+            return {
+                label: sample.label,
+                rowOffset: sample.rowOffset,
+                rowCount: sample.rowCount,
+                address: sampleAddress,
+                ...compactSnapshot,
+                ok: sampleResult.ok,
+                warnings: sampleResult.warnings ?? []
+            };
+        }));
+        return withCompactTelemetry({ ok: true, ...summary, samples }, {
+            detailLevel: "compact",
+            truncated,
+            maxPayloadBytes: args.maxPayloadBytes,
+            maxEstimatedTokens: args.maxEstimatedTokens,
+            resourceKind: "read",
+            resourceTitle: "Compact range sample",
+            budgetSummary: { ok: true, ...summary, sampleCount: samples.length }
+        });
+    }
+    const result = await readRangeSnapshot(args.workbookId, args.sheetName, windowAddress, facets);
+    if (!result.ok) {
+        return withCompactTelemetry({ ok: false, ...summary, source: result }, { detailLevel: "compact", truncated, nextPage, maxPayloadBytes: args.maxPayloadBytes, maxEstimatedTokens: args.maxEstimatedTokens, resourceKind: "read", resourceTitle: "Compact range read error", budgetSummary: { ok: false, ...summary } });
+    }
+    const snapshot = (result.data ?? [])[0]?.snapshot;
+    const compactSnapshot = compactRangeSnapshotPayload(snapshot, facets);
+    return withCompactTelemetry({
+        ok: true,
+        ...summary,
+        ...compactSnapshot,
+        warnings: result.warnings ?? [],
+        telemetry: result.telemetry
+    }, {
+        detailLevel: "compact",
+        truncated,
+        nextPage,
+        maxPayloadBytes: args.maxPayloadBytes,
+        maxEstimatedTokens: args.maxEstimatedTokens,
+        resourceKind: "read",
+        resourceTitle: "Compact range read",
+        budgetSummary: { ok: true, ...summary, warnings: result.warnings ?? [] }
+    });
+}
+async function tableSchema(selector) {
+    return compactCacheValue(`tableSchema:${selector.workbookId}:${selector.tableName}`, async () => {
+        const result = await runtime.getTableInfo(selector);
+        const info = result.info;
+        return withCompactTelemetry({
+            ok: Boolean(result.ok && info),
+            workbookId: selector.workbookId,
+            tableName: selector.tableName,
+            schema: info ? tableInfoSchema(info) : undefined,
+            source: info ? undefined : result
+        }, { detailLevel: "summary" });
+    });
+}
+function compactRangeSnapshotPayload(snapshot, facets) {
+    if (!snapshot || typeof snapshot !== "object") {
+        return {};
+    }
+    const matrixEntries = [
+        ["values", snapshot.values],
+        ["formulas", snapshot.formulas],
+        ["text", snapshot.text],
+        ["numberFormat", snapshot.numberFormat],
+        ["style", snapshot.style]
+    ];
+    const requestedEntries = matrixEntries.filter(([name, value]) => compactFacetOutputRequested(name, facets) && Array.isArray(value));
+    const bounds = compactMatrixBounds(requestedEntries.map(([, value]) => value));
+    const output = {};
+    if (snapshot.fingerprint !== undefined) {
+        output.fingerprint = snapshot.fingerprint;
+    }
+    for (const [name, value] of requestedEntries) {
+        output[name] = trimMatrixToBounds(value, bounds);
+    }
+    if (bounds.sourceRows > bounds.rows || bounds.sourceColumns > bounds.columns) {
+        output.omittedEmpty = {
+            trailingRows: Math.max(0, bounds.sourceRows - bounds.rows),
+            trailingColumns: Math.max(0, bounds.sourceColumns - bounds.columns),
+            sourceRows: bounds.sourceRows,
+            sourceColumns: bounds.sourceColumns,
+            returnedRows: bounds.rows,
+            returnedColumns: bounds.columns
+        };
+    }
+    return output;
+}
+function compactFacetOutputRequested(name, facets) {
+    if (name === "numberFormat") {
+        return facets.includes("numberFormat");
+    }
+    if (name === "style") {
+        return facets.includes("style");
+    }
+    return facets.includes(name);
+}
+function compactMatrixBounds(matrices) {
+    const sourceRows = matrices.reduce((max, matrix) => Math.max(max, matrix.length), 0);
+    const sourceColumns = matrices.reduce((max, matrix) => Math.max(max, ...matrix.map((row) => Array.isArray(row) ? row.length : 0)), 0);
+    let lastRow = -1;
+    let lastColumn = -1;
+    for (const matrix of matrices) {
+        for (let rowIndex = 0; rowIndex < matrix.length; rowIndex += 1) {
+            const row = matrix[rowIndex];
+            if (!Array.isArray(row)) {
+                continue;
+            }
+            for (let columnIndex = 0; columnIndex < row.length; columnIndex += 1) {
+                if (!isCompactEmptyCell(row[columnIndex])) {
+                    lastRow = Math.max(lastRow, rowIndex);
+                    lastColumn = Math.max(lastColumn, columnIndex);
+                }
+            }
+        }
+    }
+    return {
+        sourceRows,
+        sourceColumns,
+        rows: lastRow + 1,
+        columns: lastColumn + 1
+    };
+}
+function trimMatrixToBounds(matrix, bounds) {
+    if (bounds.rows === 0 || bounds.columns === 0) {
+        return [];
+    }
+    return matrix.slice(0, bounds.rows).map((row) => Array.isArray(row) ? row.slice(0, bounds.columns) : []);
+}
+function isCompactEmptyCell(value) {
+    if (value === undefined || value === null || value === "") {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return value.every(isCompactEmptyCell);
+    }
+    if (typeof value === "object") {
+        return Object.keys(value).length === 0;
+    }
+    return false;
+}
+function compactTablePayload(table) {
+    if (!table || typeof table !== "object") {
+        return {};
+    }
+    const matrixEntries = [
+        ["values", table.values],
+        ["formulas", table.formulas],
+        ["text", table.text],
+        ["numberFormat", table.numberFormat]
+    ];
+    const requestedEntries = matrixEntries.filter(([, value]) => Array.isArray(value));
+    const rowBounds = compactTableRowBounds(requestedEntries.map(([, value]) => value));
+    const output = {};
+    if (table.headers !== undefined) {
+        output.headers = table.headers;
+    }
+    for (const [name, value] of requestedEntries) {
+        output[name] = value.slice(0, rowBounds.rows);
+    }
+    if (rowBounds.sourceRows > rowBounds.rows) {
+        output.omittedEmpty = {
+            trailingRows: rowBounds.sourceRows - rowBounds.rows,
+            sourceRows: rowBounds.sourceRows,
+            returnedRows: rowBounds.rows
+        };
+    }
+    return output;
+}
+function compactTableRowBounds(matrices) {
+    const sourceRows = matrices.reduce((max, matrix) => Math.max(max, matrix.length), 0);
+    let lastRow = -1;
+    for (const matrix of matrices) {
+        for (let rowIndex = 0; rowIndex < matrix.length; rowIndex += 1) {
+            const row = matrix[rowIndex];
+            if (Array.isArray(row) && row.some((cell) => !isCompactEmptyCell(cell))) {
+                lastRow = Math.max(lastRow, rowIndex);
+            }
+        }
+    }
+    return { sourceRows, rows: lastRow + 1 };
+}
+async function compactTableRead(args) {
+    const mode = args.mode ?? "window";
+    const schemaResult = await runtime.getTableInfo(tableSelector(args));
+    const info = schemaResult.info;
+    if (!schemaResult.ok || !info) {
+        return withCompactTelemetry({ ok: false, workbookId: args.workbookId, tableName: args.tableName, source: schemaResult }, { detailLevel: "summary" });
+    }
+    const selectedColumns = compactTableColumns(info, args.columns, args.maxColumns);
+    const rowOffset = Math.min(args.rowOffset ?? 0, info.rowCount);
+    const maxRows = args.maxRows ?? 50;
+    const maxRowsByCells = args.maxCells !== undefined && selectedColumns.length > 0 ? Math.floor(args.maxCells / selectedColumns.length) : maxRows;
+    const rowLimit = Math.min(maxRows, maxRowsByCells, Math.max(0, info.rowCount - rowOffset));
+    const truncated = rowOffset + rowLimit < info.rowCount || selectedColumns.length < info.columnCount;
+    const summary = {
+        workbookId: args.workbookId,
+        tableName: args.tableName,
+        mode,
+        schema: tableInfoSchema(info),
+        rowOffset,
+        rowLimit,
+        projectedColumns: selectedColumns,
+        sampled: mode === "sample"
+    };
+    const nextPage = truncated && rowOffset + rowLimit < info.rowCount ? { rowOffset: rowOffset + rowLimit } : undefined;
+    if (mode === "summary" || rowLimit === 0 || selectedColumns.length === 0) {
+        return withCompactTelemetry({ ok: true, ...summary }, { detailLevel: "summary", truncated, nextPage, maxPayloadBytes: args.maxPayloadBytes, maxEstimatedTokens: args.maxEstimatedTokens, resourceKind: "read", resourceTitle: "Compact table summary", budgetSummary: { ok: true, ...summary } });
+    }
+    if (mode === "sample" && info.rowCount > rowLimit) {
+        const samples = await Promise.all(compactSampleWindows(info.rowCount, rowLimit).map(async (sample) => {
+            const sampleResult = await runtime.readTable({
+                ...tableSelector(args),
+                includeValues: args.includeValues ?? true,
+                includeFormulas: args.includeFormulas === true,
+                includeText: args.includeText === true,
+                includeNumberFormats: args.includeNumberFormats === true,
+                columns: selectedColumns.map((column) => column.name),
+                rowOffset: sample.rowOffset,
+                rowLimit: sample.rowCount
+            });
+            const sampleTable = sampleResult.table;
+            const compactTable = compactTablePayload(sampleTable);
+            return {
+                label: sample.label,
+                rowOffset: sample.rowOffset,
+                rowCount: sample.rowCount,
+                ok: sampleResult.ok,
+                ...compactTable
+            };
+        }));
+        return withCompactTelemetry({ ok: true, ...summary, samples }, {
+            detailLevel: "compact",
+            truncated,
+            maxPayloadBytes: args.maxPayloadBytes,
+            maxEstimatedTokens: args.maxEstimatedTokens,
+            resourceKind: "read",
+            resourceTitle: "Compact table sample",
+            budgetSummary: { ok: true, ...summary, sampleCount: samples.length }
+        });
+    }
+    const result = await runtime.readTable({
+        ...tableSelector(args),
+        includeValues: args.includeValues ?? true,
+        includeFormulas: args.includeFormulas === true,
+        includeText: args.includeText === true,
+        includeNumberFormats: args.includeNumberFormats === true,
+        columns: selectedColumns.map((column) => column.name),
+        rowOffset,
+        rowLimit
+    });
+    const table = result.table;
+    const compactTable = compactTablePayload(table);
+    return withCompactTelemetry({
+        ok: Boolean(result.ok),
+        ...summary,
+        ...compactTable,
+        source: result.ok ? undefined : result
+    }, {
+        detailLevel: "compact",
+        truncated,
+        nextPage,
+        maxPayloadBytes: args.maxPayloadBytes,
+        maxEstimatedTokens: args.maxEstimatedTokens,
+        resourceKind: "read",
+        resourceTitle: "Compact table read",
+        budgetSummary: { ok: Boolean(result.ok), ...summary }
+    });
+}
+async function lookupSearchWorkbook(args) {
+    const workbookId = args.workbookId;
+    const context = await lookupWorkbookContext(workbookId, args.sheetNames);
+    if (!context.ok) {
+        return withCompactTelemetry({ ok: false, workbookId, query: args.query, source: context.source }, { detailLevel: "summary" });
+    }
+    const matches = [];
+    if (args.includeSheets !== false) {
+        for (const sheet of context.sheets) {
+            if (lookupMatches(String(sheet.name), args.query, args)) {
+                matches.push(lookupMatch({
+                    kind: "sheet",
+                    sheetName: sheet.name,
+                    address: sheet.usedRange?.address,
+                    score: lookupScore(sheet.name, args.query, args.completeMatch),
+                    reason: "sheet name"
+                }));
+            }
+        }
+    }
+    if (args.includeTables !== false) {
+        matches.push(...lookupTableMatches(context.tables, args.query, args));
+    }
+    matches.push(...await lookupUsedRangeMatches(workbookId, context.sheets, args.query, args, "range"));
+    return compactLookupResponse({
+        workbookId,
+        query: args.query,
+        matches,
+        maxMatches: args.maxMatches ?? 25,
+        maxPayloadBytes: args.maxPayloadBytes,
+        maxEstimatedTokens: args.maxEstimatedTokens,
+        resourceTitle: `Workbook lookup: ${args.query}`
+    });
+}
+async function lookupFindHeaders(args) {
+    const workbookId = args.workbookId;
+    const terms = lookupTerms(args.headers ?? (args.query ? [args.query] : []));
+    const context = await lookupWorkbookContext(workbookId, args.sheetNames);
+    if (!context.ok) {
+        return withCompactTelemetry({ ok: false, workbookId, query: args.query, headers: args.headers, source: context.source }, { detailLevel: "summary" });
+    }
+    const matches = [];
+    for (const table of context.tables) {
+        for (const column of table.columns ?? []) {
+            const columnName = String(column.name ?? "");
+            if (terms.length === 0 || terms.some((term) => lookupMatches(columnName, term, args))) {
+                matches.push(lookupMatch({
+                    kind: "header",
+                    sheetName: table.sheetName,
+                    tableName: table.tableName,
+                    columnName,
+                    address: table.headerAddress ?? table.address,
+                    score: terms.length === 0 ? 0.55 : Math.max(...terms.map((term) => lookupScore(columnName, term, false))),
+                    reason: "table header",
+                    schema: { tableName: table.tableName, column }
+                }));
+            }
+        }
+    }
+    const maxRowsPerSheet = args.maxRowsPerSheet ?? 10;
+    const maxColumns = args.maxColumns ?? 50;
+    for (const sheet of context.sheets) {
+        const usedAddress = sheet.usedRange?.address;
+        if (!usedAddress) {
+            continue;
+        }
+        try {
+            const result = await compactRangeRead({
+                workbookId,
+                sheetName: sheet.name,
+                address: usedAddress,
+                mode: "window",
+                maxRows: maxRowsPerSheet,
+                maxColumns,
+                includeValues: true,
+                includeText: true
+            });
+            const rows = lookupRowsFromCompactRead(result);
+            for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
+                for (let columnIndex = 0; columnIndex < (rows[rowIndex] ?? []).length; columnIndex += 1) {
+                    const value = rows[rowIndex]?.[columnIndex];
+                    const text = value === undefined || value === null ? "" : String(value);
+                    if (text === "" || (terms.length > 0 && !terms.some((term) => lookupMatches(text, term, args)))) {
+                        continue;
+                    }
+                    matches.push(lookupMatch({
+                        kind: "header",
+                        sheetName: sheet.name,
+                        address: compactWindowAddress(usedAddress, rowIndex, columnIndex, 1, 1),
+                        columnName: text,
+                        score: terms.length === 0 ? Math.max(0.15, 0.5 - rowIndex * 0.03) : Math.max(...terms.map((term) => lookupScore(text, term, false))),
+                        reason: `bounded sheet header scan row ${rowIndex + 1}`
+                    }));
+                }
+            }
+        }
+        catch {
+            // Lookup should remain useful even when one sheet cannot be scanned.
+        }
+    }
+    return compactLookupResponse({
+        workbookId,
+        query: args.query,
+        headers: args.headers,
+        matches,
+        maxMatches: args.maxMatches ?? 25,
+        maxPayloadBytes: args.maxPayloadBytes,
+        maxEstimatedTokens: args.maxEstimatedTokens,
+        resourceTitle: "Header lookup"
+    });
+}
+async function lookupFindTablesByColumns(args) {
+    const workbookId = args.workbookId;
+    const context = await lookupWorkbookContext(workbookId);
+    if (!context.ok) {
+        return withCompactTelemetry({ ok: false, workbookId, requiredColumns: args.requiredColumns, source: context.source }, { detailLevel: "summary" });
+    }
+    const required = lookupTerms(args.requiredColumns);
+    const optional = lookupTerms(args.optionalColumns ?? []);
+    const matches = context.tables
+        .map((table) => {
+        const columns = (table.columns ?? []).map((column) => String(column.name ?? ""));
+        const requiredHits = required.filter((term) => columns.some((column) => lookupNormalized(column) === term || lookupNormalized(column).includes(term)));
+        if (required.length > 0 && requiredHits.length < required.length) {
+            return undefined;
+        }
+        const optionalHits = optional.filter((term) => columns.some((column) => lookupNormalized(column) === term || lookupNormalized(column).includes(term)));
+        const denominator = Math.max(1, required.length + optional.length * 0.5);
+        const score = Math.min(1, (requiredHits.length + optionalHits.length * 0.5) / denominator);
+        if (score < (args.minScore ?? 0)) {
+            return undefined;
+        }
+        return lookupMatch({
+            kind: "table",
+            sheetName: table.sheetName,
+            tableName: table.tableName,
+            address: table.address,
+            score,
+            reason: `matched ${requiredHits.length}/${required.length} required and ${optionalHits.length}/${optional.length} optional columns`,
+            schema: tableInfoSchema(table)
+        });
+    })
+        .filter((match) => match !== undefined);
+    return compactLookupResponse({
+        workbookId,
+        requiredColumns: args.requiredColumns,
+        optionalColumns: args.optionalColumns,
+        matches,
+        maxMatches: args.maxMatches ?? 25,
+        maxPayloadBytes: args.maxPayloadBytes,
+        maxEstimatedTokens: args.maxEstimatedTokens,
+        resourceTitle: "Table column lookup"
+    });
+}
+async function lookupFindEntity(args) {
+    const workbookId = args.workbookId;
+    const context = await lookupWorkbookContext(workbookId, args.sheetNames);
+    if (!context.ok) {
+        return withCompactTelemetry({ ok: false, workbookId, entity: args.entity, source: context.source }, { detailLevel: "summary" });
+    }
+    const matches = await lookupUsedRangeMatches(workbookId, context.sheets, args.entity, args, "entity");
+    return compactLookupResponse({
+        workbookId,
+        entity: args.entity,
+        entityKind: args.kind ?? "any",
+        matches,
+        maxMatches: args.maxMatches ?? 25,
+        maxPayloadBytes: args.maxPayloadBytes,
+        maxEstimatedTokens: args.maxEstimatedTokens,
+        resourceTitle: `Entity lookup: ${args.entity}`
+    });
+}
+async function lookupResolveRange(args) {
+    const workbookId = args.workbookId;
+    const kind = args.kind ?? "any";
+    const context = await lookupWorkbookContext(workbookId, args.preferredSheetName ? [args.preferredSheetName] : undefined);
+    if (!context.ok) {
+        return withCompactTelemetry({ ok: false, workbookId, target: args.target, source: context.source }, { detailLevel: "summary" });
+    }
+    const matches = [];
+    const parsedRange = lookupParseRangeTarget(args.target, args.preferredSheetName);
+    if ((kind === "any" || kind === "range") && parsedRange) {
+        matches.push(lookupMatch({
+            kind: "range",
+            sheetName: parsedRange.sheetName,
+            address: parsedRange.address,
+            score: 1,
+            reason: "explicit A1 range"
+        }));
+    }
+    if (kind === "any" || kind === "table" || kind === "column") {
+        for (const table of context.tables) {
+            if (args.preferredTableName && table.tableName !== args.preferredTableName) {
+                continue;
+            }
+            if ((kind === "any" || kind === "table") && lookupMatches(String(table.tableName), args.target, args)) {
+                matches.push(lookupMatch({
+                    kind: "table",
+                    sheetName: table.sheetName,
+                    tableName: table.tableName,
+                    address: table.address,
+                    score: lookupScore(table.tableName, args.target, false),
+                    reason: "table name",
+                    schema: tableInfoSchema(table)
+                }));
+            }
+            if (kind === "any" || kind === "column") {
+                for (const column of table.columns ?? []) {
+                    if (lookupMatches(String(column.name), args.target, args)) {
+                        matches.push(lookupMatch({
+                            kind: "column",
+                            sheetName: table.sheetName,
+                            tableName: table.tableName,
+                            columnName: column.name,
+                            address: table.address,
+                            score: lookupScore(column.name, args.target, false),
+                            reason: "table column",
+                            schema: { tableName: table.tableName, column }
+                        }));
+                    }
+                }
+            }
+        }
+    }
+    if (kind === "any" || kind === "header") {
+        const headerRequest = {
+            workbookId,
+            query: args.target,
+            maxRowsPerSheet: 10
+        };
+        if (args.preferredSheetName !== undefined) {
+            headerRequest.sheetNames = [args.preferredSheetName];
+        }
+        if (args.maxMatches !== undefined) {
+            headerRequest.maxMatches = args.maxMatches;
+        }
+        const headerResult = await lookupFindHeaders(headerRequest);
+        matches.push(...(headerResult.matches ?? []));
+    }
+    if (kind === "any" || kind === "entity") {
+        matches.push(...await lookupUsedRangeMatches(workbookId, context.sheets, args.target, args, "entity"));
+    }
+    return compactLookupResponse({
+        workbookId,
+        target: args.target,
+        targetKind: kind,
+        matches,
+        maxMatches: args.maxMatches ?? 10,
+        maxPayloadBytes: args.maxPayloadBytes,
+        maxEstimatedTokens: args.maxEstimatedTokens,
+        resourceTitle: `Range resolution: ${args.target}`
+    });
+}
+async function lookupInspectMatch(args) {
+    const decoded = args.matchId ? lookupDecodeMatchId(args.matchId) : undefined;
+    const match = { ...decoded, ...args };
+    const workbookId = args.workbookId;
+    if (match.tableName) {
+        const request = {
+            workbookId,
+            tableName: match.tableName,
+            mode: "window",
+            maxRows: args.maxRows ?? 10,
+            maxColumns: args.maxColumns ?? 25,
+            includeValues: args.includeValues ?? true,
+            includeFormulas: args.includeFormulas === true,
+            includeText: args.includeText === true
+        };
+        if (match.columnName !== undefined) {
+            request.columns = [match.columnName];
+        }
+        if (args.maxPayloadBytes !== undefined) {
+            request.maxPayloadBytes = args.maxPayloadBytes;
+        }
+        if (args.maxEstimatedTokens !== undefined) {
+            request.maxEstimatedTokens = args.maxEstimatedTokens;
+        }
+        return compactTableRead(request);
+    }
+    let sheetName = match.sheetName;
+    let address = match.address;
+    if (sheetName && !address) {
+        const context = await lookupWorkbookContext(workbookId, [sheetName]);
+        address = context.sheets[0]?.usedRange?.address;
+    }
+    if (sheetName && address) {
+        const request = {
+            workbookId,
+            sheetName,
+            address,
+            mode: "window",
+            maxRows: args.maxRows ?? 10,
+            maxColumns: args.maxColumns ?? 25,
+            includeValues: args.includeValues ?? true,
+            includeFormulas: args.includeFormulas === true,
+            includeText: args.includeText === true
+        };
+        if (args.maxPayloadBytes !== undefined) {
+            request.maxPayloadBytes = args.maxPayloadBytes;
+        }
+        if (args.maxEstimatedTokens !== undefined) {
+            request.maxEstimatedTokens = args.maxEstimatedTokens;
+        }
+        return compactRangeRead(request);
+    }
+    return withCompactTelemetry({
+        ok: false,
+        workbookId,
+        error: {
+            code: "LOOKUP_MATCH_TARGET_REQUIRED",
+            message: "Provide matchId from a lookup response or direct sheetName/address/tableName fields."
+        }
+    }, { detailLevel: "summary" });
+}
+async function compactValidation(args) {
+    const workbookId = args.workbookId;
+    const report = await runCompactValidator(args, workbookId);
+    const issues = Array.isArray(report.issues) ? report.issues : [];
+    const maxIssues = args.maxIssues ?? 5;
+    const summary = {
+        ok: report.ok,
+        workbookId,
+        validator: args.validator,
+        scope: report.scope,
+        issueCount: report.issueCount ?? issues.length,
+        severityCounts: compactSeverityCounts(issues),
+        categories: compactIssueCategories(issues),
+        examples: issues.slice(0, maxIssues).map(compactIssueExample),
+        examplesTruncated: issues.length > maxIssues
+    };
+    return withCompactTelemetry(summary, {
+        detailLevel: "summary",
+        truncated: issues.length > maxIssues,
+        storeResource: true,
+        resourceKind: "validation",
+        resourceTitle: `Validation detail: ${args.validator}`,
+        resourcePayload: report,
+        maxPayloadBytes: args.maxPayloadBytes,
+        maxEstimatedTokens: args.maxEstimatedTokens,
+        budgetSummary: summary
+    });
+}
+function compactSnapshot(snapshotId, maxPayloadBytes, maxEstimatedTokens) {
+    const result = runtime.getSnapshot(snapshotId);
+    const snapshot = result.snapshot;
+    const summary = snapshot
+        ? {
+            ok: true,
+            snapshotId,
+            workbookId: snapshot.workbookId,
+            createdAt: snapshot.createdAt,
+            reason: snapshot.reason,
+            affectedRangeCount: snapshot.affectedRanges?.length ?? 0,
+            affectedRanges: snapshot.affectedRanges,
+            payloadRangeCount: snapshot.payload?.rangeSnapshots?.length ?? 0
+        }
+        : { ok: false, snapshotId, error: result.error };
+    return withCompactTelemetry(summary, {
+        detailLevel: "summary",
+        truncated: false,
+        storeResource: Boolean(snapshot),
+        resourceKind: "snapshot",
+        resourceTitle: `Snapshot detail: ${snapshotId}`,
+        resourcePayload: result,
+        maxPayloadBytes,
+        maxEstimatedTokens,
+        budgetSummary: summary
+    });
+}
+function compactSnapshotCreationResult(result) {
+    if (toolProfile === "full") {
+        return result;
+    }
+    const snapshot = result?.snapshot;
+    if (!snapshot) {
+        return result;
+    }
+    const summary = snapshotSummary(snapshot);
+    const stored = storeCompactResource("snapshot", result, `Snapshot detail: ${summary.snapshotId}`);
+    return withCompactTelemetry({
+        ok: result.ok,
+        snapshot: summary
+    }, {
+        detailLevel: "summary",
+        resourceUri: stored.uri,
+        resourceKind: "snapshot",
+        resourceTitle: `Snapshot detail: ${summary.snapshotId}`
+    });
+}
+function snapshotSummary(snapshot) {
+    return {
+        snapshotId: snapshot.snapshotId,
+        workbookId: snapshot.workbookId,
+        createdAt: snapshot.createdAt,
+        reason: snapshot.reason,
+        affectedRangeCount: snapshot.affectedRanges?.length ?? 0,
+        affectedRanges: snapshot.affectedRanges,
+        payloadRangeCount: snapshot.payload?.rangeSnapshots?.length ?? snapshot.rangeSnapshots?.length ?? 0
+    };
+}
+function compactSnapshotDiff(leftSnapshotId, rightSnapshotId, maxPayloadBytes, maxEstimatedTokens) {
+    const result = runtime.compareSnapshots(leftSnapshotId, rightSnapshotId);
+    const diff = result.diff;
+    const summary = diff
+        ? {
+            ok: true,
+            leftSnapshotId,
+            rightSnapshotId,
+            title: diff.summary?.title,
+            changedRangeCount: diff.summary?.changedRanges?.length ?? diff.changedRanges?.length ?? 0,
+            cellsChanged: diff.summary?.cellsChanged ?? diff.cellsChanged,
+            formulasChanged: diff.summary?.formulasChanged ?? diff.formulasChanged,
+            stylesChanged: diff.summary?.stylesChanged ?? diff.stylesChanged,
+            tablesChanged: diff.summary?.tablesChanged ?? diff.tablesChanged,
+            sheetsChanged: diff.summary?.sheetsChanged ?? diff.sheetsChanged,
+            destructiveLevel: diff.summary?.destructiveLevel ?? diff.destructiveLevel,
+            changedRanges: (diff.summary?.changedRanges ?? diff.changedRanges ?? []).slice(0, 20),
+            changedRangesTruncated: (diff.summary?.changedRanges ?? diff.changedRanges ?? []).length > 20
+        }
+        : { ok: false, leftSnapshotId, rightSnapshotId, error: result.error };
+    return withCompactTelemetry(summary, {
+        detailLevel: "summary",
+        truncated: Boolean(summary.changedRangesTruncated),
+        storeResource: Boolean(diff),
+        resourceKind: "diff",
+        resourceTitle: `Snapshot diff: ${leftSnapshotId}..${rightSnapshotId}`,
+        resourcePayload: result,
+        maxPayloadBytes,
+        maxEstimatedTokens,
+        budgetSummary: summary
+    });
+}
+async function runCompactValidator(args, workbookId) {
+    switch (args.validator) {
+        case "workbook":
+            return runtime.validateWorkbook({ workbookId });
+        case "sheet":
+            return runtime.validateSheet({ workbookId, sheetName: requiredCompactArg(args.sheetName, "sheetName") });
+        case "formulas":
+            return runtime.validateFormulas({ workbookId, ...compactOptional({ sheetName: args.sheetName, address: args.address }) });
+        case "styles":
+            return runtime.validateStyles(compactStylesValidationRequest(workbookId, args));
+        case "tables":
+            return runtime.validateTables(compactTablesValidationRequest(workbookId, args));
+        case "filters":
+            return runtime.validateFilters({ workbookId, ...compactOptional({ tableName: args.tableName }) });
+        case "print_layout":
+            return runtime.validatePrintLayout(compactPrintLayoutValidationRequest(workbookId, args));
+        case "no_broken_references":
+            return runtime.validateNoBrokenReferences({ workbookId, ...compactOptional({ sheetName: args.sheetName, address: args.address }) });
+        case "no_formula_errors":
+            return runtime.validateNoFormulaErrors({ workbookId, ...compactOptional({ sheetName: args.sheetName, address: args.address }) });
+        case "no_unintended_changes":
+            return runtime.validateNoUnintendedChanges(compactUnintendedChangesValidationRequest(workbookId, args));
+        default:
+            return {
+                ok: false,
+                workbookId,
+                scope: args.validator,
+                issueCount: 1,
+                issues: [
+                    {
+                        code: "VALIDATOR_UNSUPPORTED",
+                        severity: "error",
+                        category: "validation",
+                        message: `Unsupported compact validator: ${args.validator}`
+                    }
+                ]
+            };
+    }
+}
+function compactSeverityCounts(issues) {
+    const counts = {};
+    for (const issue of issues) {
+        const severity = typeof issue === "object" && issue !== null && "severity" in issue ? String(issue.severity) : "unknown";
+        counts[severity] = (counts[severity] ?? 0) + 1;
+    }
+    return counts;
+}
+function compactStylesValidationRequest(workbookId, args) {
+    const request = { workbookId };
+    if (args.sheetName !== undefined) {
+        request.sheetName = args.sheetName;
+    }
+    if (args.templateId !== undefined) {
+        request.templateId = args.templateId;
+    }
+    if (args.targetSheetName !== undefined) {
+        request.targetSheetName = args.targetSheetName;
+    }
+    return request;
+}
+function compactTablesValidationRequest(workbookId, args) {
+    const request = { workbookId };
+    if (args.tableName !== undefined) {
+        request.tableName = args.tableName;
+    }
+    if (args.templateId !== undefined) {
+        request.templateId = args.templateId;
+    }
+    return request;
+}
+function compactPrintLayoutValidationRequest(workbookId, args) {
+    const request = { workbookId };
+    if (args.templateId !== undefined) {
+        request.templateId = args.templateId;
+    }
+    if (args.targetSheetName !== undefined) {
+        request.targetSheetName = args.targetSheetName;
+    }
+    return request;
+}
+function compactUnintendedChangesValidationRequest(workbookId, args) {
+    const request = { workbookId };
+    if (args.snapshotId !== undefined) {
+        request.snapshotId = args.snapshotId;
+    }
+    if (args.leftSnapshotId !== undefined) {
+        request.leftSnapshotId = args.leftSnapshotId;
+    }
+    if (args.rightSnapshotId !== undefined) {
+        request.rightSnapshotId = args.rightSnapshotId;
+    }
+    return request;
+}
+function compactIssueCategories(issues) {
+    return [...new Set(issues.map((issue) => typeof issue === "object" && issue !== null && "category" in issue ? String(issue.category) : "unknown"))];
+}
+function compactIssueExample(issue) {
+    if (typeof issue !== "object" || issue === null) {
+        return issue;
+    }
+    const typed = issue;
+    return {
+        code: typed.code,
+        severity: typed.severity,
+        category: typed.category,
+        message: typed.message,
+        target: typed.target
+    };
+}
+function requiredCompactArg(value, name) {
+    if (value === undefined || value === "") {
+        throw new Error(`${name} is required for this compact validator.`);
+    }
+    return value;
+}
+function usedRangeCellCount(usedRange) {
+    return (usedRange?.rowCount ?? 0) * (usedRange?.columnCount ?? 0);
+}
+function tableInfoSchema(info) {
+    return {
+        workbookId: info.workbookId,
+        tableName: info.tableName,
+        sheetName: info.sheetName,
+        address: info.address,
+        headerAddress: info.headerAddress,
+        rowCount: info.rowCount,
+        columnCount: info.columnCount,
+        columns: info.columns ?? [],
+        style: info.style,
+        showHeaders: info.showHeaders,
+        showTotals: info.showTotals,
+        showFilterButton: info.showFilterButton,
+        showBandedRows: info.showBandedRows,
+        showBandedColumns: info.showBandedColumns,
+        hasFilters: info.filters !== undefined,
+        hasSort: info.sort !== undefined
+    };
+}
+async function lookupWorkbookContext(workbookId, sheetNames) {
+    const result = await runtime.getWorkbookMap();
+    const map = "map" in result ? result.map : undefined;
+    if (!result.ok || !map) {
+        return { ok: false, workbookId, source: result, sheets: [], tables: [] };
+    }
+    const requestedSheets = new Set((sheetNames ?? []).map(lookupNormalized));
+    const sheets = (map.sheets ?? []).filter((sheet) => requestedSheets.size === 0 || requestedSheets.has(lookupNormalized(sheet.name)));
+    const tableRefs = sheets.flatMap((sheet) => (sheet.tables ?? []).map((table) => ({
+        sheetName: sheet.name,
+        tableName: table.name ?? table.tableName
+    }))).filter((table) => table.tableName);
+    const tables = await Promise.all(tableRefs.map(async (table) => {
+        try {
+            const infoResult = await runtime.getTableInfo({ workbookId, tableName: table.tableName });
+            const info = infoResult.info;
+            return info ? { ...info, sheetName: info.sheetName ?? table.sheetName } : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }));
+    return {
+        ok: true,
+        workbookId,
+        workbook: map.workbook,
+        sheets,
+        tables: tables.filter((table) => table !== undefined)
+    };
+}
+function lookupTableMatches(tables, query, options) {
+    const matches = [];
+    for (const table of tables) {
+        const schema = tableInfoSchema(table);
+        if (lookupMatches(String(table.tableName), query, options)) {
+            matches.push(lookupMatch({
+                kind: "table",
+                sheetName: table.sheetName,
+                tableName: table.tableName,
+                address: table.address,
+                score: lookupScore(table.tableName, query, options.completeMatch),
+                reason: "table name",
+                schema
+            }));
+        }
+        for (const column of table.columns ?? []) {
+            if (lookupMatches(String(column.name), query, options)) {
+                matches.push(lookupMatch({
+                    kind: "column",
+                    sheetName: table.sheetName,
+                    tableName: table.tableName,
+                    columnName: column.name,
+                    address: table.address,
+                    score: lookupScore(column.name, query, options.completeMatch),
+                    reason: "table column",
+                    schema: { tableName: table.tableName, column }
+                }));
+            }
+        }
+    }
+    return matches;
+}
+async function lookupUsedRangeMatches(workbookId, sheets, query, options, kind) {
+    const matches = [];
+    const lookupOptions = options;
+    for (const sheet of sheets) {
+        const address = sheet.usedRange?.address;
+        if (!address) {
+            continue;
+        }
+        try {
+            const result = await runtime.readRangeMetadata("range.search", {
+                workbookId,
+                sheetName: sheet.name,
+                address,
+                text: query,
+                completeMatch: lookupOptions.completeMatch,
+                matchCase: lookupOptions.matchCase
+            });
+            const found = result.matches;
+            if (!found?.address || found.isNullObject) {
+                continue;
+            }
+            const match = lookupMatch({
+                kind,
+                sheetName: sheet.name,
+                address: found.address,
+                score: lookupOptions.completeMatch ? 0.92 : 0.82,
+                reason: `${kind === "entity" ? "entity" : "range"} text match`,
+                preview: {
+                    areaCount: found.areaCount,
+                    cellCount: found.cellCount
+                }
+            });
+            if ((lookupOptions.maxPreviewRows ?? 0) > 0) {
+                match.preview = await lookupPreviewRange(workbookId, sheet.name, found.address, lookupOptions.maxPreviewRows ?? 3);
+            }
+            matches.push(match);
+        }
+        catch {
+            // Ignore sheet-local search failures; other sheets and metadata can still guide the model.
+        }
+    }
+    return matches;
+}
+async function lookupPreviewRange(workbookId, sheetName, address, maxRows) {
+    try {
+        const result = await compactRangeRead({
+            workbookId,
+            sheetName,
+            address,
+            mode: "window",
+            maxRows,
+            maxColumns: 10,
+            includeValues: true,
+            includeText: true
+        });
+        return {
+            address: result.window?.address ?? address,
+            values: result.values,
+            text: result.text
+        };
+    }
+    catch {
+        return { address };
+    }
+}
+function compactLookupResponse(args) {
+    const allMatches = lookupSortAndDedupe(args.matches);
+    const shownMatches = allMatches.slice(0, args.maxMatches);
+    const summary = {
+        ok: true,
+        workbookId: args.workbookId,
+        ...Object.fromEntries(Object.entries(args).filter(([key]) => !["workbookId", "matches", "maxMatches", "maxPayloadBytes", "maxEstimatedTokens", "resourceTitle"].includes(key))),
+        matchCount: allMatches.length,
+        matches: shownMatches,
+        matchesTruncated: shownMatches.length < allMatches.length
+    };
+    return withCompactTelemetry(summary, {
+        detailLevel: "summary",
+        truncated: shownMatches.length < allMatches.length,
+        maxPayloadBytes: args.maxPayloadBytes,
+        maxEstimatedTokens: args.maxEstimatedTokens,
+        resourceKind: "summary",
+        resourceTitle: args.resourceTitle,
+        resourcePayload: { ...summary, matches: allMatches, matchesTruncated: false },
+        budgetSummary: { ...summary, matches: shownMatches.map(({ preview, schema, ...match }) => match) }
+    });
+}
+function lookupMatch(match) {
+    return {
+        ...match,
+        score: Number(match.score.toFixed(3)),
+        matchId: lookupEncodeMatchId(match)
+    };
+}
+function lookupSortAndDedupe(matches) {
+    const best = new Map();
+    for (const match of matches) {
+        const key = [match.kind, match.sheetName, match.tableName, match.columnName, match.address].map((value) => value ?? "").join("|");
+        const existing = best.get(key);
+        if (!existing || match.score > existing.score) {
+            best.set(key, match);
+        }
+    }
+    return [...best.values()].sort((left, right) => right.score - left.score ||
+        String(left.sheetName ?? "").localeCompare(String(right.sheetName ?? "")) ||
+        String(left.tableName ?? "").localeCompare(String(right.tableName ?? "")) ||
+        String(left.address ?? "").localeCompare(String(right.address ?? "")));
+}
+function lookupTerms(values) {
+    return values.map(lookupNormalized).filter((value) => value !== "");
+}
+function lookupMatches(candidate, query, options) {
+    const lookupOptions = options;
+    const left = lookupOptions.matchCase ? candidate.trim() : lookupNormalized(candidate);
+    const right = lookupOptions.matchCase ? query.trim() : lookupNormalized(query);
+    return lookupOptions.completeMatch ? left === right : left.includes(right);
+}
+function lookupScore(candidate, query, completeMatch) {
+    const left = lookupNormalized(candidate);
+    const right = lookupNormalized(query);
+    if (left === right) {
+        return 1;
+    }
+    if (completeMatch) {
+        return 0;
+    }
+    if (left.startsWith(right)) {
+        return 0.9;
+    }
+    return left.includes(right) ? 0.75 : 0;
+}
+function lookupNormalized(value) {
+    return String(value ?? "").trim().toLowerCase();
+}
+function lookupRowsFromCompactRead(result) {
+    const typed = result;
+    return Array.isArray(typed.text) ? typed.text : Array.isArray(typed.values) ? typed.values : [];
+}
+function lookupParseRangeTarget(target, preferredSheetName) {
+    const parts = target.split("!");
+    const sheetName = parts.length > 1 ? parts.slice(0, -1).join("!").replace(/^'|'$/g, "") : preferredSheetName;
+    const address = parts.length > 1 ? parts[parts.length - 1] : target;
+    if (address === undefined) {
+        return undefined;
+    }
+    try {
+        parseCompactA1Address(address);
+        return sheetName ? { sheetName, address } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function lookupEncodeMatchId(match) {
+    const payload = JSON.stringify({
+        kind: match.kind,
+        sheetName: match.sheetName,
+        tableName: match.tableName,
+        columnName: match.columnName,
+        address: match.address
+    });
+    return `lookup:${Buffer.from(payload, "utf8").toString("base64url")}`;
+}
+function lookupDecodeMatchId(matchId) {
+    if (!matchId.startsWith("lookup:")) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(Buffer.from(matchId.slice("lookup:".length), "base64url").toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function compactTableColumns(info, requested, maxColumns) {
+    const columns = info.columns ?? [];
+    if (requested?.length) {
+        return columns.filter((column) => requested.some((item) => item === column.name || item === column.index || item === column.id));
+    }
+    return columns.slice(0, maxColumns ?? 25);
+}
+function compactRangeFacets(args) {
+    const facets = [];
+    if (args.includeValues !== false) {
+        facets.push("values");
+    }
+    if (args.includeFormulas === true) {
+        facets.push("formulas");
+    }
+    if (args.includeText === true) {
+        facets.push("text");
+    }
+    if (args.includeNumberFormats === true) {
+        facets.push("numberFormat");
+    }
+    if (args.includeStyles === true) {
+        facets.push("style");
+    }
+    return facets;
+}
+function compactSampleWindows(totalRows, requestedRows) {
+    const sampleRows = Math.max(1, Math.min(totalRows, requestedRows));
+    if (totalRows <= sampleRows) {
+        return [{ label: "head", rowOffset: 0, rowCount: totalRows }];
+    }
+    const headRows = Math.max(1, Math.floor(sampleRows / 3));
+    const middleRows = Math.max(1, Math.floor(sampleRows / 3));
+    const tailRows = Math.max(1, sampleRows - headRows - middleRows);
+    const middleOffset = Math.max(headRows, Math.floor((totalRows - middleRows) / 2));
+    const tailOffset = Math.max(middleOffset + middleRows, totalRows - tailRows);
+    const windows = [
+        { label: "head", rowOffset: 0, rowCount: headRows },
+        { label: "middle", rowOffset: middleOffset, rowCount: Math.min(middleRows, totalRows - middleOffset) },
+        { label: "tail", rowOffset: tailOffset, rowCount: Math.min(tailRows, totalRows - tailOffset) }
+    ];
+    return windows.filter((window, index, all) => window.rowCount > 0 &&
+        all.findIndex((candidate) => rangesOverlap(candidate.rowOffset, candidate.rowCount, window.rowOffset, window.rowCount)) === index);
+}
+function rangesOverlap(leftOffset, leftCount, rightOffset, rightCount) {
+    const leftEnd = leftOffset + leftCount;
+    const rightEnd = rightOffset + rightCount;
+    return leftOffset < rightEnd && rightOffset < leftEnd;
+}
+function compactWindowAddress(address, rowOffset, columnOffset, rowCount, columnCount) {
+    const parsed = parseCompactA1Address(address);
+    const startRow = parsed.startRow + rowOffset;
+    const startColumn = parsed.startColumn + columnOffset;
+    const endRow = startRow + Math.max(rowCount, 1) - 1;
+    const endColumn = startColumn + Math.max(columnCount, 1) - 1;
+    const start = `${compactColumnName(startColumn)}${startRow}`;
+    const end = `${compactColumnName(endColumn)}${endRow}`;
+    return start === end ? start : `${start}:${end}`;
+}
+function parseCompactA1Address(address) {
+    const range = stripResourceSheetName(address).trim();
+    const match = /^(?<startCol>[A-Z]+)(?<startRow>\d+)(?::(?<endCol>[A-Z]+)(?<endRow>\d+))?$/i.exec(range);
+    if (!match?.groups?.startCol || !match.groups.startRow) {
+        throw new Error(`Invalid A1 address: ${address}`);
+    }
+    const startColumn = compactColumnNumber(match.groups.startCol);
+    const startRow = Number(match.groups.startRow);
+    const endColumn = compactColumnNumber(match.groups.endCol ?? match.groups.startCol);
+    const endRow = Number(match.groups.endRow ?? match.groups.startRow);
+    if (startRow < 1 || endRow < startRow || endColumn < startColumn) {
+        throw new Error(`Invalid A1 range bounds: ${address}`);
+    }
+    return { startRow, startColumn, endRow, endColumn };
+}
+function compactColumnNumber(columnName) {
+    let value = 0;
+    for (const char of columnName.toUpperCase()) {
+        const code = char.charCodeAt(0);
+        if (code < 65 || code > 90) {
+            throw new Error(`Invalid column name: ${columnName}`);
+        }
+        value = value * 26 + (code - 64);
+    }
+    return value;
+}
+function compactColumnName(columnNumber) {
+    let value = "";
+    let n = columnNumber;
+    while (n > 0) {
+        n -= 1;
+        value = String.fromCharCode(65 + (n % 26)) + value;
+        n = Math.floor(n / 26);
+    }
+    return value;
+}
+function tableCreateRequest(args) {
+    const request = {
+        workbookId: args.workbookId,
+        sheetName: args.sheetName,
+        address: args.address,
+        hasHeaders: args.hasHeaders
+    };
+    if (args.tableName !== undefined) {
+        request.tableName = args.tableName;
+    }
+    if (args.values !== undefined) {
+        request.values = args.values;
+    }
+    if (args.style !== undefined) {
+        request.style = args.style;
+    }
+    if (args.showTotals !== undefined) {
+        request.showTotals = args.showTotals;
+    }
+    return request;
+}
+function tableFilterSchema() {
+    return {
+        ...tableSelectorSchema(),
+        filters: z.array(z.object({
+            column: z.union([z.string(), z.number().int().min(0)]),
+            criteria: z.record(z.string(), z.any())
+        }))
+    };
+}
+function tableSortSchema() {
+    return {
+        ...tableSelectorSchema(),
+        fields: z.array(z.object({
+            key: z.number().int().min(0),
+            ascending: z.boolean().optional(),
+            sortOn: z.enum(["Value", "CellColor", "FontColor", "Icon"]).optional(),
+            color: z.string().optional(),
+            dataOption: z.enum(["Normal", "TextAsNumber"]).optional()
+        })),
+        matchCase: z.boolean().optional(),
+        method: z.enum(["PinYin", "StrokeCount"]).optional()
+    };
+}
+function nameSelectorSchema() {
+    return {
+        workbookId: z.string(),
+        name: z.string(),
+        sheetName: z.string().optional()
+    };
+}
+function nameMutationSchema() {
+    return {
+        ...nameSelectorSchema(),
+        reference: z.string().optional(),
+        formula: z.string().optional(),
+        comment: z.string().optional(),
+        visible: z.boolean().optional()
+    };
+}
+function nameSelector(args) {
+    const request = {
+        workbookId: args.workbookId,
+        name: args.name
+    };
+    if (args.sheetName !== undefined) {
+        request.sheetName = args.sheetName;
+    }
+    return request;
+}
+function nameCreateRequest(args) {
+    const request = nameSelector(args);
+    if (args.reference !== undefined) {
+        request.reference = args.reference;
+    }
+    if (args.formula !== undefined) {
+        request.formula = args.formula;
+    }
+    if (args.comment !== undefined) {
+        request.comment = args.comment;
+    }
+    if (args.visible !== undefined) {
+        request.visible = args.visible;
+    }
+    return request;
+}
+function nameUpdateRequest(args) {
+    return nameCreateRequest(args);
+}
+function regionSelectorSchema() {
+    return {
+        workbookId: z.string(),
+        regionName: z.string()
+    };
+}
+function regionSelector(args) {
+    return {
+        workbookId: args.workbookId,
+        regionName: args.regionName
+    };
+}
+function pivotSelectorSchema() {
+    return {
+        workbookId: z.string(),
+        pivotTableName: z.string()
+    };
+}
+function pivotSelector(args) {
+    return {
+        workbookId: args.workbookId,
+        pivotTableName: args.pivotTableName
+    };
+}
+function pivotValidateSourceRequest(args) {
+    return {
+        ...pivotSelector(args),
+        ...(args.expectedFields !== undefined ? { expectedFields: args.expectedFields } : {}),
+        ...(args.expectedRowFields !== undefined ? { expectedRowFields: args.expectedRowFields } : {}),
+        ...(args.expectedColumnFields !== undefined ? { expectedColumnFields: args.expectedColumnFields } : {}),
+        ...(args.expectedFilterFields !== undefined ? { expectedFilterFields: args.expectedFilterFields } : {}),
+        ...(args.expectedDataFields !== undefined ? { expectedDataFields: args.expectedDataFields } : {}),
+        ...(args.expectedDataFieldSettings !== undefined ? { expectedDataFieldSettings: args.expectedDataFieldSettings } : {}),
+        ...(args.expectedLayout !== undefined ? { expectedLayout: args.expectedLayout } : {})
+    };
+}
+function pivotCreateRequest(args) {
+    const request = {
+        workbookId: args.workbookId,
+        pivotTableName: args.pivotTableName,
+        destinationSheetName: args.destinationSheetName,
+        destinationAddress: args.destinationAddress
     };
     if (args.sourceSheetName !== undefined) {
         request.sourceSheetName = args.sourceSheetName;
@@ -4639,10 +6599,83 @@ function escapeHtml(value) {
     return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 function registerMcpTool(mcp, name, config, callback) {
-    if (!isToolExposed(name, catalogOptions)) {
+    if (!shouldExposeMcpTool(name)) {
         return;
     }
-    mcp.registerTool(name, config, callback);
+    mcp.registerTool(name, config, async (args, extra) => {
+        const result = await callback(args, extra);
+        const decorated = isWorkbookMutatingMcpTool(name) ? addCompactMutationProof(result) : result;
+        if (isWorkbookMutatingMcpTool(name)) {
+            clearCompactCache(`mutation:${name}`);
+        }
+        return enforceCompactResultBudget(name, decorated);
+    });
+}
+function enforceCompactResultBudget(toolName, result) {
+    if (toolProfile === "full" || !isJsonTextResult(result)) {
+        return result;
+    }
+    if (toolName === "excel.compact.get_resource") {
+        return result;
+    }
+    const payloadBytes = Buffer.byteLength(result.content[0].text, "utf8");
+    if (payloadBytes <= COMPACT_DEFAULT_RESOURCE_THRESHOLD_BYTES) {
+        return result;
+    }
+    try {
+        const payload = JSON.parse(result.content[0].text);
+        if (payload.resourceUri !== undefined && payload.budgetExceeded === true) {
+            return result;
+        }
+        const stored = storeCompactResource(compactResourceKindForTool(toolName), payload, `Full result: ${toolName}`);
+        const summary = compactResultSummary(toolName, payload, payloadBytes, stored);
+        return jsonResult(summary);
+    }
+    catch {
+        const stored = storeCompactResource("generic", result.content[0].text, `Full text result: ${toolName}`);
+        return jsonResult({
+            ok: true,
+            toolName,
+            detailLevel: "summary",
+            budgetExceeded: true,
+            payloadBytes,
+            estimatedTokens: Math.ceil(payloadBytes / 4),
+            resourcePayloadBytes: stored.payloadBytes,
+            resourceEstimatedTokens: stored.estimatedTokens,
+            resourceUri: stored.uri,
+            warnings: [
+                {
+                    code: "COMPACT_RESULT_BUDGET_EXCEEDED",
+                    message: "Tool result exceeded compact response budget and was stored behind resourceUri."
+                }
+            ]
+        });
+    }
+}
+function shouldExposeMcpTool(name) {
+    if (!isToolExposed(name, catalogOptions)) {
+        return false;
+    }
+    if (explicitToolNames !== undefined && !explicitToolNames.has(name)) {
+        return false;
+    }
+    if (disabledToolNames?.has(name)) {
+        return false;
+    }
+    if (explicitToolNames !== undefined) {
+        return true;
+    }
+    if (toolProfile === "full") {
+        return true;
+    }
+    if (toolProfile === "compact") {
+        return COMPACT_PROFILE_TOOLS.has(name);
+    }
+    if (toolProfile === "read-only" || toolProfile === "readonly") {
+        return READ_ONLY_PROFILE_TOOLS.has(name);
+    }
+    console.error(`Unknown OPEN_WORKBOOK_TOOL_PROFILE=${toolProfile}; falling back to full MCP tool surface.`);
+    return true;
 }
 function jsonResult(value) {
     return {
@@ -4654,6 +6687,287 @@ function jsonResult(value) {
         ]
     };
 }
+function isWorkbookMutatingMcpTool(name) {
+    const namespace = name.split(".")[1];
+    if (!namespace || name.startsWith("excel.compact.")) {
+        return false;
+    }
+    if (namespace === "workbook") {
+        return /\.(calculate|save|save_as|restore_backup|close|embed|import)/.test(name);
+    }
+    if (namespace === "plan") {
+        return /\.(apply|rollback)/.test(name);
+    }
+    if (namespace === "transaction") {
+        return /\.(rollback|rollback_chain)/.test(name);
+    }
+    if (!new Set(["sheet", "range", "batch", "workflow", "template", "style", "formula", "table", "filter", "sort", "pivot", "chart", "names", "region", "repair", "clean"]).has(namespace)) {
+        return false;
+    }
+    if (name === "excel.workflow.preview_risky_edit") {
+        return true;
+    }
+    return /\.(set_|write_|create|copy|rename|delete|move|hide|unhide|protect|unprotect|clear|apply|repair|fill|append|update|resize|sort|save|restore|close|insert|merge|unmerge|lock|unlock|convert|calculate|recalculate|register|unregister|commit|rollback|cancel|refresh|invalidate|parse|normalize|trim|remove|standardize|split|import|embed)/.test(name);
+}
+function addCompactMutationProof(result) {
+    if (!isJsonTextResult(result)) {
+        return result;
+    }
+    try {
+        const payload = JSON.parse(result.content[0].text);
+        if (payload.compactProof !== undefined) {
+            return result;
+        }
+        const compactProof = summarizeMutationProof(payload);
+        if (toolProfile === "full") {
+            return jsonResult({
+                ...payload,
+                compactProof
+            });
+        }
+        const stored = storeCompactResource("mutation", payload, "Full mutation result");
+        return jsonResult({
+            ...compactMutationPayload(payload),
+            compactProof,
+            resourceUri: stored.uri
+        });
+    }
+    catch {
+        return result;
+    }
+}
+function isJsonTextResult(result) {
+    return Boolean(result &&
+        typeof result === "object" &&
+        Array.isArray(result.content) &&
+        result.content[0]?.text !== undefined);
+}
+function summarizeMutationProof(payload) {
+    const diffSummary = payload.diffSummary;
+    const telemetry = payload.telemetry;
+    const warnings = Array.isArray(payload.warnings) ? payload.warnings : [];
+    const validation = validationSummary(payload);
+    return {
+        ok: payload.ok,
+        transactionId: payload.transactionId,
+        transactionStatus: payload.transactionStatus,
+        taskId: payload.taskId,
+        rollbackAvailable: payload.rollbackAvailable,
+        backups: payload.backups,
+        changedRanges: diffSummary?.changedRanges,
+        cellsChanged: diffSummary?.cellsChanged ?? telemetry?.cellsWritten,
+        formulasChanged: diffSummary?.formulasChanged,
+        stylesChanged: diffSummary?.stylesChanged,
+        tablesChanged: diffSummary?.tablesChanged,
+        sheetsChanged: diffSummary?.sheetsChanged,
+        warnings: warnings.length,
+        validation,
+        payloadBytes: Buffer.byteLength(JSON.stringify(payload), "utf8"),
+        estimatedTokens: Math.ceil(Buffer.byteLength(JSON.stringify(payload), "utf8") / 4)
+    };
+}
+function compactMutationPayload(payload) {
+    const output = {};
+    for (const [key, value] of Object.entries(payload)) {
+        if (key === "beforeSnapshot" || key === "afterSnapshot") {
+            output[key] = value && typeof value === "object" ? snapshotSummary(value) : value;
+            continue;
+        }
+        if (key === "backup") {
+            output[key] = summarizeBackup(value);
+            continue;
+        }
+        if (key === "diff") {
+            output[key] = summarizeDiffResult(value);
+            continue;
+        }
+        if (key === "planPreview") {
+            output[key] = summarizePlanPreview(value);
+            continue;
+        }
+        if (key === "applyResult") {
+            output[key] = summarizeOperationResult(value);
+            continue;
+        }
+        if (key === "beforeSnapshotResult") {
+            output[key] = summarizeOperationResult(value);
+            continue;
+        }
+        output[key] = value;
+    }
+    return output;
+}
+function summarizeBackup(value) {
+    if (!value || typeof value !== "object") {
+        return value;
+    }
+    const record = value;
+    return {
+        backupId: record.backupId,
+        workbookId: record.workbookId,
+        kind: record.kind,
+        reason: record.reason,
+        createdAt: record.createdAt,
+        affectedRangeCount: record.affectedRanges?.length ?? 0,
+        affectedRanges: record.affectedRanges,
+        payloadRef: record.payloadRef
+    };
+}
+function summarizeDiffResult(value) {
+    if (!value || typeof value !== "object") {
+        return value;
+    }
+    const record = value;
+    const diff = record.diff ?? record;
+    return {
+        ok: record.ok,
+        diffId: record.diffId,
+        summary: diff.summary ?? {
+            title: diff.title,
+            changedRanges: Array.isArray(diff.changedRanges) ? diff.changedRanges.slice(0, 20) : undefined,
+            changedRangesTruncated: Array.isArray(diff.changedRanges) && diff.changedRanges.length > 20,
+            cellsChanged: diff.cellsChanged,
+            formulasChanged: diff.formulasChanged,
+            stylesChanged: diff.stylesChanged,
+            tablesChanged: diff.tablesChanged,
+            sheetsChanged: diff.sheetsChanged,
+            destructiveLevel: diff.destructiveLevel
+        }
+    };
+}
+function summarizePlanPreview(value) {
+    if (!value || typeof value !== "object") {
+        return value;
+    }
+    const record = value;
+    return {
+        ok: record.ok,
+        planId: record.planId,
+        operationCount: record.operationCount ?? record.operations?.length,
+        requiredBackupCount: record.requiredBackups?.length ?? 0,
+        requiredBackups: record.requiredBackups,
+        diffSummary: record.diffSummary ?? summarizeDiffResult(record.diff),
+        confirmationRequired: record.confirmationRequired,
+        confirmationToken: record.confirmationToken,
+        warnings: Array.isArray(record.warnings) ? record.warnings.length : record.warnings
+    };
+}
+function summarizeOperationResult(value) {
+    if (!value || typeof value !== "object") {
+        return value;
+    }
+    const record = value;
+    return {
+        ok: record.ok,
+        transactionId: record.transactionId,
+        transactionStatus: record.transactionStatus,
+        rollbackAvailable: record.rollbackAvailable,
+        backups: record.backups,
+        backup: summarizeBackup(record.backup),
+        warnings: Array.isArray(record.warnings) ? record.warnings.length : record.warnings,
+        telemetry: record.telemetry,
+        error: record.error
+    };
+}
+function compactResourceKindForTool(toolName) {
+    if (toolName.includes(".snapshot.")) {
+        return "snapshot";
+    }
+    if (toolName.includes(".diff.")) {
+        return "diff";
+    }
+    if (toolName.includes(".validate.")) {
+        return "validation";
+    }
+    if (isWorkbookMutatingMcpTool(toolName)) {
+        return "mutation";
+    }
+    if (toolName.includes(".read") || toolName.includes(".lookup.") || toolName.includes(".summary") || toolName.includes(".schema")) {
+        return "read";
+    }
+    return "generic";
+}
+function compactResultSummary(toolName, payload, payloadBytes, stored) {
+    return {
+        ok: payload.ok ?? true,
+        toolName,
+        detailLevel: "summary",
+        budgetExceeded: true,
+        payloadBytes: Math.min(payloadBytes, COMPACT_DEFAULT_RESOURCE_THRESHOLD_BYTES),
+        estimatedTokens: Math.ceil(Math.min(payloadBytes, COMPACT_DEFAULT_RESOURCE_THRESHOLD_BYTES) / 4),
+        resourcePayloadBytes: stored.payloadBytes,
+        resourceEstimatedTokens: stored.estimatedTokens,
+        resourceUri: stored.uri,
+        summary: summarizePayloadForBudget(payload),
+        warnings: [
+            ...asWarningArray(payload.warnings),
+            {
+                code: "COMPACT_RESULT_BUDGET_EXCEEDED",
+                message: "Tool result exceeded compact response budget and was stored behind resourceUri."
+            }
+        ]
+    };
+}
+function summarizePayloadForBudget(payload) {
+    return {
+        transactionId: payload.transactionId,
+        transactionStatus: payload.transactionStatus,
+        taskId: payload.taskId,
+        rollbackAvailable: payload.rollbackAvailable,
+        backups: payload.backups,
+        backup: summarizeBackup(payload.backup),
+        snapshot: payload.snapshot && typeof payload.snapshot === "object" ? snapshotSummary(payload.snapshot) : undefined,
+        diffSummary: payload.diffSummary ?? summarizeDiffResult(payload.diff),
+        compactProof: payload.compactProof,
+        telemetry: payload.telemetry,
+        validation: validationSummary(payload),
+        table: summarizeTablePayload(payload.table),
+        source: summarizeSourcePayload(payload)
+    };
+}
+function summarizeTablePayload(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const table = value;
+    return {
+        info: table.info
+            ? {
+                workbookId: table.info.workbookId,
+                tableName: table.info.tableName,
+                rowCount: table.info.rowCount,
+                columnCount: table.info.columnCount
+            }
+            : undefined,
+        headerCount: Array.isArray(table.headers?.[0]) ? table.headers[0].length : undefined,
+        rowCount: Array.isArray(table.values) ? table.values.length : undefined,
+        hasValues: Array.isArray(table.values),
+        hasFormulas: Array.isArray(table.formulas),
+        hasText: Array.isArray(table.text),
+        hasNumberFormat: Array.isArray(table.numberFormat)
+    };
+}
+function summarizeSourcePayload(payload) {
+    if (Array.isArray(payload.data)) {
+        return {
+            dataCount: payload.data.length,
+            snapshotCount: payload.data.filter((item) => Boolean(item.snapshot)).length
+        };
+    }
+    return undefined;
+}
+function validationSummary(payload) {
+    const issueCount = typeof payload.issueCount === "number" ? payload.issueCount : undefined;
+    const issues = Array.isArray(payload.issues) ? payload.issues : undefined;
+    const severityCounts = (payload.severityCounts ?? payload.summary);
+    if (issueCount === undefined && issues === undefined && severityCounts === undefined) {
+        return undefined;
+    }
+    return {
+        issueCount: issueCount ?? issues?.length ?? 0,
+        severityCounts
+    };
+}
 function jsonResource(uri, value) {
     return {
         contents: [
@@ -4691,6 +7005,16 @@ function readArg(name) {
     }
     return undefined;
 }
+function parseToolNameList(value) {
+    if (value === undefined || value.trim() === "") {
+        return undefined;
+    }
+    const names = value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return names.length > 0 ? new Set(names) : undefined;
+}
 function trimTrailingSlash(value) {
     return value.endsWith("/") ? value.slice(0, -1) : value;
 }