OpenAiTool
The OpenAiTool module defines OpenAI provider tools for Effect AI language model requests. It exposes typed descriptors for tools such as Apply Patch, Code Interpreter, File Search, Image Generation, MCP, Web Search, and shell-like local tools, including their provider names, configuration arguments, call parameters, success schemas, and handler requirements.
Models
OpenAiTool type
Signature
type OpenAiTool = | ReturnType<typeof ApplyPatch> | ReturnType<typeof CodeInterpreter> | ReturnType<typeof FileSearch> | ReturnType<typeof Shell> | ReturnType<typeof ImageGeneration> | ReturnType<typeof LocalShell> | ReturnType<typeof Mcp> | ReturnType<typeof WebSearch> | ReturnType<typeof WebSearchPreview>;Tools
ApplyPatch
Defines the OpenAI Apply Patch tool that allows the model to apply diffs by creating, deleting, or updating files. This local tool runs in your environment and requires a handler to execute file operations.
When to use
Use when you want an OpenAI model to request structured file edits as create, delete, or update operations that your application executes through a local handler.
Signature
declare const ApplyPatch: <Mode extends FailureMode | undefined = undefined>(args: { readonly failureMode?: Mode;}) => ProviderDefined< "openai.apply_patch", "OpenAiApplyPatch", { readonly args: Void; readonly failure: Never; readonly failureMode: Mode extends undefined ? "error" : Mode; readonly parameters: Struct; readonly success: Struct; }, true>;CodeInterpreter
Defines the OpenAI Code Interpreter tool that allows the model to execute Python code in a sandboxed environment.
When to use
Use to enable OpenAI-hosted Python execution for a model response.
Details
The tool is configured with a container argument. Successful tool calls expose outputs, which may contain logs or generated images, or null when no outputs are available.
Signature
declare const CodeInterpreter: <Mode extends FailureMode | undefined = undefined>(args: { readonly container: string | { readonly file_ids?: readonly Array<string>; readonly memory_limit?: "1g" | "4g" | "16g" | "64g" | null; readonly network_policy?: ReadonlySide<{ readonly type: Literal<"disabled">; }, "Encoded"> | { readonly allowed_domains: readonly Array<string>; readonly domain_secrets?: readonly Array<ReadonlySide<{ readonly domain: String; readonly name: String; readonly value: String; }, "Encoded">>; readonly type: "allowlist"; }; readonly type: "auto"; };}) => ProviderDefined<"openai.code_interpreter", "OpenAiCodeInterpreter", { readonly args: Struct; readonly failure: Never; readonly failureMode: Mode extends undefined ? "error" : Mode; readonly parameters: Struct; readonly success: Struct;}, false>FileSearch
Defines the OpenAI File Search tool that enables the model to search through uploaded files and vector stores.
When to use
Use to let an OpenAI model search uploaded files through one or more vector stores.
Details
The tool requires vector_store_ids and accepts optional filters, max_num_results, and ranking_options. Successful tool calls expose the search status, generated queries, and optional results.
Signature
declare const FileSearch: <Mode extends FailureMode | undefined = undefined>(args: { readonly filters?: ReadonlySide<{ readonly key: String; readonly type: Literals<readonly ["eq", "ne", "gt", "gte", "lt", "lte", "in", "nin"]>; readonly value: Union<readonly [String, Number, Boolean, $Array<Union<readonly [String, Number]>>]>; }, "Encoded"> | ReadonlySide<{ readonly filters: $Array<Union<readonly [Struct<{ readonly key: String; readonly type: Literals<...>; readonly value: Union<...>; }>, Unknown]>>; readonly type: Literals<readonly ["and", "or"]>; }, "Encoded"> | null; readonly max_num_results?: number; readonly ranking_options?: { readonly hybrid_search?: ReadonlySide<{ readonly embedding_weight: Number; readonly text_weight: Number; }, "Encoded">; readonly ranker?: "auto" | "default-2024-11-15"; readonly score_threshold?: number; }; readonly vector_store_ids: readonly Array<string>;}) => ProviderDefined<"openai.file_search", "OpenAiFileSearch", { readonly args: Struct; readonly failure: Never; readonly failureMode: Mode extends undefined ? "error" : Mode; readonly parameters: Void; readonly success: Struct;}, false>ImageGeneration
Defines the OpenAI Image Generation tool that enables the model to generate images using the GPT image models.
When to use
Use to enable OpenAI provider-defined image generation through a language model response.
Details
The tool configures the image_generation provider tool, including model, size, quality, output format, moderation, background, input-image options, and partial image settings. Successful tool calls expose result as base64 image data or null.
Signature
declare const ImageGeneration: <Mode extends FailureMode | undefined = undefined>(args: { readonly background?: "auto" | "transparent" | "opaque"; readonly input_fidelity?: "low" | "high" | null; readonly input_image_mask?: { readonly file_id?: string; readonly image_url?: string; }; readonly model?: string; readonly moderation?: "low" | "auto"; readonly output_compression?: number; readonly output_format?: "png" | "webp" | "jpeg"; readonly partial_images?: number; readonly quality?: "low" | "medium" | "high" | "auto"; readonly size?: string;}) => ProviderDefined< "openai.image_generation", "OpenAiImageGeneration", { readonly args: Struct; readonly failure: Never; readonly failureMode: Mode extends undefined ? "error" : Mode; readonly parameters: Void; readonly success: Struct; }, false>;LocalShell
Defines the OpenAI Local Shell tool that enables the model to run a command with a local shell. This local tool runs in your environment and requires a handler to execute commands.
When to use
Use to let an OpenAI model request local shell commands that your application executes through a handler.
Details
The tool exposes a provider-defined local_shell call. It is marked as handler-required, so applications must provide the command execution policy and implementation.
Signature
declare const LocalShell: <Mode extends FailureMode | undefined = undefined>(args: { readonly failureMode?: Mode;}) => ProviderDefined< "openai.local_shell", "OpenAiLocalShell", { readonly args: Void; readonly failure: Never; readonly failureMode: Mode extends undefined ? "error" : Mode; readonly parameters: Struct; readonly success: Struct; }, true>;Defines the OpenAI MCP tool that gives the model access to additional tools via remote Model Context Protocol (MCP) servers.
When to use
Use to let an OpenAI model call tools exposed by a remote MCP server.
Details
The tool accepts MCP server configuration such as allowed tools, authorization, connector id, approval requirements, server metadata, and server URL. Tool call results include the called tool name, arguments, output, error, and server label.
Gotchas
This schema leaves both server_url and connector_id optional, but OpenAI may require a server URL or connector id for a usable MCP tool configuration.
Signature
declare const Mcp: <Mode extends FailureMode | undefined = undefined>(args: { readonly allowed_tools?: readonly Array<string> | { readonly read_only?: boolean; readonly tool_names?: readonly Array<string>; } | null; readonly authorization?: string; readonly connector_id?: "connector_dropbox" | "connector_gmail" | "connector_googlecalendar" | "connector_googledrive" | "connector_microsoftteams" | "connector_outlookcalendar" | "connector_outlookemail" | "connector_sharepoint"; readonly require_approval?: "always" | "never" | { readonly always?: { readonly read_only?: boolean; readonly tool_names?: readonly Array<string>; }; readonly never?: { readonly read_only?: boolean; readonly tool_names?: readonly Array<string>; }; } | null; readonly server_description?: string; readonly server_label: string; readonly server_url?: string;}) => ProviderDefined<"openai.mcp", "OpenAiMcp", { readonly args: Struct; readonly failure: Never; readonly failureMode: Mode extends undefined ? "error" : Mode; readonly parameters: Unknown; readonly success: Struct;}, false>Defines the OpenAI shell tool for model-requested command execution.
When to use
Use to let an OpenAI model request shell commands that your application executes through a handler.
Details
The tool exposes a provider-defined shell call. It is marked as handler-required, so applications must provide the command execution policy and implementation.
Signature
declare const Shell: <Mode extends FailureMode | undefined = undefined>(args: { readonly failureMode?: Mode;}) => ProviderDefined< "openai.shell", "OpenAiShell", { readonly args: Void; readonly failure: Never; readonly failureMode: Mode extends undefined ? "error" : Mode; readonly parameters: Struct; readonly success: Struct; }, true>;Defines the OpenAI Web Search tool that enables the model to search the web for information.
When to use
Use to enable OpenAI provider-defined web search for a model response.
Details
The tool accepts optional filters, user location, and search context size. Successful calls expose the performed search action and status.
See
WebSearchPreviewfor the preview web search provider tool
Signature
declare const WebSearch: <Mode extends FailureMode | undefined = undefined>(args: { readonly filters?: { readonly allowed_domains?: readonly Array<string> | null; } | null; readonly search_context_size?: "low" | "medium" | "high"; readonly user_location?: { readonly city?: string | null; readonly country?: string | null; readonly region?: string | null; readonly timezone?: string | null; readonly type?: "approximate"; } | null;}) => ProviderDefined<"openai.web_search", "OpenAiWebSearch", { readonly args: Struct; readonly failure: Never; readonly failureMode: Mode extends undefined ? "error" : Mode; readonly parameters: Struct; readonly success: Struct;}, false>WebSearchPreview
Defines the OpenAI preview Web Search tool for model responses.
When to use
Use to enable the preview OpenAI web search provider tool.
Details
The preview tool accepts optional user location and search context size, then exposes the performed search action and status in successful calls.
See
WebSearchfor the stable web search provider tool
Signature
declare const WebSearchPreview: <Mode extends FailureMode | undefined = undefined>(args: { readonly search_context_size?: "low" | "medium" | "high"; readonly user_location?: { readonly city?: string | null; readonly country?: string | null; readonly region?: string | null; readonly timezone?: string | null; readonly type: "approximate"; } | null;}) => ProviderDefined< "openai.web_search_preview", "OpenAiWebSearchPreview", { readonly args: Struct; readonly failure: Never; readonly failureMode: Mode extends undefined ? "error" : Mode; readonly parameters: Void; readonly success: Struct; }, false>;
Union of all OpenAI provider-defined tools.