#Custom tools

Tools are how the model acts on the world. Beyond the built-in tools, tool() lets you define your own — a typed function the model can call — from a Zod schema. The schema validates every call before your code runs, so your handler only ever sees well-formed input. Custom tools are appended after the built-ins and go through the same permission gate and allowedTools / disallowedTools filtering.

#Defining a tool

import { query, tool } from "@lite-agent/sdk";
import { anthropic } from "@lite-agent/provider";
import { z } from "zod";

const weather = tool(
  "get_weather",
  "Get the weather for a city",
  z.object({ city: z.string() }),
  async ({ city }) => `It's sunny in ${city}.`,
);

for await (const ev of query({
  prompt: "What's the weather in Tokyo?",
  model: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
  modelName: "claude-sonnet-4-6",
  tools: [weather],
  allowedTools: ["get_weather", "read_file"],
})) {
  if (ev.type === "text_delta") process.stdout.write(ev.text);
}

#The tool() signature

tool(name, description, schema, handler, opts?)

#ToolContext

The handler's second argument carries per-call services provided by the kernel:

#Security metadata

opts.security declares what a tool can reach, typed as ToolSecurity:

Hosts can inspect this metadata when selecting tools and composing a permission policy. It is a declaration, not an isolation boundary: in-process JavaScript tools are trusted host code. See deployment composition.

#See also

• Built-in tools — the tool set that ships with the SDK.
• Permissions — gate custom and built-in tools with allow / ask / deny rules.
• Agent SDK overview — where custom tools fit in the assembled agent.
• CLI example — a full agent wiring custom tools end to end.