The tool registry
LLM agents actually need

The problem

Every agent project rewrites the same three things

Different code. Every project. Every framework. No standard.

The real difference

It's not about line count

The raw version is nearly the same length — because the handlers are identical. The difference is what the raw version is missing.

The invisible bug: schema drift

Without toolwire, your JSON schema (sent to the LLM) and your Zod validation (run in code) are two separate things that must stay in sync manually. They don't.

// JSON schema sent to the LLM
const schema = {
  parameters: {
    properties: {
      city: { type: 'string' }
    },
    required: ['city']
  }
}

// Zod validation — written separately.
// Add a field? Update both. Easy to forget.
const args = validateCity(rawArgs)

// One Zod schema. That's it.
const weatherTool = tool({
  name: 'get_weather',
  input: z.object({
    city: z.string().min(1),
  }),
  handler: async ({ city }) => { ... }
})

// JSON schema auto-computed from Zod.
// Validation runs from the same schema.
// Change one thing. Everything stays in sync.

Quick start

Up in 30 seconds

Define a tool, create a registry, call it, export to your provider.

import { tool, registry } from 'toolwire'
import { z } from 'zod'

const searchWeb = tool({
  name: 'search_web',
  description: 'Search the web for current information',
  input: z.object({
    query: z.string().min(1).describe('The search query'),
    maxResults: z.number().int().min(1).max(20).default(5),
  }),
  handler: async ({ query, maxResults }) => {
    return await mySearchAPI(query, maxResults)
  },
  timeout: 10_000,
  retries: 2,
})

const reg = registry([searchWeb, readFile, writeFile])

const tools = reg.toAnthropic()  // or toOpenAI(), toGemini(), toVercelAI()

const result = await reg.call(llmToolCall)

if (result.success) {
  messages.push({ role: 'tool', content: JSON.stringify(result.data) })
} else {
  messages.push({ role: 'tool', content: result.error.llmMessage })
}

Features

Everything your agent loop needs

Built-in. No configuration required for the happy path.

API reference

Small surface. Full control.

Three entry points cover every use case.

const myTool = tool({
  name: 'my_tool',          // 1–64 chars: letters, digits, _ or -
  description: string,      // shown to the LLM — explain when to call this
  input: ZodSchema,         // validates LLM arguments
  output?: ZodSchema,       // optional — validates handler return value
  handler: async (input, context) => { ... },
  timeout?: number,         // ms, default 30_000
  retries?: number,         // extra attempts on execution failure, default 0
  annotations?: {
    readOnly?: boolean,
    destructive?: boolean,
    expensive?: boolean,
  },
})

interface ToolContext {
  signal: AbortSignal // tied to the timeout
  attempt: number     // 0 = first try, 1 = first retry, …
}

const reg = registry([searchWeb, readFile, writeFile], {
  defaultTimeout: 15_000,
})

const result = await reg.call({ name: 'search_web', arguments: { query: 'hello' } })

if (result.success) {
  result.data        // validated return value
  result.durationMs  // wall time
} else {
  result.error.code       // error category (see table below)
  result.error.message    // developer-readable
  result.error.llmMessage // formatted for the LLM to retry
  result.error.retryable  // boolean
  result.error.issues     // Zod issue array (VALIDATION_* errors only)
}

reg.register(newTool)           // add a tool at runtime
reg.swap('search_web', v2Tool)  // hot-replace a registered tool
reg.disable('send_email')       // block a tool (returns DISABLED if called)
reg.enable('send_email')        // re-enable it
reg.use(middleware)             // add middleware
reg.list()                      // → ['search_web', 'read_file', ...]
reg.get('search_web')           // → ToolDefinition | undefined
reg.describe()                  // → human-readable summary for system prompts

const reg = await ToolRegistry.fromDir('./tools/')
const reg = await ToolRegistry.fromManifest('https://tools.myco.com/manifest.json')

Provider adapters

One definition. Every provider.

Each adapter reads the pre-computed JSON Schema from your tool definitions. No re-conversion. No format drift. Disabled tools are always excluded.

reg.toOpenAI()               // { type: 'function', function: { name, description, parameters } }
reg.toOpenAI({ strict: true })
reg.toAnthropic()            // { name, description, input_schema }
reg.toGemini()               // { functionDeclarations: [{ name, description, parametersJsonSchema }] }
reg.toVercelAI()             // { [name]: { description, parameters: ZodSchema } }

import { toOpenAI, toAnthropic } from 'toolwire'
toOpenAI([searchWeb, readFile])

Middleware

Plug in observability in 3 lines

Hooks run before and after every tool call. Multiple middleware chain in order for beforeCall, reverse order for afterCall.

reg.use({
  name: 'logger',
  beforeCall: (toolName, args) => {
    console.log(`→ ${toolName}`, args)
    span.start(toolName)
  },
  afterCall: (toolName, args, result) => {
    span.end(toolName, result.durationMs)
    metrics.record(toolName, result.data)
  },
  onError: (toolName, args, failure) => {
    alerting.send(toolName, failure.error)
    // return a ToolResult here to recover silently
  },
})

reg
  .use({ name: 'auth',    beforeCall: checkToken })
  .use({ name: 'cache',   beforeCall: checkCache, afterCall: writeCache })
  .use({ name: 'metrics', afterCall: recordMetrics })

TypeScript

Types flow end-to-end

Input and output types are inferred from your Zod schemas. No manual generics.

import type { InferInput, InferOutput } from 'toolwire'

const greet = tool({
  name: 'greet',
  description: 'Greet someone',
  input: z.object({ name: z.string() }),
  output: z.object({ message: z.string() }),
  handler: async ({ name }) => ({ message: `Hello, ${name}!` }),
})

type GreetInput  = InferInput<typeof greet>   // { name: string }
type GreetOutput = InferOutput<typeof greet>  // { message: string }

// Zod v3: install the optional peer — npm install zod-to-json-schema
// toolwire detects the version automatically.