Tool

Namespace: Vercel.AI

public sealed class Tool

A tool the model can call. Maps to tool().

Inheritance: object

View source

Constructors

Tool(string, string?, JsonElement, Func<JsonElement, CancellationToken, Task<string>>?, bool?)

public Tool(string name, string? description, JsonElement inputSchema, Func<JsonElement, CancellationToken, Task<string>>? execute, bool? strict = null)

Creates a function tool.

Parameters

Name	Type	Description
name	string
description	string
inputSchema	JsonElement
execute	Func<JsonElement, CancellationToken, Task<string>>
strict	bool?

View source

Properties

Description

public string? Description { get; }

Tool description.

Value: string

View source

Execute

public Func<JsonElement, CancellationToken, Task<string>>? Execute { get; }

Executes the tool and returns a JSON string. Null means the call is not executed locally, unless ExecuteWithOptions is set.

Value: Func<JsonElement, CancellationToken, Task<string>>

View source

ExecuteWithOptions

public Func<JsonElement, ToolExecutionOptions, Task<string>>? ExecuteWithOptions { get; set; }

Executes the tool with the options of the call, such as the messages of the step. When it is set, the loop calls it instead of Execute. Maps to execute(input, { toolCallId, messages, abortSignal }).

Value: Func<JsonElement, ToolExecutionOptions, Task<string>>

View source

InputSchema

public JsonElement InputSchema { get; }

JSON Schema for the arguments. Undefined for a provider-defined tool declared without one.

Value: JsonElement

View source

IsDynamic

public bool IsDynamic { get; set; }

True for a tool whose input type is not known at compile time, such as an MCP tool. Parsed calls of the tool are dynamic. Maps to dynamicTool.

Value: bool

View source

IsProviderDefined

public bool IsProviderDefined { get; }

Whether this is a provider-defined tool, which the provider executes. Maps to { type: 'provider', id, args }.

Value: bool

View source

Metadata

public IReadOnlyDictionary<string, JsonElement>? Metadata { get; set; }

Metadata of the tool, such as the name of the client that created it. Parsed calls of the tool carry it as tool metadata, apart from provider metadata.

Value: IReadOnlyDictionary<string, JsonElement>

View source

Name

public string Name { get; }

Tool name.

Value: string

View source

NeedsApproval

public bool NeedsApproval { get; set; }

When true, a call to this tool is not executed. The loop ends at that step and the call is left for the caller, unless ApproveTool is set, which then decides. Maps to needsApproval.

Value: bool

View source

ProviderOptions

public JsonElement? ProviderOptions { get; set; }

Provider options of the tool, keyed by provider name, such as { "openai": { "omitFromRequestTools": true } }. Maps to the tool’s providerOptions.

Value: JsonElement?

View source

ProviderToolArgs

public JsonElement ProviderToolArgs { get; }

Arguments of a provider-defined tool. Undefined for a function tool.

Value: JsonElement

View source

ProviderToolId

public string? ProviderToolId { get; }

Provider-defined tool id (<provider>.<tool>), or null for a function tool.

Value: string

View source

Strict

public bool? Strict { get; }

Responses strict mode. Null means unset, which Responses sends as false.

Value: bool?

View source

Title

public string? Title { get; set; }

Display title of the tool. Parsed calls of the tool carry it.

Value: string

View source

ToModelOutput

public Func<ToolModelOutputCall, ToolModelOutput>? ToModelOutput { get; set; }

Converts the JSON output of the tool into the result sent to the model. Null sends the output as it is. Maps to toModelOutput.

Value: Func<ToolModelOutputCall, ToolModelOutput>

View source

Methods

DynamicTool(string, string?, string, Func<JsonElement, CancellationToken, Task<string>>?)

public static Tool DynamicTool(string name, string? description, string jsonSchema, Func<JsonElement, CancellationToken, Task<string>>? execute)

Creates a dynamic tool from a JSON schema string. Maps to dynamicTool.

Parameters

Name	Type	Description
name	string
description	string
jsonSchema	string
execute	Func<JsonElement, CancellationToken, Task<string>>

Returns: Tool

View source

Function(string, string?, string, Func<JsonElement, CancellationToken, Task<string>>?, bool?)

public static Tool Function(string name, string? description, string jsonSchema, Func<JsonElement, CancellationToken, Task<string>>? execute, bool? strict = null)

Creates a tool from a JSON schema string.

Parameters

Name	Type	Description
name	string
description	string
jsonSchema	string
execute	Func<JsonElement, CancellationToken, Task<string>>
strict	bool?

Returns: Tool

View source

ProviderDefined(string, string, JsonElement)

public static Tool ProviderDefined(string id, string name, JsonElement args)

Declares a provider-defined tool. The provider executes it, so it has no Execute. <code class=“paramref”>args</code> must be a JSON object. Maps to JsonElement).

Parameters

Name	Type	Description
id	string
name	string
args	JsonElement

Returns: Tool

View source

ProviderDefined(string, string, JsonElement, JsonElement)

public static Tool ProviderDefined(string id, string name, JsonElement args, JsonElement inputSchema)

Declares a provider-defined tool with an input schema. The input of a call the provider ran is parsed with the schema, so a property the schema does not declare is dropped, as a Zod object does. Maps to a provider tool’s inputSchema.

Parameters

Name	Type	Description
id	string
name	string
args	JsonElement
inputSchema	JsonElement

Returns: Tool

View source