effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/unstable/ai/Tool.d.ts

@@ -7,7 +7,8 @@
  * AI models to perform actions like searching databases, calling APIs, or
  * executing code within your application context.
  *
- * @example
+ * **Example** (Defining a calculator tool)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
@@ -24,7 +25,7 @@
  * })
  * ```
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Context from "../../Context.ts";
 import type * as Effect from "../../Effect.ts";
@@ -36,33 +37,55 @@ import type * as AiError from "./AiError.ts";
 import type { CodecTransformer } from "./LanguageModel.ts";
 import type * as Prompt from "./Prompt.ts";
 /**
- * @since 1.0.0
- * @category type ids
+ * Runtime type identifier carried by Effect AI tool values.
+ *
+ * The tool type guards use this marker, together with more specific markers,
+ * to distinguish user-defined, provider-defined, and dynamic tools.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export declare const TypeId: TypeId;
 /**
- * @since 1.0.0
- * @category type ids
+ * Type-level representation of the Effect AI tool runtime type identifier.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export type TypeId = "~effect/ai/Tool";
 /**
- * @since 1.0.0
- * @category type ids
+ * Runtime type identifier carried by provider-defined tools.
+ *
+ * `isProviderDefined` uses this marker to distinguish tools that are built into
+ * an AI provider from user-defined and dynamic tools.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export declare const ProviderDefinedTypeId: ProviderDefinedTypeId;
 /**
- * @since 1.0.0
- * @category type ids
+ * Type-level representation of the provider-defined tool runtime type
+ * identifier.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export type ProviderDefinedTypeId = "~effect/ai/Tool/ProviderDefined";
 /**
- * @since 1.0.0
- * @category type ids
+ * Runtime type identifier carried by dynamic tools.
+ *
+ * `isDynamic` uses this marker to distinguish tools whose schema may be
+ * provided at runtime from user-defined and provider-defined tools.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export declare const DynamicTypeId: DynamicTypeId;
 /**
- * @since 1.0.0
- * @category type ids
+ * Type-level representation of the dynamic tool runtime type identifier.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export type DynamicTypeId = "~effect/ai/Tool/Dynamic";
 /**
@@ -75,16 +98,16 @@ export type DynamicTypeId = "~effect/ai/Tool/Dynamic";
  * If set to `"return"`, errors that occur during tool call handler execution
  * will be captured and returned as part of the tool call result.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type FailureMode = "error" | "return";
 /**
  * Context provided to the `needsApproval` function when dynamically
  * determining if a tool requires user approval.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface NeedsApprovalContext {
     /**
@@ -99,8 +122,8 @@ export interface NeedsApprovalContext {
 /**
  * Function type for dynamically determining if a tool requires approval.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type NeedsApprovalFunction<Params extends Schema.Top> = (params: Params["Type"], context: NeedsApprovalContext) => boolean | Effect.Effect<boolean>;
 /**
@@ -110,8 +133,8 @@ export type NeedsApprovalFunction<Params extends Schema.Top> = (params: Params["
  * - `boolean`: Static approval requirement
  * - `NeedsApprovalFunction`: Dynamic approval based on parameters/context
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type NeedsApproval<Params extends Schema.Top> = boolean | NeedsApprovalFunction<Params>;
 /**
@@ -121,7 +144,8 @@ export type NeedsApproval<Params extends Schema.Top> = boolean | NeedsApprovalFu
  * to extend their functionality beyond text generation. Each tool has a defined
  * schema for parameters, results, and failures.
  *
- * @example
+ * **Example** (Defining a weather lookup tool)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
@@ -141,8 +165,8 @@ export type NeedsApproval<Params extends Schema.Top> = boolean | NeedsApprovalFu
  * })
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Tool<out Name extends string, out Config extends {
     readonly parameters: Schema.Top;
@@ -259,7 +283,8 @@ export interface Tool<out Name extends string, out Config extends {
  * by your application. However, they can optionally require custom handlers
  * implemented in your application to process provider generated results.
  *
- * @example
+ * **Example** (Defining a provider-defined web search tool)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
@@ -282,8 +307,8 @@ export interface Tool<out Name extends string, out Config extends {
  * })
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ProviderDefined<out Identifier extends `${string}.${string}`, out Name extends string, out Config extends {
     readonly args: Schema.Top;
@@ -332,7 +357,8 @@ export interface ProviderDefined<out Identifier extends `${string}.${string}`, o
  * This enables scenarios such as MCP tools discovered at runtime, user-defined
  * functions loaded from external sources, or plugin systems.
  *
- * @example
+ * **Example** (Defining dynamic tools)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
@@ -358,8 +384,8 @@ export interface ProviderDefined<out Identifier extends `${string}.${string}`, o
  * })
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Dynamic<out Name extends string, out Config extends {
     readonly parameters: Schema.Top | JsonSchema.JsonSchema;
@@ -382,7 +408,8 @@ export interface Dynamic<out Name extends string, out Config extends {
 /**
  * Type guard to check if a value is a user-defined tool.
  *
- * @example
+ * **Example** (Checking for user-defined tools)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
@@ -417,14 +444,15 @@ export interface Dynamic<out Name extends string, out Config extends {
  * console.log(Tool.isUserDefined(ProviderDefinedTool)) // false
  * ```
  *
