Tools

Tools are a boundary you supply

StateWeave owns the graph. Models and tools are explicit boundaries you pass to Agent.

Tool contract

A tool is a small object with a name, a description, a Zod schema, and an executor.

type Tool = {
  name: string;
  description: string;
  schema: z.ZodSchema;
  execute: (args: unknown) => Promise<unknown>;
};

const agent = new Agent({ model, tools: [lookupOrder] });

Descriptions become part of the provider’s system contract. The runtime validates arguments before execution and records both success and failure.

Default workspace tools

Omit tools and Agent creates four workspace-scoped tools:

read_file
write_file
edit_file
read-only bash_command

Pass tools: [] for no tools. Pass your own array to replace the defaults.

import { createFileSystemTools } from "stateweave";

const tools = createFileSystemTools({
  rootDir: "/srv/sandboxes/run-123",
  timeoutMs: 5_000,
  maxOutputBytes: 32_000,
  allowedBashCommands: ["pwd", "ls", "rg", "node"]
});

Boundaries built in

The file tools reject absolute paths, traversal, and symlink components. The shell tool is a fixed-PATH, read-only allowlist. It rejects pipes, redirects, command substitution, arbitrary interpreters, and network commands. These checks reduce scope. They are not a process sandbox.

Security boundary. For untrusted coding work, run the whole agent inside an isolated filesystem and process boundary. StateWeave’s path checks are defense in depth, not tenant isolation.

Design tools for evidence

Return small, structured values with stable identifiers and status.

return { ok: true, resource: "order:ord_123", version: "7", status: "shipped" };

Structured results improve projection and inspection. Do not return secrets, unlimited logs, or data the next call does not need. Next: Models.

Start

Understand

Build

Reference

Tools are a boundary you supply

Tool contract

Default workspace tools

Boundaries built in

Design tools for evidence

​Tools are a boundary you supply

​Tool contract

​Default workspace tools

​Boundaries built in

​Design tools for evidence

Tools are a boundary you supply

Tool contract

Default workspace tools

Boundaries built in

Design tools for evidence