Struct ToolDefinition

Source

pub struct ToolDefinition {
    pub name: String,
    pub description: String,
    pub parameters: Value,
    pub kind: ToolKind,
    pub approval_mode: ApprovalMode,
    pub executor: Option<Arc<dyn Tool>>,
}

Expand description

A uniform, cloneable descriptor of a tool passed via ChatOptions::tools.

For function tools it carries an executor (Arc<dyn Tool>); hosted tools and declaration-only tools carry None.

Fields§

§name: String§description: String§parameters: Value

JSON Schema for the parameters (empty object for tools with no params).

§kind: ToolKind§approval_mode: ApprovalMode§executor: Option<Arc<dyn Tool>>

The local executor, if this is an invokable function tool.

Implementations§

Source §

impl ToolDefinition

Source

pub fn is_executable(&self) -> bool

Whether this tool has a local implementation to execute.

Source

pub fn requires_approval(&self) -> bool

Whether a human must approve a call to this tool before it executes.

Source

pub fn with_approval_mode(self, mode: ApprovalMode) -> ToolDefinition

Builder: set the human-in-the-loop approval mode (default ApprovalMode::NeverRequire). When set to ApprovalMode::AlwaysRequire, the function-invocation loop returns a FunctionApprovalRequestContent instead of executing the call.

Source

pub fn require_approval(self) -> ToolDefinition

Builder: require human approval before every call to this tool.

Source

pub fn description(self, description: impl Into<String>) -> ToolDefinition

Builder: set the tool’s description.

Works on any ToolDefinition, but is primarily useful right after a hosted constructor (hosted_web_search, hosted_file_search, hosted_code_interpreter, hosted_mcp), none of which take a description argument. For a hosted_mcp tool specifically, the OpenAI Responses API forwards a non-empty description as the hosted MCP server’s server_description.

Source

pub fn user_location(self, location: Value) -> ToolDefinition

Builder: the web-search tool’s approximate user location.

Read by the OpenAI Chat Completions and Responses APIs (as web_search_options.user_location.approximate / web_search.user_location) and by Anthropic’s web-search tool (user_location). Ignored by Azure AI Foundry’s Bing-backed web search. Writes parameters["user_location"]; the value’s shape is provider-specific (e.g. {"city": "Seattle", "country": "US"}). Use immediately after hosted_web_search.

Source

pub fn max_uses(self, max_uses: u32) -> ToolDefinition

Builder: cap the number of searches a hosted web-search tool may perform while answering a single request.

Read by Anthropic only (max_uses); OpenAI and Azure AI Foundry ignore it. Writes parameters["max_uses"]. Use immediately after hosted_web_search.

Source

pub fn connection_id(self, connection_id: impl Into<String>) -> ToolDefinition

Builder: an Azure AI Foundry Bing Grounding connection id.

Read by Azure AI Foundry only, to build a bing_grounding tool. Mutually exclusive with ToolDefinition::custom_connection: a fully-specified custom pair takes precedence over this plain id, and a partial custom pair (only one of the two custom fields) still disqualifies this plain id – Azure AI Foundry then rejects the tool outright for having no usable connection. Writes parameters["connection_id"]. Use immediately after hosted_web_search.

Source

pub fn custom_connection( self, connection_id: impl Into<String>, instance_name: impl Into<String>, ) -> ToolDefinition

Builder: an Azure AI Foundry Bing Custom Search connection: a connection id plus the custom-search instance name.

Read by Azure AI Foundry only, to build a bing_custom_search tool; takes precedence over a plain ToolDefinition::connection_id when both are set. Writes parameters["custom_connection_id"] and parameters["instance_name"]. Use immediately after hosted_web_search.

Source

pub fn vector_store_ids(self, ids: Vec<String>) -> ToolDefinition

Builder: the vector store ids a hosted file-search tool should search.

Read by the OpenAI Responses API and Azure AI Foundry. Ignored by Anthropic, which has no file-search tool (unsupported by the Anthropic Messages API). Writes parameters["vector_store_ids"]. Use immediately after hosted_file_search.

Source

pub fn max_results(self, max_results: u32) -> ToolDefinition

Builder: cap the number of results a hosted file-search tool returns.

Read by the OpenAI Responses API only, and only as a fallback: pass max_results directly to hosted_file_search where possible, which takes precedence over this parameter when both are set (and is the only option Azure AI Foundry honors, since it does not read this key). Writes parameters["max_results"].

Source

pub fn file_ids(self, file_ids: Vec<String>) -> ToolDefinition

Builder: file ids attached to a hosted code-interpreter tool’s container.

Read by the OpenAI Responses API, which folds them into a default {"type": "auto"} container unless ToolDefinition::container supplies an explicit override (which then wins outright and this key is ignored). Writes parameters["file_ids"]. Use immediately after hosted_code_interpreter.

Source

pub fn container(self, container: Value) -> ToolDefinition

Builder: an explicit container object for a hosted code-interpreter tool, overriding the default {"type": "auto"} container (and any ToolDefinition::file_ids).

Read by the OpenAI Responses API only. Writes parameters["container"]. Use immediately after hosted_code_interpreter.

Source

pub fn headers(self, headers: HashMap<String, String>) -> ToolDefinition

Builder: HTTP headers sent with requests to a hosted MCP server.

Read by the OpenAI Responses API (forwarded verbatim as headers), Anthropic (only the lower-case "authorization" entry, mapped to authorization_token), and Azure AI Foundry (forwarded verbatim, when non-empty). Writes parameters["headers"]. Use immediately after hosted_mcp.

Source

pub fn mcp_approval_mode(self, mode: McpApprovalMode) -> ToolDefinition

Builder: the hosted MCP server’s own approval gate for its tool calls – see McpApprovalMode.

Read by the OpenAI Responses API and Azure AI Foundry as parameters["approval_mode"]; not read by the Anthropic converter in this port (Anthropic’s MCP connector has no per-tool approval concept here). Use immediately after hosted_mcp.

Source