Skip to content
Browse documentation
typescript sdk

Define, bind and execute tools

Give an operation typed JSON contracts and a stable implementation identity before exposing it to a model.

Define one bounded operation

Use a supported Standard JSON Schema authoring library for inferred inputs and outputs. The runtime validates the portable schema, not arbitrary schema-library callbacks.

import { z } from "zod";
import { defineTool } from "@smoothie-framework/runtime/tools";

export const normalizeTitle = defineTool({
  name: "normalize_title",
  description: "Normalize a short document title.",
  capability: "documents.normalize",
  input: z.strictObject({ title: z.string().max(200) }),
  output: z.strictObject({ title: z.string() }),
  bindingIdentity: { adapter: "title-normalizer", revision: 1 },
  execute: ({ title }) => ({ title: title.trim() }),
});

Normalization here is explicit binding code, not a hidden schema transform. Change bindingIdentity when implementation semantics change. Never put secrets in identity metadata.

Bind execution to the owning context

Attach the Tool to an Agent definition or construct createToolRuntime with the Tool set and a trusted execution context. That context supplies policy checks, cancellation and optional approvals; the definition alone grants no execution.

Inputs are validated before binding work and outputs before model visibility. Use toModelOutput when the model should see a smaller projection than the application's full return value.

Use Agent authoring for model-loop execution and Tool policies for the decision boundary.