Agent tools

@elastic/isomer-agent-tools turns any Isomer runtime into agent tools: read the authoring guide, look up the primitives it indexes, validate a composition, render it, and, when the runtime registers views, list them and request one. Beside them it offers the guide and the composition JSON Schema as resources, and a compose prompt. Everything is plain data with a Zod schema, so the host brings the transport: an MCP server, the AI SDK, or its own agent framework. The package depends on the SDK alone, and never on @modelcontextprotocol/sdk.

It is not published to npm yet; it lives in this repository until its API settles.

import {
  createIsomerPrompts,
  createIsomerResources,
  createIsomerTools,
} from '@elastic/isomer-agent-tools';

const tools = createIsomerTools({ runtime });
const resources = createIsomerResources({ runtime });
const prompts = createIsomerPrompts({ runtime });
		

runtime is declared structurally, as IsomerToolsRuntime, so only this package's tests import @elastic/isomer-runtime. Pass a real IsomerRuntime, which satisfies it.

The two view tools are offered only when the runtime lists a view when the tools are created.

The composition input is a loose object: the node union is recursive and too large for a tool schema, so its description sends the model to the guide and the primitive lookup first, and isomer_validate enforces shape.

The tools check a composition once with the SDK's checkComposition from @elastic/isomer-sdk/author, passing the frame, and print what it returns: each of errors is a formatValidationError string, <path> (in <type>) <message>, naming the primitive the model should look up to repair it, and a frame rule's error has an empty path. A host that wants the structured ValidationError values calls checkComposition itself.

The guide indexes the catalog rather than inlining it, so it stays small as packs grow. JSON Schema is printed compact, without indentation. A host that wants the whole schema reads the isomer://composition-schema resource, which is large (about 59 KB for the slides pack), so its description sends a model to the index and isomer_describe_primitives instead.

Tests hold the slides pack's tools/list, guide, and each one-type describe under byte ceilings, so a change that grows what an agent reads shows up in review.

createIsomerResources and createIsomerPrompts take runtime, guide, rules, examples, and profile (IsomerGuideOptions).

The runtime renders text, markdown, html, and slack itself. Anything else, such as a PNG, an SVG, or a PDF, is a format the host renders from the runtime's snapshot surface, so the tools take each as a renderer rather than a flag. A rasterizer that writes several formats registers one entry per format:

const takumi = createTakumiImageBackend({ fonts });
const { snapshot } = runtime.surfaces;

const tools = createIsomerTools({
  runtime,
  formats: {
    png: { mimeType: 'image/png', render: (composition, options) => takumi.png(snapshot.render(composition, options)) },
    svg: { mimeType: 'image/svg+xml', render: (composition, options) => takumi.svg(snapshot.render(composition, options)) },
    pdf: {
      mimeType: 'application/pdf',
      render: (composition, options) => takumi.pdf(snapshot.renderPages([composition], options)),
    },
  },
});
		

How a format answers follows its mimeType. An image/* type answers as an image block, a string render result UTF-8 encoded first, so an SVG reaches a client that displays images. Any other type answers as a text block when render resolves to a string, and otherwise as an embedded resource, { type: 'resource', resource: { uri, mimeType, blob } }, whose uri is isomer://render/<format>. A render that rejects is a failed call with its message.

An adapter maps the three lists onto a transport. On an MCP McpServer:

for (const tool of tools) {
  const { name, title, description, inputSchema } = tool;
  if (Object.keys(inputSchema.shape).length === 0) {
    server.registerTool(name, { title, description }, () => tool.handler(inputSchema.parse({})));
  } else {
    server.registerTool(name, { title, description, inputSchema }, (input) => tool.handler(input));
  }
}
for (const resource of resources) {
  const { name, uri, title, description, mimeType } = resource;
  server.registerResource(name, uri, { title, description, mimeType }, ({ href }) => ({
    contents: [{ uri: href, mimeType, text: resource.read() }],
  }));
}
for (const prompt of prompts) {
  const { name, title, description, argsSchema } = prompt;
  server.registerPrompt(name, { title, description, argsSchema: argsSchema.shape }, (args) => ({
    messages: [{ role: 'user', content: { type: 'text', text: prompt.build(argsSchema.parse(args)) } }],
  }));
}
		

The MCP SDK rejects a call that omits arguments against any inputSchema, even one with no keys, so a tool whose schema has no keys is registered without one.

With the AI SDK, each tool becomes a tool():

import { tool } from 'ai';

const aiTools = Object.fromEntries(
  tools.map(({ name, description, inputSchema, handler }) => [
    name,
    tool({ description, inputSchema, execute: (input) => handler(input) }),
  ])
);
		

Every composition a tool receives came from a model. The runtime's validate and viewRegistry.request apply the SDK's input budget, checkInputBudget, before anything else reads a composition or a view's input: by default it must nest at most 64 objects and arrays deep, hold at most 20,000 values, hold at most 1,000,000 characters across object keys and leaves, contain no cycle, and be plain data. The runtime's inputBudget option changes the limits. A refusal is one finding with an empty path and the code INPUT_OVER_BUDGET or INPUT_NOT_PLAIN_DATA, which checkComposition keeps in its errors: isomer_validate answers valid: false, isomer_render fails with the same errors, and isomer_request_view fails with { error, errors } before the view sees the input. isomer_render validates before rendering and renders the copy validate checked, never the raw input, and the runtime's own formats validate that copy again as every surface does; URL fields go through the SDK's sanitizers on every surface. The tools read and write nothing beyond what the runtime and the host's formats and view builders do, so authorization stays with the host: decide what hostContext a caller gets and which views are registered before building the tools.