tool-definition

Tool Definition

The pattern

A Tool is defined by calling buildTool({ ... }), which fills in safe defaults for isEnabled, isConcurrencySafe, isReadOnly, isDestructive, checkPermissions, and other housekeeping methods. The Input is a Zod schema exposed via a get inputSchema() getter. The Output is the TypeScript type of data inside the result. These compose: the Zod schema drives runtime validation AND TypeScript types simultaneously, eliminating a class of bugs where validation and types diverge.

The key insight: buildTool factory + checkPermissions method + typed throw for errors. Permissions are not checked inside call() — the framework calls checkPermissions(input, context) before dispatching to call(). Errors are thrown (not returned), and the framework formats them for the LLM.

Why this matters

The LLM produces tool calls as JSON objects. Claude Code must: (1) validate the JSON against a schema, (2) check if the user permits this call, (3) execute the tool, (4) return a structured result back to the LLM. These four steps must be explicit and in order.

If a tool checked permissions after execution (or not at all), security would be broken. If validation happened after permission checking, the LLM could construct inputs that bypass validation for permitted tools. The pattern enforces the correct order: schema validation happens automatically when the framework calls the tool; checkPermissions is called by the framework before call() is ever reached; call() can assume permission is already granted.

Using Zod as the schema source of truth means the LLM's JSON schema (shown in the system prompt) and the runtime validator are the same artifact. When you change one, you change both.

How to apply it

1. Define inputSchema using lazySchema(() => z.strictObject({ ... })). Add .describe() to each field — these become the LLM's parameter documentation.
2. Implement isConcurrencySafe(input) and isReadOnly(input). These are called with the actual input, so you can make them input-dependent (e.g., a bash tool is concurrent-safe only for read commands).
3. Implement checkPermissions() for side-effect tools — the framework calls it before call(). Return a PermissionDecision indicating whether execution is allowed.
4. Return { data: result } from call() on success; throw for errors (the framework formats thrown errors for the LLM).
5. Use onProgress to stream partial results to the UI. Call it with typed progress objects as work proceeds.