@grid-is/agent-tools

GRID's spreadsheet tools for AI agents: load, read, edit, and recalculate .xlsx workbooks headlessly. Use the tools directly from your own agent SDK, or run them as an MCP server over stdio.

Installation

npm install @grid-is/agent-tools

The engine installs automatically as a dependency — nothing else to add, and no GRID registry token required. See The engine to run on a licensed Apiary build instead.

Getting started

createGridTools() returns the full set of tools, each { name, description, inputSchema, run }. Wire them into your own agent SDK:

import { createGridTools } from "@grid-is/agent-tools";

const tools = createGridTools();
const load = tools.find((t) => t.name === "loadWorkbook");
await load.run({ path: "budget.xlsx" });

inputSchema is a zod raw shape; z.toJSONSchema(z.object(tool.inputSchema)) produces the JSON Schema most SDKs expect.

Or run the tools as an MCP server over stdio, for any MCP-capable runtime:

import { serveStdio, createGridTools } from "@grid-is/agent-tools";

await serveStdio({ tools: createGridTools() });

Tools

| Group | Tools | | --- | --- | | Lifecycle | loadWorkbook createWorkbook saveWorkbook listWorkbooks selectWorkbook | | Understand | describeStructure generateWorkbookContext symbols viewRange captureRange inspect findCells | | Audit | precedents dependents listErrors getStyles getComments getComment | | Edit | editCells fillCells editCellStyles manageSheets manageRowsAndColumns | | Model | readCalculatedValues runFormula goalSeek whatIf | | Escape hatch | executeOfficeJs |

Each tool operates on the active workbook (the last one loaded or selected). The per-tool reference lives in docs/ (cd docs && npm ci && npm run dev).

The engine

The tools run on the engine installed under the @grid-is/apiary name — by default the free @grid-is/spreadsheet-engine. To run on a licensed Apiary build, override the name:

"overrides": { "@grid-is/apiary": "17.0.0-beta.1" }

Development

npm install
npm run build      # tsdown → dist/
npm test           # smoke test against test/fixtures/sample.xlsx
npm run typecheck
npm run gen:docs   # regenerate the per-tool reference under docs/src/content/docs/tools/