Required & Multiple Tools

Force the model to call specific tools and use multiple tools simultaneously.

Required Tools

Setting required: true forces the model to call the tool instead of freely choosing whether to call it. This is useful when you need to ensure the model always performs a specific operation (e.g., data validation, permission checks):

const validateTool = tool({
  name: 'validateInput',
  description: 'Validate the legitimacy of user input',
  schema: z.object({
    input: z.string().describe('Input to validate'),
  }),
  required: true,
  execute: async (input) => {
    return { valid: true, sanitized: input.input }
  },
})

When only one tool is marked as required, tool_choice is set to that tool; when multiple tools are marked as required, tool_choice is set to "required".

Multiple Tools

You can pass multiple tools simultaneously, and the model will autonomously choose which tools to call based on context:

const weatherTool = tool({
  name: 'getWeather',
  description: 'Query weather information for a city',
  schema: z.object({ city: z.string().describe('City name') }),
  execute: async input => getWeather(input.city),
})

const calculatorTool = tool({
  name: 'calculator',
  description: 'Perform mathematical calculations',
  schema: z.object({ expression: z.string().describe('Mathematical expression') }),
  execute: async input => evaluate(input.expression),
})

const agent = createAgent({
  model,
  tools: [weatherTool, calculatorTool],
})

const result = await agent.generate({
  prompt: 'How\'s the weather in Beijing? Also calculate 25 * 4 for me.',
})
Strict Mode
Strict mode ensures the model strictly follows the JSON Schema format when generating function calls.
Execution Control
Control tool execution behavior — results, timeout & retry, result compaction, and cancellation.