Represent completed tool execution
Build or validate tool messages passed to AI SDK Core model operations.
AI Tools · Type Alias
ToolResultPart
ToolResultPart represents one completed tool call within a tool message. It links the result to the call and tool, stores JSON-serializable output, and optionally carries provider-specific metadata.
How it works
ToolResultPart is one item in a tool message's content array. It identifies the completed call, names the tool, carries its JSON-serializable output, and can optionally preserve provider-specific options for downstream handling.
Syntax
export interface ToolResultPart {
type: 'tool-result';
toolCallId: string;
toolName: string;
output: ToolResultOutput;
providerOptions?: ProviderOptions;
}Parameters
| Name | Type | Description |
|---|---|---|
type | 'tool-result' | Discriminator identifying this part as a tool result. |
toolCallId | string | ID of the associated tool call. |
toolName | string | Name of the tool that generated the result. |
output | ToolResultOutput | JSON-serializable result of the tool call. |
providerOptions | ProviderOptions | undefined | Optional provider-specific metadata. |
Returns
A ToolResultPart object representing one tool-call result in a tool message.
Key points
- A ToolResultPart is the message-level representation of a completed tool invocation.
- The literal type value acts as the discriminant for recognizing this part as a tool result.
- toolCallId correlates the result with the specific tool call that produced it.
- toolName records the tool responsible for generating the result.
- output stores the value returned by executing the tool.
- Optional providerOptions are forwarded through the SDK to support provider-specific functionality.
Common mistakes
- The output must be JSON-serializable; arbitrary class instances or functions do not satisfy the documented contract.
- providerOptions is optional and is intended for provider-specific behavior, so it should not replace the portable output field.
Example: Construct a tool result
import type { ToolResultPart } from 'ai';
const result: ToolResultPart = {
type: 'tool-result',
toolCallId: 'call_123',
toolName: 'weather',
output: { temperatureC: 21, condition: 'clear' },
};
console.log(result.output);Creates a typed tool-result message part with the call identity, tool name, and JSON-serializable output.
When to use it
Match results to calls
Correlate returned data with the exact invocation in a multi-call conversation.
Forward provider options
Preserve provider-specific metadata while keeping the result structure standardized.
Interview questions
QWhat does ToolResultPart model?
ToolResultPart represents the result of a tool call inside a tool message. Its required fields identify the part as a tool result, associate it with the call, name the tool, and provide the output.
Follow-up: How is it placed in a model message? It is an element of ToolContent, and ToolContent is an array of ToolResultPart values.
QHow does a consumer identify the result?
The discriminator is type: 'tool-result'. toolCallId links the result to the originating call, while toolName records which tool produced it.
Follow-up: Why retain both identifiers? A call ID provides correlation, while the tool name supplies semantic identity for consumers handling the message.
QWhat are output and providerOptions for?
output contains the tool's JSON-serializable result. providerOptions may carry provider-specific metadata that the SDK passes through to the provider.
Follow-up: When should providerOptions be used? Use it only when a provider feature requires extra metadata; keep the actual tool result in output.
Related
ToolModelMessageToolContentModelMessageProviderOptionsToolResultOutput