- * @since 1.0.0
  * @category guards
+ * @since 4.0.0
  */
 export declare const isUserDefined: (u: unknown) => u is Tool<string, any, any>;
 /**
  * Type guard to check if a value is a provider-defined tool.
  *
- * @example
+ * **Example** (Checking for provider-defined tools)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
@@ -455,18 +483,19 @@ export declare const isUserDefined: (u: unknown) => u is Tool<string, any, any>;
  *   })
  * })
  *
- * console.log(Tool.isUserDefined(UserDefinedTool)) // false
- * console.log(Tool.isUserDefined(ProviderDefinedTool)) // true
+ * console.log(Tool.isProviderDefined(UserDefinedTool)) // false
+ * console.log(Tool.isProviderDefined(ProviderDefinedTool)) // true
  * ```
  *
- * @since 1.0.0
  * @category guards
+ * @since 4.0.0
  */
 export declare const isProviderDefined: (u: unknown) => u is ProviderDefined<`${string}.${string}`, string, any>;
 /**
  * Type guard to check if a value is a dynamic tool.
  *
- * @example
+ * **Example** (Checking for dynamic tools)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
@@ -484,15 +513,15 @@ export declare const isProviderDefined: (u: unknown) => u is ProviderDefined<`${
  * console.log(Tool.isDynamic(UserDefinedTool)) // false
  * ```
  *
- * @since 1.0.0
  * @category guards
+ * @since 4.0.0
  */
 export declare const isDynamic: (u: unknown) => u is Dynamic<string, any>;
 /**
  * A type which represents any `Tool`.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export interface Any extends Tool<any, {
     readonly parameters: Schema.Top;
@@ -504,8 +533,8 @@ export interface Any extends Tool<any, {
 /**
  * A type which represents any provider-defined `Tool`.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export interface AnyProviderDefined extends ProviderDefined<any, any, {
     readonly args: Schema.Top;
@@ -518,8 +547,8 @@ export interface AnyProviderDefined extends ProviderDefined<any, any, {
 /**
  * A type which represents any dynamic `Tool`.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export interface AnyDynamic extends Dynamic<any, {
     readonly parameters: Schema.Top | JsonSchema.JsonSchema;
@@ -531,68 +560,68 @@ export interface AnyDynamic extends Dynamic<any, {
 /**
  * A utility type to extract the `Name` type from an `Tool`.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type Name<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Name : never;
 /**
  * A utility type to extract the type of the tool call parameters.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type Parameters<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["parameters"]["Type"] : never;
 /**
  * A utility type to extract the encoded type of the tool call parameters.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type ParametersEncoded<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["parameters"]["Encoded"] : never;
 /**
  * A utility type to extract the schema for the parameters which an `Tool`
  * must be called with.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type ParametersSchema<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["parameters"] : never;
 /**
  * A utility type to extract the type of the tool call result when it succeeds.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type Success<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["success"]["Type"] : never;
 /**
  * A utility type to extract the encoded type of the tool call result when
  * it succeeds.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type SuccessEncoded<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["success"]["Encoded"] : never;
 /**
  * A utility type to extract the schema for the return type of a tool call when
  * the tool call succeeds.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type SuccessSchema<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["success"] : never;
 /**
  * A utility type to extract the type of the tool call result when it fails.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type Failure<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["failure"]["Type"] : never;
 /**
  * A utility type to extract the encoded type of the tool call result when
  * it fails.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type FailureEncoded<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["failure"]["Encoded"] : never;
 /**
@@ -600,15 +629,15 @@ export type FailureEncoded<T> = T extends Tool<infer _Name, infer _Config, infer
  * When `failureMode` is `"return"`, this includes both user-defined failures
  * and `AiError`.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type FailureResult<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["failureMode"] extends "return" ? _Config["failure"]["Type"] | AiError.AiError : _Config["failure"]["Type"] : never;
 /**
  * The encoded version of `FailureResult`.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type FailureResultEncoded<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["failureMode"] extends "return" ? _Config["failure"]["Encoded"] | AiError.AiErrorEncoded : _Config["failure"]["Encoded"] : never;
 /**
@@ -617,8 +646,8 @@ export type FailureResultEncoded<T> = T extends Tool<infer _Name, infer _Config,
  *
  * When `failureMode` is `"return"`, the result may also be an `AiError`.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type Result<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["failureMode"] extends "return" ? Success<T> | Failure<T> | AiError.AiError : Success<T> | Failure<T> : never;
 /**
@@ -627,38 +656,38 @@ export type Result<T> = T extends Tool<infer _Name, infer _Config, infer _Requir
  *
  * When `failureMode` is `"return"`, the result may also be an encoded `AiError`.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type ResultEncoded<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["failureMode"] extends "return" ? SuccessEncoded<T> | FailureEncoded<T> | AiError.AiErrorEncoded : SuccessEncoded<T> | FailureEncoded<T> : never;
 /**
  * A utility type to extract the requirements of a `Tool` call handler.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type HandlerServices<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["parameters"]["DecodingServices"] | ResultEncodingServices<T> | _Requirements : never;
 /**
  * A utility type to extract the requirements needed to encode the result of
  * a `Tool` call.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type ResultEncodingServices<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["success"]["EncodingServices"] | _Config["failure"]["EncodingServices"] : never;
 /**
  * A utility type to extract the requirements needed to decode the result of
  * a `Tool` call.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type ResultDecodingServices<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["success"]["DecodingServices"] | _Config["failure"]["DecodingServices"] : never;
 /**
  * Represents an `Tool` that has been implemented within the application.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Handler<Name extends string> {
     readonly _: unique symbol;
@@ -669,8 +698,8 @@ export interface Handler<Name extends string> {
 /**
  * Represents the result of calling the handler for a particular `Tool`.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface HandlerResult<Tool extends Any> {
     /**
@@ -702,8 +731,8 @@ export interface HandlerResult<Tool extends Any> {
  * - `Preliminary`: An intermediate result representing progress
  * - `Final`: The last result, which is the authoritative output
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type HandlerOutput<Success> = {
     readonly _tag: "Preliminary";
@@ -716,16 +745,16 @@ export type HandlerOutput<Success> = {
  * A utility type which represents the possible errors that can be raised by
  * a tool call's handler.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type HandlerError<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["failureMode"] extends "error" ? _Config["failure"]["Type"] | AiError.AiError : never : never;
 /**
  * A utility type to create a union of `Handler` types for all tools in a
  * record.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type HandlersFor<Tools extends Record<string, Any>> = {
     [Name in keyof Tools]: RequiresHandler<Tools[Name]> extends true ? Handler<Tools[Name]["name"]> : never;
@@ -734,8 +763,8 @@ export type HandlersFor<Tools extends Record<string, Any>> = {
  * A utility type to determine if the specified tool requires a user-defined
  * handler to be implemented.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type RequiresHandler<Tool extends Any> = Tool extends ProviderDefined<infer _Name, infer _Config, infer _RequiresHandler> ? _RequiresHandler : true;
 /**
@@ -748,7 +777,8 @@ export type RequiresHandler<Tool extends Any> = Tool extends ProviderDefined<inf
  * If a tool accepts no parameters but still needs an explicit empty object
  * schema, use {@link EmptyParams}.
  *
- * @example
+ * **Example** (Creating a tool without parameters)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
@@ -760,8 +790,8 @@ export type RequiresHandler<Tool extends Any> = Tool extends ProviderDefined<inf
  * })
  * ```
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const make: <const Name extends string, Parameters extends Schema.Top = typeof EmptyParams, Success extends Schema.Top = typeof Schema.Void, Failure extends Schema.Top = typeof Schema.Never, Mode extends FailureMode | undefined = undefined, Dependencies extends Array<Context.Key<any, any> | Context.Key<never, any>> = []>(name: Name, options?: {
     /**
@@ -820,7 +850,8 @@ export declare const make: <const Name extends string, Parameters extends Schema
  * - When `parameters` is an Effect Schema: full type safety with validation
  * - When `parameters` is a JSON Schema: handler receives `unknown`, no validation
  *
- * @example
+ * **Example** (Creating a dynamic tool)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
@@ -846,8 +877,8 @@ export declare const make: <const Name extends string, Parameters extends Schema
  * })
  * ```
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const dynamic: {
     /**
@@ -860,7 +891,8 @@ export declare const dynamic: {
      * - When `parameters` is an Effect Schema: full type safety with validation
      * - When `parameters` is a JSON Schema: handler receives `unknown`, no validation
      *
-     * @example
+     * **Example** (Creating a dynamic tool)
+     *
      * ```ts
      * import { Schema } from "effect"
      * import { Tool } from "effect/unstable/ai"
@@ -886,8 +918,8 @@ export declare const dynamic: {
      * })
      * ```
      *
-     * @since 1.0.0
      * @category constructors
+     * @since 4.0.0
      */
     <const Name extends string, const Options extends {
         readonly description?: string | undefined;
@@ -919,7 +951,8 @@ export declare const dynamic: {
  * by your application. However, they can optionally require custom handlers
  * implemented in your application to process provider generated results.
  *
- * @example
+ * **Example** (Creating a provider-defined tool)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
@@ -942,8 +975,8 @@ export declare const dynamic: {
  * })
  * ```
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const providerDefined: <const Identifier extends `${string}.${string}`, const Name extends string, Args extends Schema.Top = typeof Schema.Void, Parameters extends Schema.Top = typeof Schema.Void, Success extends Schema.Top = typeof Schema.Void, Failure extends Schema.Top = typeof Schema.Never, RequiresHandler extends boolean = false>(options: {
     /**
@@ -1006,8 +1039,8 @@ export declare const providerDefined: <const Identifier extends `${string}.${str
  * naming conflicts (i.e. `"web_search"`) to instead use custom names (i.e.
  * `"OpenAiWebSearch"`).
  *
- * @since 1.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export declare class NameMapper<Tools extends ReadonlyArray<Any>> {
     #private;
@@ -1043,7 +1076,8 @@ export declare class NameMapper<Tools extends ReadonlyArray<Any>> {
  * Returns the tool's description if explicitly set, otherwise attempts to
  * extract it from the parameter schema's AST annotations.
  *
- * @example
+ * **Example** (Reading a tool description)
+ *
  * ```ts
  * import { Tool } from "effect/unstable/ai"
  *
@@ -1055,8 +1089,8 @@ export declare class NameMapper<Tools extends ReadonlyArray<Any>> {
  * console.log(description) // "This is an example tool"
  * ```
  *
- * @since 1.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export declare const getDescription: <Tool extends Any>(tool: Tool) => string | undefined;
 /**
@@ -1070,7 +1104,8 @@ export declare const getDescription: <Tool extends Any>(tool: Tool) => string |
  * tool parameter schema so that the resultant JSON schema for the tool call
  * parameters are in a format that conforms to any provider-specific constraints.
  *
- * @example
+ * **Example** (Generating a tool JSON schema)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
@@ -1094,15 +1129,22 @@ export declare const getDescription: <Tool extends Any>(tool: Tool) => string |
  * // }
  * ```
  *
- * @since 1.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export declare const getJsonSchema: <Tool extends Any>(tool: Tool, options?: {
     readonly transformer?: CodecTransformer;
 }) => JsonSchema.JsonSchema;
 /**
- * @since 1.0.0
- * @category utilities
+ * Generates a JSON Schema from an Effect `Schema`.
+ *
+ * If a `CodecTransformer` is supplied, the transformed schema's JSON Schema is
+ * returned. Otherwise, the schema is converted with
+ * `Schema.toJsonSchemaDocument` and any generated definitions are attached as
+ * `$defs`.
+ *
+ * @category utils
+ * @since 4.0.0
  */
 export declare const getJsonSchemaFromSchema: <S extends Schema.Top>(schema: S, options?: {
     readonly transformer?: CodecTransformer;
@@ -1111,7 +1153,8 @@ declare const Title_base: Context.ServiceClass<Title, "effect/ai/Tool/Title", st
 /**
  * Annotation for providing a human-readable title for tools.
  *
- * @example
+ * **Example** (Annotating a tool title)
+ *
  * ```ts
  * import { Tool } from "effect/unstable/ai"
  *
@@ -1119,8 +1162,8 @@ declare const Title_base: Context.ServiceClass<Title, "effect/ai/Tool/Title", st
  *   .annotate(Tool.Title, "Tip Calculator")
  * ```
  *
- * @since 1.0.0
  * @category annotations
+ * @since 4.0.0
  */
 export declare class Title extends Title_base {
 }
@@ -1128,22 +1171,28 @@ declare const Meta_base: Context.ServiceClass<Meta, "effect/ai/Tool/Meta", Recor
 /**
  * Annotation for providing tool metadata for MCP.
  *
- * @example
+ * **Example** (Annotating MCP metadata)
+ *
  * ```ts
  * import { Tool } from "effect/unstable/ai"
  *
  * const myCalculatorUi = Tool.make("calculator_ui", {})
  *   .annotate(Tool.Meta, { ui: { resourceUri: "ui://example/calculator-ui" } })
  * ```
- * @since 1.0.0
+ *
  * @category annotations
+ * @since 4.0.0
  */
 export declare class Meta extends Meta_base {
 }
 /**
  * Annotation indicating whether a tool only reads data without making changes.
  *
- * @example
+ * This is emitted as the MCP `readOnlyHint`; unannotated tools default to
+ * `false`.
+ *
+ * **Example** (Marking a tool as read-only)
+ *
  * ```ts
  * import { Tool } from "effect/unstable/ai"
  *
@@ -1151,14 +1200,18 @@ export declare class Meta extends Meta_base {
  *   .annotate(Tool.Readonly, true)
  * ```
  *
- * @since 1.0.0
  * @category annotations
+ * @since 4.0.0
  */
 export declare const Readonly: Context.Reference<boolean>;
 /**
- * Annotation indicating whether a tool performs destructive operations.
+ * Annotation indicating whether a tool may perform destructive operations.
+ *
+ * This is emitted as the MCP `destructiveHint`; unannotated tools default to
+ * `true`, so annotate safe tools with `false`.
+ *
+ * **Example** (Marking a tool as non-destructive)
  *
- * @example
  * ```ts
  * import { Tool } from "effect/unstable/ai"
  *
@@ -1166,14 +1219,19 @@ export declare const Readonly: Context.Reference<boolean>;
  *   .annotate(Tool.Destructive, false)
  * ```
  *
- * @since 1.0.0
  * @category annotations
+ * @since 4.0.0
  */
 export declare const Destructive: Context.Reference<boolean>;
 /**
- * Annotation indicating whether a tool can be called multiple times safely.
+ * Annotation indicating whether a tool can be called repeatedly with the same
+ * parameters without changing the result beyond the first call.
+ *
+ * This is emitted as the MCP `idempotentHint`; unannotated tools default to
+ * `false`.
+ *
+ * **Example** (Marking a tool as idempotent)
  *
- * @example
  * ```ts
  * import { Tool } from "effect/unstable/ai"
  *
@@ -1181,14 +1239,19 @@ export declare const Destructive: Context.Reference<boolean>;
  *   .annotate(Tool.Idempotent, true)
  * ```
  *
- * @since 1.0.0
  * @category annotations
+ * @since 4.0.0
  */
 export declare const Idempotent: Context.Reference<boolean>;
 /**
- * Annotation indicating whether a tool can handle arbitrary external data.
+ * Annotation indicating whether a tool may interact with arbitrary external
+ * data or systems.
+ *
+ * This is emitted as the MCP `openWorldHint`; unannotated tools default to
+ * `true`.
+ *
+ * **Example** (Disabling open-world access)
  *
- * @example
  * ```ts
  * import { Tool } from "effect/unstable/ai"
  *
@@ -1196,8 +1259,8 @@ export declare const Idempotent: Context.Reference<boolean>;
  *   .annotate(Tool.OpenWorld, false)
  * ```
  *
- * @since 1.0.0
  * @category annotations
+ * @since 4.0.0
  */
 export declare const OpenWorld: Context.Reference<boolean>;
 /**
@@ -1211,7 +1274,8 @@ export declare const OpenWorld: Context.Reference<boolean>;
  * When `undefined` (default), the provider's global configuration determines
  * the behavior (e.g. `Config.strictJsonSchema` for OpenAI).
  *
- * @example
+ * **Example** (Disabling strict JSON schema mode)
+ *
  * ```ts
  * import { Tool } from "effect/unstable/ai"
  *
@@ -1219,26 +1283,32 @@ export declare const OpenWorld: Context.Reference<boolean>;
  *   .annotate(Tool.Strict, false)
  * ```
  *
- * @since 1.0.0
  * @category annotations
+ * @since 4.0.0
  */
 export declare const Strict: Context.Reference<boolean | undefined>;
 /**
  * Returns the strict mode setting for a tool, or `undefined` if not set.
  *
- * @since 1.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export declare const getStrictMode: <T extends Any>(tool: T) => boolean | undefined;
 /**
  * **Unsafe**: This function will throw an error if an insecure property is
  * found in the parsed JSON or if the provided JSON text is not parseable.
  *
- * @since 1.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export declare const unsafeSecureJsonParse: (text: string) => unknown;
 /**
+ * Type of the `EmptyParams` schema used for tools with no parameters.
+ *
+ * It is a record schema with string keys and `never` values, so the generated
+ * parameter schema accepts an empty object shape with no properties.
+ *
+ * @category schemas
  * @since 4.0.0
  */
 export interface EmptyParams extends Schema.$Record<Schema.String, Schema.Never> {
@@ -1246,6 +1316,7 @@ export interface EmptyParams extends Schema.$Record<Schema.String, Schema.Never>
 /**
  * A schema for tools that accept no parameters.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export declare const EmptyParams: EmptyParams;