@effect/ai-openai 4.0.0-beta.9 → 4.0.0-beta.91

package/dist/OpenAiTool.d.ts

@@ -1,29 +1,34 @@
 /**
- * OpenAI provider-defined tools for use with the LanguageModel.
+ * 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.
  *
- * Provides tools that are natively supported by OpenAI's API, including
- * code interpreter, file search, and web search functionality.
- *
- * @since 1.0.0
+ * @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.
+ * 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**
  *
- * 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,27 +57,36 @@ export declare const ApplyPatch: <Mode extends Tool.FailureMode | undefined = un
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * OpenAI Code Interpreter tool.
+ * Defines the OpenAI Code Interpreter tool that allows the model to execute Python code in
+ * a sandboxed environment.
+ *
+ * **When to use**
  *
- * Allows the model to execute Python code in a sandboxed environment.
+ * 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 memory_limit?: "1g" | "4g" | "16g" | "64g" | null;
-        readonly network_policy?: {
-            readonly type: "disabled";
-        } | {
+        readonly network_policy?: Schema.Struct.ReadonlySide<{
+            readonly type: Schema.Literal<"disabled">;
+        }, "Encoded"> | {
             readonly type: "allowlist";
             readonly allowed_domains: readonly string[];
-            readonly domain_secrets?: readonly {
-                readonly value: string;
-                readonly name: string;
-                readonly domain: string;
-            }[];
+            readonly domain_secrets?: readonly Schema.Struct.ReadonlySide<{
+                readonly domain: Schema.String;
+                readonly name: Schema.String;
+                readonly value: Schema.String;
+            }, "Encoded">[];
         };
         readonly file_ids?: readonly string[];
     };
@@ -112,42 +126,56 @@ export declare const CodeInterpreter: <Mode extends Tool.FailureMode | undefined
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * OpenAI File Search tool.
+ * Defines the OpenAI File Search tool that enables the model to search through uploaded
+ * files and vector stores.
+ *
+ * **When to use**
  *
- * Enables the model to search through uploaded files and vector stores.
+ * 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 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 key: string;
-    } | {
-        readonly type: "and" | "or";
-        readonly filters: readonly unknown[];
-    } | null;
+    readonly filters?: Schema.Struct.ReadonlySide<{
+        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]>>]>;
+    }, "Encoded"> | Schema.Struct.ReadonlySide<{
+        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", "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]>>;
+    }, "Encoded"> | null;
     readonly max_num_results?: number;
     readonly ranking_options?: {
         readonly ranker?: "auto" | "default-2024-11-15";
         readonly score_threshold?: number;
-        readonly hybrid_search?: {
-            readonly embedding_weight: number;
-            readonly text_weight: number;
-        };
+        readonly hybrid_search?: Schema.Struct.ReadonlySide<{
+            readonly embedding_weight: Schema.Number;
+            readonly text_weight: Schema.Number;
+        }, "Encoded">;
     };
 }) => 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,16 +207,27 @@ export declare const FileSearch: <Mode extends Tool.FailureMode | undefined = un
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * OpenAI Image Generation tool.
+ * 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**
  *
- * Enables the model to generate images using the GPT image models.
+ * 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 size?: string;
     readonly quality?: "auto" | "low" | "high" | "medium";
     readonly background?: "auto" | "transparent" | "opaque";
     readonly output_format?: "png" | "webp" | "jpeg";
@@ -214,7 +253,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 +263,23 @@ export declare const ImageGeneration: <Mode extends Tool.FailureMode | undefined
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * OpenAI Local Shell tool.
+ * 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.
  *
- * 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.
+ * **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.
  *
- * @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 +302,27 @@ export declare const LocalShell: <Mode extends Tool.FailureMode | undefined = un
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * OpenAI MCP tool.
+ * 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.
  *
- * Gives the model access to additional tools via remote Model Context Protocol
- * (MCP) servers
+ * **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.
  *
- * @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;
@@ -303,7 +366,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 +379,21 @@ export declare const Mcp: <Mode extends Tool.FailureMode | undefined = undefined
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * OpenAI Function Shell tool.
+ * 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.
  *
- * 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.
+ * **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.
  *
- * @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 +416,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.
+ * 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.
  *
- * Enables the model to search the web for information.
+ * @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 +452,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 +507,21 @@ export declare const WebSearch: <Mode extends Tool.FailureMode | undefined = und
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * OpenAI Web Search Preview tool.
+ * 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.
  *
- * 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;;;;;;;;GAQG;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;;;;;;;;;;;;;;;;GAgBG;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,28 @@
 /**
- * OpenAI provider-defined tools for use with the LanguageModel.
+ * 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.
  *
- * Provides tools that are natively supported by OpenAI's API, including
- * code interpreter, file search, and web search functionality.
- *
- * @since 1.0.0
+ * @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.
+ * 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**
  *
- * 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 const ApplyPatch = /*#__PURE__*/Tool.providerDefined({
   id: "openai.apply_patch",
@@ -34,12 +39,21 @@ export const ApplyPatch = /*#__PURE__*/Tool.providerDefined({
   })
 });
 /**
- * OpenAI Code Interpreter tool.
+ * 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.
  *
- * Allows the model to execute Python code in a sandboxed environment.
+ * **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 const CodeInterpreter = /*#__PURE__*/Tool.providerDefined({
   id: "openai.code_interpreter",
@@ -57,12 +71,22 @@ export const CodeInterpreter = /*#__PURE__*/Tool.providerDefined({
   })
 });
 /**
- * OpenAI File Search tool.
+ * 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**
  *
- * 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 const FileSearch = /*#__PURE__*/Tool.providerDefined({
   id: "openai.file_search",
@@ -81,12 +105,23 @@ export const FileSearch = /*#__PURE__*/Tool.providerDefined({
   })
 });
 /**
- * OpenAI Image Generation tool.
+ * Defines the OpenAI Image Generation tool that enables the model to generate images using
+ * the GPT image models.
  *
- * 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`.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const ImageGeneration = /*#__PURE__*/Tool.providerDefined({
   id: "openai.image_generation",
@@ -109,13 +144,23 @@ export const ImageGeneration = /*#__PURE__*/Tool.providerDefined({
   })
 });
 /**
- * OpenAI Local Shell tool.
+ * 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**
  *
- * 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.
+ * 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.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const LocalShell = /*#__PURE__*/Tool.providerDefined({
   id: "openai.local_shell",
@@ -130,13 +175,27 @@ export const LocalShell = /*#__PURE__*/Tool.providerDefined({
   })
 });
 /**
- * OpenAI MCP tool.
+ * Defines the OpenAI MCP tool that gives the model access to additional tools via remote
+ * Model Context Protocol (MCP) servers.
+ *
+ * **When to use**
  *
- * Gives the model access to additional tools via remote Model Context Protocol
- * (MCP) servers
+ * 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.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const Mcp = /*#__PURE__*/Tool.providerDefined({
   id: "openai.mcp",
@@ -151,6 +210,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 +221,21 @@ export const Mcp = /*#__PURE__*/Tool.providerDefined({
   })
 });
 /**
- * OpenAI Function Shell tool.
+ * Defines the OpenAI shell tool for model-requested command execution.
  *
- * 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.
+ * **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.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export const Shell = /*#__PURE__*/Tool.providerDefined({
   id: "openai.shell",
@@ -179,16 +246,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.
+ * Defines the 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 +285,21 @@ export const WebSearch = /*#__PURE__*/Tool.providerDefined({
   })
 });
 /**
- * OpenAI Web Search Preview tool.
+ * 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.
  *
- * 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",