Output Schema Validation

Tools can declare an outputSchema (a Zod type) that the runtime validates the tool result against after execution. Validation failures are non-fatal — a warning is logged but the result is returned to the agent unchanged.

Declaring an output schema

import { z } from 'zod'

export const searchTool: ToolDefinition = {
  name: 'search',
  description: 'Search the web',
  parameters: z.object({ query: z.string() }),
  outputSchema: z.object({
    results: z.array(z.object({
      title: z.string(),
      url: z.string().url(),
      snippet: z.string(),
    })),
    totalCount: z.number(),
  }),
  execute: async ({ query }) => {
    return await webSearch(query)
  },
}

Validation behaviour

• If the result passes: no action, result forwarded to agent
• If the result fails: warning logged via logger.warn with Zod error details; result still forwarded to agent unchanged
• Validation never throws or blocks the agent loop

Why non-fatal?

Output schema validation is a development-time safety net, not a production gate. Making it fatal would cause tools to silently break agents when upstream APIs change shape. The warning surface is enough to catch schema drift during development without introducing production failures.