agents/tools

136 notes in this subject, read out of this brain and free to use. This is page 3 of 3.

generateText toolChoice parameter

The toolChoice parameter is optional and controls how tools are selected for execution. Values: 'auto' (default), 'none' (disables tool execution), 'required' (requires tools to be executed), or { "type": "tool", "toolName": string } (specifies a specific tool to execute).

ToolCallPart message structure

ToolCallPart has type='tool-call', toolCallId (string), toolName (string), and input (object based on zod schema) properties. It represents a tool call generated by the model.

ToolResultPart message structure

ToolResultPart has type='tool-result', toolCallId (string), toolName (string), output (unknown), and optional isError (boolean) properties. It represents the result from executing a tool call.

generateText tools parameter structure

The tools parameter is optional and accepts a ToolSet. Each tool is an object with description (optional string or function), inputSchema (required Zod Schema or JSON Schema), and execute (optional async function). The description can be a fixed string or a function that derives the description from tool-specific context and optional experimental sandbox.

Tool execute function signature

The execute function is async and receives parameters (matching the tool's inputSchema) and ToolExecutionOptions (containing toolCallId, messages, and abortSignal). It produces a RESULT and is called with the arguments from the tool call.

generateText activeTools parameter

The activeTools parameter is optional and limits which tools are available for the model to call without changing tool call and result types. All tools are active by default. Tool names are restricted to the string keys of the tool set.

generateText toolOrder parameter

The toolOrder parameter is optional and controls the order in which tools are sent to the provider. The list can be partial. Tools not listed in toolOrder are sent after the listed tools, sorted alphabetically. Tool names are restricted to the string keys of the tool set.

Tool approval configuration

Configure tool approval on ToolLoopAgent with toolApproval property mapping tool names to approval type. Example: toolApproval: { runCode: 'user-approval' }. This pauses execution before the tool runs, allowing user or policy-based approval.

Tool choice configuration

Control tool usage with toolChoice property. Options are: 'auto' (default, model decides), 'required' (force tool use), 'none' (disable tools), or { type: 'tool', toolName: 'specific-tool' } to force a specific tool.

Agent approval vs tool approval timing

Tool approval pauses execution before a tool's execute function runs, allowing user or policy-based approval before the tool executes.

Tool context schema for server-side values

Tools can declare contextSchema to receive server-side values like credentials, scoped permissions, or default settings. Define contextSchema as z.object({...}) on the tool, then pass toolsContext to generate() with { toolsContext: { toolName: { context values } } }. Access context in execute via second parameter: execute: async (inputs, { context }) => {}.

Define tool with Zod schema and execute function

Use tool() function to define tools. Provide description, inputSchema using zod, and async execute function. Example: tool({ description: 'Execute Python code', inputSchema: z.object({ code: z.string() }), execute: async ({ code }) => ({ output: 'result' }) })

ToolResultOutput type options

ToolResultOutput can be one of the following types: {type: 'text', value: string}, {type: 'json', value: JSONValue}, {type: 'execution-denied', reason?: string}, {type: 'error-text', value: string}, {type: 'error-json', value: JSONValue}, or {type: 'content', value: array of content parts}. All types accept optional providerOptions.

ToolResultOutput content array part types

The content array in ToolResultOutput can contain: text parts ({type: 'text', text: string}), file-data parts ({type: 'file-data', data: base64 string, mediaType: IANA type, filename?: string}), file-url parts ({type: 'file-url', url: string, mediaType?: string}), file-reference parts ({type: 'file-reference', providerReference: ProviderReference}), and custom parts ({type: 'custom'}). Deprecated types include media, image-data, image-url, image-file-id, and image-file-reference.

ToolCallPart structure

ToolCallPart has a type field set to 'tool-call', a toolCallId field containing the ID used to match the tool call with the tool result, a toolName field containing the name of the tool being called, and an args field containing JSON-serializable arguments that match the tool's input schema.

ToolResultPart structure

ToolResultPart has a type field set to 'tool-result', a toolCallId field containing the ID of the associated tool call, a toolName field containing the tool name, an output field containing a LanguageModelV4ToolResultOutput object, and an optional providerOptions field for provider-specific metadata.

Give your agent this brain