@effect/ai-openai 4.0.0-beta.7 → 4.0.0-beta.71

package/dist/OpenAiTool.d.ts

@@ -1,29 +1,52 @@
 /**
- * OpenAI provider-defined tools for use with the LanguageModel.
+ * OpenAI provider-defined tools for Effect AI language model requests.
  *
- * Provides tools that are natively supported by OpenAI's API, including
- * code interpreter, file search, and web search functionality.
+ * This module exposes typed descriptors for OpenAI tools such as code
+ * interpreter, file search, image generation, MCP, web search, and shell-like
+ * local tools. Each descriptor captures the OpenAI provider name, user-facing
+ * configuration arguments, provider call parameters, success output schema, and
+ * whether the tool call needs an application-provided handler.
  *
- * @since 1.0.0
+ * **Mental model**
+ *
+ * Provider-defined tools are not implementations of the capability themselves.
+ * They are schemas and metadata that tell the language model provider which
+ * tool to make available and tell Effect AI how to decode any tool calls or
+ * tool results that come back.
+ *
+ * **Common tasks**
+ *
+ * Use hosted or provider-routed tools such as {@link CodeInterpreter},
+ * {@link FileSearch}, {@link ImageGeneration}, {@link Mcp}, {@link WebSearch},
+ * and {@link WebSearchPreview} to opt into OpenAI-managed capabilities. Use
+ * handler-required tools such as {@link ApplyPatch}, {@link Shell}, and
+ * {@link LocalShell} only when your application is prepared to execute the
+ * requested local operation and enforce its own safety policy.
+ *
+ * @since 4.0.0
  */
 import * as Schema from "effect/Schema";
 import * as Tool from "effect/unstable/ai/Tool";
 /**
  * Union of all OpenAI provider-defined tools.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export 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>;
 /**
- * OpenAI Apply Patch tool.
+ * 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**
  *
- * Allows the model to apply diffs by creating, deleting, or updating files.
- * This is a local tool that runs in your environment and requires a handler
- * to execute file operations.
+ * 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.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const ApplyPatch: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly failureMode?: Mode | undefined;
@@ -52,16 +75,26 @@ export declare const ApplyPatch: <Mode extends Tool.FailureMode | undefined = un
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * OpenAI Code Interpreter tool.
+ * OpenAI Code Interpreter tool that allows the model to execute Python code in
+ * a sandboxed environment.
  *
- * 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.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const CodeInterpreter: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly container: string | {
         readonly type: "auto";
+        readonly file_ids?: readonly string[];
         readonly memory_limit?: "1g" | "4g" | "16g" | "64g" | null;
         readonly network_policy?: {
             readonly type: "disabled";
@@ -69,12 +102,11 @@ export declare const CodeInterpreter: <Mode extends Tool.FailureMode | undefined
             readonly type: "allowlist";
             readonly allowed_domains: readonly string[];
             readonly domain_secrets?: readonly {
-                readonly value: string;
-                readonly name: string;
                 readonly domain: string;
+                readonly name: string;
+                readonly value: string;
             }[];
         };
-        readonly file_ids?: readonly string[];
     };
 }) => Tool.ProviderDefined<"openai.code_interpreter", "OpenAiCodeInterpreter", {
     readonly args: Schema.Struct<{
@@ -112,19 +144,29 @@ export declare const CodeInterpreter: <Mode extends Tool.FailureMode | undefined
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * OpenAI File Search tool.
+ * 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**
  *
- * Enables the model to search through uploaded files and vector stores.
+ * 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`.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const FileSearch: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly vector_store_ids: readonly string[];
     readonly filters?: {
-        readonly value: string | number | boolean | readonly (string | number)[];
-        readonly type: "eq" | "ne" | "gt" | "gte" | "lt" | "lte";
+        readonly type: "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "nin";
         readonly key: string;
+        readonly value: string | number | boolean | readonly (string | number)[];
     } | {
         readonly type: "and" | "or";
         readonly filters: readonly unknown[];
@@ -141,13 +183,13 @@ export declare const FileSearch: <Mode extends Tool.FailureMode | undefined = un
 }) => Tool.ProviderDefined<"openai.file_search", "OpenAiFileSearch", {
     readonly args: Schema.Struct<{
         readonly filters: Schema.optionalKey<Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
-            readonly type: Schema.Literals<readonly ["eq", "ne", "gt", "gte", "lt", "lte"]>;
+            readonly type: Schema.Literals<readonly ["eq", "ne", "gt", "gte", "lt", "lte", "in", "nin"]>;
             readonly key: Schema.String;
             readonly value: Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>]>;
         }>, Schema.Struct<{
             readonly type: Schema.Literals<readonly ["and", "or"]>;
             readonly filters: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
-                readonly type: Schema.Literals<readonly ["eq", "ne", "gt", "gte", "lt", "lte"]>;
+                readonly type: Schema.Literals<readonly ["eq", "ne", "gt", "gte", "lt", "lte", "in", "nin"]>;
                 readonly key: Schema.String;
                 readonly value: Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>]>;
             }>, Schema.Unknown]>>;
@@ -179,27 +221,38 @@ export declare const FileSearch: <Mode extends Tool.FailureMode | undefined = un
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * OpenAI Image Generation tool.
+ * 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.
  *
- * Enables the model to generate images using the GPT image models.
+ * **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`.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const ImageGeneration: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
-    readonly model?: string;
-    readonly size?: "auto" | "1024x1024" | "1024x1536" | "1536x1024";
-    readonly quality?: "auto" | "low" | "high" | "medium";
     readonly background?: "auto" | "transparent" | "opaque";
-    readonly output_format?: "png" | "webp" | "jpeg";
-    readonly output_compression?: number;
-    readonly partial_images?: number;
-    readonly moderation?: "auto" | "low";
     readonly input_fidelity?: "low" | "high" | null;
     readonly input_image_mask?: {
-        readonly file_id?: string;
         readonly image_url?: string;
+        readonly file_id?: string;
     };
+    readonly model?: string;
+    readonly moderation?: "auto" | "low";
+    readonly output_compression?: number;
+    readonly output_format?: "png" | "webp" | "jpeg";
+    readonly partial_images?: number;
+    readonly quality?: "auto" | "low" | "high" | "medium";
+    readonly size?: string;
 }) => Tool.ProviderDefined<"openai.image_generation", "OpenAiImageGeneration", {
     readonly args: Schema.Struct<{
         readonly background: Schema.optionalKey<Schema.Literals<readonly ["transparent", "opaque", "auto"]>>;
@@ -214,7 +267,7 @@ export declare const ImageGeneration: <Mode extends Tool.FailureMode | undefined
         readonly output_format: Schema.optionalKey<Schema.Literals<readonly ["png", "webp", "jpeg"]>>;
         readonly partial_images: Schema.optionalKey<Schema.Number>;
         readonly quality: Schema.optionalKey<Schema.Literals<readonly ["low", "medium", "high", "auto"]>>;
-        readonly size: Schema.optionalKey<Schema.Literals<readonly ["1024x1024", "1024x1536", "1536x1024", "auto"]>>;
+        readonly size: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Literals<readonly ["1024x1024", "1024x1536", "1536x1024", "auto"]>]>>;
     }>;
     readonly parameters: Schema.Void;
     readonly success: Schema.Struct<{
@@ -224,13 +277,23 @@ export declare const ImageGeneration: <Mode extends Tool.FailureMode | undefined
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * OpenAI Local Shell tool.
+ * 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.
  *
- * Enables the model to run a command with a local shell. This is a local tool
- * that runs in your environment and requires a handler to execute commands.
+ * **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.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const LocalShell: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly failureMode?: Mode | undefined;
@@ -253,13 +316,27 @@ export declare const LocalShell: <Mode extends Tool.FailureMode | undefined = un
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * OpenAI MCP tool.
+ * 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**
  *
- * Gives the model access to additional tools via remote Model Context Protocol
- * (MCP) servers
+ * 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.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const Mcp: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly server_label: string;
@@ -267,10 +344,8 @@ export declare const Mcp: <Mode extends Tool.FailureMode | undefined = undefined
         readonly tool_names?: readonly string[];
         readonly read_only?: boolean;
     } | null;
-    readonly server_url?: string;
-    readonly connector_id?: "connector_dropbox" | "connector_gmail" | "connector_googlecalendar" | "connector_googledrive" | "connector_microsoftteams" | "connector_outlookcalendar" | "connector_outlookemail" | "connector_sharepoint";
     readonly authorization?: string;
-    readonly server_description?: 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 tool_names?: readonly string[];
@@ -281,6 +356,8 @@ export declare const Mcp: <Mode extends Tool.FailureMode | undefined = undefined
             readonly read_only?: boolean;
         };
     } | null;
+    readonly server_description?: string;
+    readonly server_url?: string;
 }) => Tool.ProviderDefined<"openai.mcp", "OpenAiMcp", {
     readonly args: Schema.Struct<{
         readonly allowed_tools: Schema.optionalKey<Schema.Union<readonly [Schema.Union<readonly [Schema.$Array<Schema.String>, Schema.Struct<{
@@ -303,7 +380,7 @@ export declare const Mcp: <Mode extends Tool.FailureMode | undefined = undefined
         readonly server_label: Schema.String;
         readonly server_url: Schema.optionalKey<Schema.String>;
     }>;
-    readonly parameters: Schema.Void;
+    readonly parameters: Schema.Unknown;
     readonly success: Schema.Struct<{
         readonly type: Schema.Literal<"mcp_call">;
         readonly name: Schema.String;
@@ -316,14 +393,12 @@ export declare const Mcp: <Mode extends Tool.FailureMode | undefined = undefined
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * OpenAI Function Shell tool.
- *
- * Enables the model to execute one or more shell commands in a managed
- * environment. This is a local tool that runs in your environment and requires
- * a handler to execute commands.
+ * OpenAI Function Shell tool that enables the model to execute one or more shell
+ * commands in a managed environment. This local tool runs in your environment
+ * and requires a handler to execute commands.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const Shell: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly failureMode?: Mode | undefined;
@@ -346,20 +421,34 @@ export declare const Shell: <Mode extends Tool.FailureMode | undefined = undefin
                 readonly type: Schema.Literal<"exit">;
                 readonly exit_code: Schema.Number;
             }>]>;
+            readonly created_by: Schema.optionalKey<Schema.String>;
         }>>;
     }>;
     readonly failure: Schema.Never;
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * OpenAI Web Search tool.
+ * 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.
  *
- * Enables the model to search the web for information.
+ * **Details**
+ *
+ * The tool accepts optional filters, user location, and search context size.
+ * Successful calls expose the performed search action and status.
+ *
+ * @see {@link WebSearchPreview} for the preview web search provider tool
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const WebSearch: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
+    readonly filters?: {
+        readonly allowed_domains?: readonly string[] | null;
+    } | null;
     readonly user_location?: {
         readonly type?: "approximate";
         readonly country?: string | null;
@@ -368,9 +457,6 @@ export declare const WebSearch: <Mode extends Tool.FailureMode | undefined = und
         readonly timezone?: string | null;
     } | null;
     readonly search_context_size?: "low" | "high" | "medium";
-    readonly filters?: {
-        readonly allowed_domains?: readonly string[] | null;
-    } | null;
 }) => Tool.ProviderDefined<"openai.web_search", "OpenAiWebSearch", {
     readonly args: Schema.Struct<{
         readonly filters: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
@@ -426,12 +512,21 @@ export declare const WebSearch: <Mode extends Tool.FailureMode | undefined = und
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * OpenAI Web Search Preview tool.
+ * 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.
  *
- * Preview version of the web search tool with additional features.
+ * @see {@link WebSearch} for the stable web search provider tool
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const WebSearchPreview: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly user_location?: {

package/dist/OpenAiTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OpenAiTool.d.ts","sourceRoot":"","sources":["../src/OpenAiTool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,yBAAyB,CAAA;AAG/C;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAClB,UAAU,CAAC,OAAO,UAAU,CAAC,GAC7B,UAAU,CAAC,OAAO,eAAe,CAAC,GAClC,UAAU,CAAC,OAAO,UAAU,CAAC,GAC7B,UAAU,CAAC,OAAO,KAAK,CAAC,GACxB,UAAU,CAAC,OAAO,eAAe,CAAC,GAClC,UAAU,CAAC,OAAO,UAAU,CAAC,GAC7B,UAAU,CAAC,OAAO,GAAG,CAAC,GACtB,UAAU,CAAC,OAAO,SAAS,CAAC,GAC5B,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAEvC;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;QAarB,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAc1B,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAerB,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAmB1B,CAAA;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;QAWrB,CAAA;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAqBd,CAAA;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;QAWhB,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAgBpB,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAY3B,CAAA"}
+{"version":3,"file":"OpenAiTool.d.ts","sourceRoot":"","sources":["../src/OpenAiTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,yBAAyB,CAAA;AAG/C;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAClB,UAAU,CAAC,OAAO,UAAU,CAAC,GAC7B,UAAU,CAAC,OAAO,eAAe,CAAC,GAClC,UAAU,CAAC,OAAO,UAAU,CAAC,GAC7B,UAAU,CAAC,OAAO,KAAK,CAAC,GACxB,UAAU,CAAC,OAAO,eAAe,CAAC,GAClC,UAAU,CAAC,OAAO,UAAU,CAAC,GAC7B,UAAU,CAAC,OAAO,GAAG,CAAC,GACtB,UAAU,CAAC,OAAO,SAAS,CAAC,GAC5B,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAEvC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;QAarB,CAAA;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAc1B,CAAA;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAerB,CAAA;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAmB1B,CAAA;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;QAWrB,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAsBd,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;QAWhB,CAAA;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAgBpB,CAAA;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAY3B,CAAA"}

package/dist/OpenAiTool.js

@@ -1,23 +1,46 @@
 /**
- * OpenAI provider-defined tools for use with the LanguageModel.
+ * OpenAI provider-defined tools for Effect AI language model requests.
  *
- * Provides tools that are natively supported by OpenAI's API, including
- * code interpreter, file search, and web search functionality.
+ * This module exposes typed descriptors for OpenAI tools such as code
+ * interpreter, file search, image generation, MCP, web search, and shell-like
+ * local tools. Each descriptor captures the OpenAI provider name, user-facing
+ * configuration arguments, provider call parameters, success output schema, and
+ * whether the tool call needs an application-provided handler.
  *
- * @since 1.0.0
+ * **Mental model**
+ *
+ * Provider-defined tools are not implementations of the capability themselves.
+ * They are schemas and metadata that tell the language model provider which
+ * tool to make available and tell Effect AI how to decode any tool calls or
+ * tool results that come back.
+ *
+ * **Common tasks**
+ *
+ * Use hosted or provider-routed tools such as {@link CodeInterpreter},
+ * {@link FileSearch}, {@link ImageGeneration}, {@link Mcp}, {@link WebSearch},
+ * and {@link WebSearchPreview} to opt into OpenAI-managed capabilities. Use
+ * handler-required tools such as {@link ApplyPatch}, {@link Shell}, and
+ * {@link LocalShell} only when your application is prepared to execute the
+ * requested local operation and enforce its own safety policy.
+ *
+ * @since 4.0.0
  */
 import * as Schema from "effect/Schema";
 import * as Tool from "effect/unstable/ai/Tool";
 import * as Generated from "./Generated.js";
 /**
- * OpenAI Apply Patch tool.
+ * 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.
  *
- * Allows the model to apply diffs by creating, deleting, or updating files.
- * This is a local tool that 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.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const ApplyPatch = /*#__PURE__*/Tool.providerDefined({
   id: "openai.apply_patch",
@@ -34,12 +57,21 @@ export const ApplyPatch = /*#__PURE__*/Tool.providerDefined({
   })
 });
 /**
- * OpenAI Code Interpreter tool.
+ * 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**
  *
- * Allows the model to execute Python code in a sandboxed environment.
+ * 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.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const CodeInterpreter = /*#__PURE__*/Tool.providerDefined({
   id: "openai.code_interpreter",
@@ -57,12 +89,22 @@ export const CodeInterpreter = /*#__PURE__*/Tool.providerDefined({
   })
 });
 /**
- * OpenAI File Search tool.
+ * OpenAI File Search tool that enables the model to search through uploaded
+ * files and vector stores.
  *
- * 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`.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const FileSearch = /*#__PURE__*/Tool.providerDefined({
   id: "openai.file_search",
@@ -81,12 +123,23 @@ export const FileSearch = /*#__PURE__*/Tool.providerDefined({
   })
 });
 /**
- * OpenAI Image Generation tool.
+ * OpenAI Image Generation tool that enables the model to generate images using
+ * the GPT image models.
+ *
+ * **When to use**
  *
- * Enables the model to generate images using the GPT image models.
+ * 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`.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const ImageGeneration = /*#__PURE__*/Tool.providerDefined({
   id: "openai.image_generation",
@@ -109,13 +162,23 @@ export const ImageGeneration = /*#__PURE__*/Tool.providerDefined({
   })
 });
 /**
- * OpenAI Local Shell tool.
+ * 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.
  *
- * Enables the model to run a command with a local shell. This is a local tool
- * that runs in your environment and requires a handler to execute commands.
+ * **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.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const LocalShell = /*#__PURE__*/Tool.providerDefined({
   id: "openai.local_shell",
@@ -130,13 +193,27 @@ export const LocalShell = /*#__PURE__*/Tool.providerDefined({
   })
 });
 /**
- * OpenAI MCP tool.
+ * 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**
  *
- * Gives the model access to additional tools via remote Model Context Protocol
- * (MCP) servers
+ * 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.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const Mcp = /*#__PURE__*/Tool.providerDefined({
   id: "openai.mcp",
@@ -151,6 +228,7 @@ export const Mcp = /*#__PURE__*/Tool.providerDefined({
     server_label: Generated.MCPTool.fields.server_label,
     server_url: Generated.MCPTool.fields.server_url
   }),
+  parameters: Schema.Unknown,
   success: /*#__PURE__*/Schema.Struct({
     type: Generated.MCPToolCall.fields.type,
     name: Generated.MCPToolCall.fields.name,
@@ -161,14 +239,12 @@ export const Mcp = /*#__PURE__*/Tool.providerDefined({
   })
 });
 /**
- * OpenAI Function Shell tool.
+ * OpenAI Function Shell tool that enables the model to execute one or more shell
+ * commands in a managed environment. This local tool runs in your environment
+ * and requires a handler to execute commands.
  *
- * Enables the model to execute one or more shell commands in a managed
- * environment. This is a local tool that runs in your environment and requires
- * a handler to execute commands.
- *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const Shell = /*#__PURE__*/Tool.providerDefined({
   id: "openai.shell",
@@ -179,16 +255,26 @@ export const Shell = /*#__PURE__*/Tool.providerDefined({
     action: Generated.FunctionShellCall.fields.action
   }),
   success: /*#__PURE__*/Schema.Struct({
-    output: Generated.FunctionShellCallOutputItemParam.fields.output
+    output: Generated.FunctionShellCallOutput.fields.output
   })
 });
 /**
- * OpenAI Web Search tool.
+ * OpenAI Web Search tool that enables the model to search the web for
+ * information.
+ *
+ * **When to use**
  *
- * Enables the model to search the web for information.
+ * 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 {@link WebSearchPreview} for the preview web search provider tool
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const WebSearch = /*#__PURE__*/Tool.providerDefined({
   id: "openai.web_search",
@@ -208,12 +294,21 @@ export const WebSearch = /*#__PURE__*/Tool.providerDefined({
   })
 });
 /**
- * OpenAI Web Search Preview tool.
+ * 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.
  *
- * Preview version of the web search tool with additional features.
+ * @see {@link WebSearch} for the stable web search provider tool
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const WebSearchPreview = /*#__PURE__*/Tool.providerDefined({
   id: "openai.web_search_preview",