@effect/ai 0.26.0 → 0.27.0

package/dist/dts/Tool.d.ts

@@ -0,0 +1,876 @@
+/**
+ * The `Tool` module provides functionality for defining and managing tools
+ * that language models can call to augment their capabilities.
+ *
+ * This module enables creation of both user-defined and provider-defined tools,
+ * with full schema validation, type safety, and handler support. Tools allow
+ * AI models to perform actions like searching databases, calling APIs, or
+ * executing code within your application context.
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "@effect/ai"
+ * import { Schema } from "effect"
+ *
+ * // Define a simple calculator tool
+ * const Calculator = Tool.make("Calculator", {
+ *   description: "Performs basic arithmetic operations",
+ *   parameters: {
+ *     operation: Schema.Literal("add", "subtract", "multiply", "divide"),
+ *     a: Schema.Number,
+ *     b: Schema.Number
+ *   },
+ *   success: Schema.Number
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as JsonSchema from "effect/JSONSchema";
+import type { Pipeable } from "effect/Pipeable";
+import * as Schema from "effect/Schema";
+import * as AST from "effect/SchemaAST";
+import type { Covariant } from "effect/Types";
+import * as AiError from "./AiError.js";
+/**
+ * Unique identifier for user-defined tools.
+ *
+ * @since 1.0.0
+ * @category Type Ids
+ */
+export declare const TypeId = "~@effect/ai/Tool";
+/**
+ * Type-level representation of the user-defined tool identifier.
+ *
+ * @since 1.0.0
+ * @category Type Ids
+ */
+export type TypeId = typeof TypeId;
+/**
+ * Unique identifier for provider-defined tools.
+ *
+ * @since 1.0.0
+ * @category Type Ids
+ */
+export declare const ProviderDefinedTypeId = "~@effect/ai/Tool/ProviderDefined";
+/**
+ * Type-level representation of the provider-defined tool identifier.
+ *
+ * @since 1.0.0
+ * @category Type Ids
+ */
+export type ProviderDefinedTypeId = typeof ProviderDefinedTypeId;
+/**
+ * A user-defined tool that language models can call to perform actions.
+ *
+ * Tools represent actionable capabilities that large language models can invoke
+ * to extend their functionality beyond text generation. Each tool has a defined
+ * schema for parameters, results, and failures.
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "@effect/ai"
+ * import { Schema } from "effect"
+ *
+ * // Create a weather lookup tool
+ * const GetWeather = Tool.make("GetWeather", {
+ *   description: "Get current weather for a location",
+ *   parameters: {
+ *     location: Schema.String,
+ *     units: Schema.Literal("celsius", "fahrenheit")
+ *   },
+ *   success: Schema.Struct({
+ *     temperature: Schema.Number,
+ *     condition: Schema.String,
+ *     humidity: Schema.Number
+ *   })
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface Tool<Name extends string, Config extends {
+    readonly parameters: AnyStructSchema;
+    readonly success: Schema.Schema.Any;
+    readonly failure: Schema.Schema.All;
+} = {
+    readonly parameters: Schema.Struct<{}>;
+    readonly success: typeof Schema.Void;
+    readonly failure: typeof Schema.Never;
+}, Requirements = never> extends Tool.Variance<Requirements> {
+    /**
+     * The tool identifier which is used to uniquely identify the tool. */
+    readonly id: string;
+    /**
+     * The name of the tool.
+     */
+    readonly name: Name;
+    /**
+     * The optional description of the tool.
+     */
+    readonly description?: string | undefined;
+    /**
+     * A `Schema` representing the parameters that a tool must be called with.
+     */
+    readonly parametersSchema: Config["parameters"];
+    /**
+     * A `Schema` representing the value that a tool must return when called if
+     * the tool call is successful.
+     */
+    readonly successSchema: Config["success"];
+    /**
+     * A `Schema` representing the value that a tool must return when called if
+     * it fails.
+     */
+    readonly failureSchema: Config["failure"];
+    /**
+     * A `Context` object containing tool annotations which can store metadata
+     * about the tool.
+     */
+    readonly annotations: Context.Context<never>;
+    /**
+     * Adds a _request-level_ dependency which must be provided before the tool
+     * call handler can be executed.
+     *
+     * This can be useful when you want to enforce that a particular dependency
+     * **MUST** be provided to each request to the large language model provider
+     * instead of being provided when creating the tool call handler layer.
+     */
+    addDependency<Identifier, Service>(tag: Context.Tag<Identifier, Service>): Tool<Name, Config, Identifier | Requirements>;
+    /**
+     * Set the schema to use to validate the result of a tool call when successful.
+     */
+    setParameters<ParametersSchema extends Schema.Struct<any> | Schema.Struct.Fields>(schema: ParametersSchema): Tool<Name, {
+        readonly parameters: ParametersSchema extends Schema.Struct<infer _> ? ParametersSchema : ParametersSchema extends Schema.Struct.Fields ? Schema.Struct<ParametersSchema> : never;
+        readonly success: Config["success"];
+        readonly failure: Config["failure"];
+    }, Requirements>;
+    /**
+     * Set the schema to use to validate the result of a tool call when successful.
+     */
+    setSuccess<SuccessSchema extends Schema.Schema.Any>(schema: SuccessSchema): Tool<Name, {
+        readonly parameters: Config["parameters"];
+        readonly success: SuccessSchema;
+        readonly failure: Config["failure"];
+    }, Requirements>;
+    /**
+     * Set the schema to use to validate the result of a tool call when it fails.
+     */
+    setFailure<FailureSchema extends Schema.Schema.Any>(schema: FailureSchema): Tool<Name, {
+        readonly parameters: Config["parameters"];
+        readonly success: Config["success"];
+        readonly failure: FailureSchema;
+    }, Requirements>;
+    /**
+     * Add an annotation to the tool.
+     */
+    annotate<I, S>(tag: Context.Tag<I, S>, value: S): Tool<Name, Config, Requirements>;
+    /**
+     * Add many annotations to the tool.
+     */
+    annotateContext<I>(context: Context.Context<I>): Tool<Name, Config, Requirements>;
+}
+/**
+ * A provider-defined tool is a tool which is built into a large language model
+ * provider (e.g. web search, code execution).
+ *
+ * These tools are executed by the large language model provider rather than
+ * by your application. However, they can optionally require custom handlers
+ * implemented in your application to process provider generated results.
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "@effect/ai"
+ * import { Schema } from "effect"
+ *
+ * // Define a web search tool provided by OpenAI
+ * const WebSearch = Tool.providerDefined({
+ *   id: "openai.web_search",
+ *   toolkitName: "WebSearch",
+ *   providerName: "web_search",
+ *   args: {
+ *     query: Schema.String
+ *   },
+ *   success: Schema.Struct({
+ *     results: Schema.Array(Schema.Struct({
+ *       title: Schema.String,
+ *       url: Schema.String,
+ *       snippet: Schema.String
+ *     }))
+ *   })
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface ProviderDefined<Name extends string, Config extends {
+    readonly args: AnyStructSchema;
+    readonly parameters: AnyStructSchema;
+    readonly success: Schema.Schema.Any;
+    readonly failure: Schema.Schema.All;
+} = {
+    readonly args: Schema.Struct<{}>;
+    readonly parameters: Schema.Struct<{}>;
+    readonly success: typeof Schema.Void;
+    readonly failure: typeof Schema.Never;
+}, RequiresHandler extends boolean = false> extends Tool<Name, {
+    readonly parameters: Config["parameters"];
+    success: RequiresHandler extends true ? Config["success"] : Schema.Either<Config["success"], Config["failure"]>;
+    failure: RequiresHandler extends true ? Config["failure"] : typeof Schema.Never;
+}>, Tool.ProviderDefinedProto {
+    /**
+     * The arguments passed to the provider-defined tool.
+     */
+    readonly args: Config["args"]["Encoded"];
+    /**
+     * A `Schema` representing the arguments provided by the end-user which will
+     * be used to configure the behavior of the provider-defined tool.
+     */
+    readonly argsSchema: Config["args"];
+    /**
+     * Name of the tool as recognized by the large language model provider.
+     */
+    readonly providerName: string;
+    /**
+     * If set to `true`, this provider-defined tool will require a user-defined
+     * tool call handler to be provided when converting the `Toolkit` containing
+     * this tool into a `Layer`.
+     */
+    readonly requiresHandler: RequiresHandler;
+    /**
+     * Decodes the result received after the provider-defined tool is called.
+     */
+    decodeResult(args: unknown): Effect.Effect<Config["success"]["Type"], AiError.AiError>;
+}
+/**
+ * @since 1.0.0
+ */
+export declare namespace Tool {
+    /**
+     * @since 1.0.0
+     * @category Models
+     */
+    interface Variance<out Requirements> extends Pipeable {
+        readonly [TypeId]: VarianceStruct<Requirements>;
+    }
+    /**
+     * @since 1.0.0
+     * @category Models
+     */
+    interface VarianceStruct<out Requirements> {
+        readonly _Requirements: Covariant<Requirements>;
+    }
+    /**
+     * @since 1.0.0
+     * @category Models
+     */
+    interface ProviderDefinedProto {
+        readonly [ProviderDefinedTypeId]: ProviderDefinedTypeId;
+    }
+}
+/**
+ * Type guard to check if a value is a user-defined tool.
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "@effect/ai"
+ * import { Schema } from "effect"
+ *
+ * const UserDefinedTool = Tool.make("Calculator", {
+ *   description: "Performs basic arithmetic operations",
+ *   parameters: {
+ *     operation: Schema.Literal("add", "subtract", "multiply", "divide"),
+ *     a: Schema.Number,
+ *     b: Schema.Number
+ *   },
+ *   success: Schema.Number
+ * })
+ *
+ * const ProviderDefinedTool = Tool.providerDefined({
+ *   id: "openai.web_search",
+ *   toolkitName: "WebSearch",
+ *   providerName: "web_search",
+ *   args: {
+ *     query: Schema.String
+ *   },
+ *   success: Schema.Struct({
+ *     results: Schema.Array(Schema.Struct({
+ *       title: Schema.String,
+ *       url: Schema.String,
+ *       snippet: Schema.String
+ *     }))
+ *   })
+ * })
+ *
+ * console.log(Tool.isUserDefined(UserDefinedTool))      // true
+ * console.log(Tool.isUserDefined(ProviderDefinedTool))  // false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Guards
+ */
+export declare const isUserDefined: (u: unknown) => u is Tool<string, any, any>;
+/**
+ * Type guard to check if a value is a provider-defined tool.
+ *
+ * @param u - The value to check
+ * @returns `true` if the value is a provider-defined `Tool`, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "@effect/ai"
+ * import { Schema } from "effect"
+ *
+ * const UserDefinedTool = Tool.make("Calculator", {
+ *   description: "Performs basic arithmetic operations",
+ *   parameters: {
+ *     operation: Schema.Literal("add", "subtract", "multiply", "divide"),
+ *     a: Schema.Number,
+ *     b: Schema.Number
+ *   },
+ *   success: Schema.Number
+ * })
+ *
+ * const ProviderDefinedTool = Tool.providerDefined({
+ *   id: "openai.web_search",
+ *   toolkitName: "WebSearch",
+ *   providerName: "web_search",
+ *   args: {
+ *     query: Schema.String
+ *   },
+ *   success: Schema.Struct({
+ *     results: Schema.Array(Schema.Struct({
+ *       title: Schema.String,
+ *       url: Schema.String,
+ *       snippet: Schema.String
+ *     }))
+ *   })
+ * })
+ *
+ * console.log(Tool.isUserDefined(UserDefinedTool))      // false
+ * console.log(Tool.isUserDefined(ProviderDefinedTool))  // true
+ * ```
+ *
+ * @since 1.0.0
+ * @category Guards
+ */
+export declare const isProviderDefined: (u: unknown) => u is ProviderDefined<string, any>;
+/**
+ * A type which represents any `Tool`.
+ *
+ * @since 1.0.0
+ * @category Utility Types
+ */
+export interface Any extends Pipeable {
+    readonly [TypeId]: {
+        readonly _Requirements: Covariant<any>;
+    };
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string | undefined;
+    readonly parametersSchema: AnyStructSchema;
+    readonly successSchema: Schema.Schema.Any;
+    readonly failureSchema: Schema.Schema.All;
+    readonly annotations: Context.Context<never>;
+}
+/**
+ * A type which represents any provider-defined `Tool`.
+ *
+ * @since 1.0.0
+ * @category Utility Types
+ */
+export interface AnyProviderDefined extends Any {
+    readonly args: any;
+    readonly argsSchema: AnyStructSchema;
+    readonly requiresHandler: boolean;
+    readonly providerName: string;
+    readonly decodeResult: (result: unknown) => Effect.Effect<any, AiError.AiError>;
+}
+/**
+ * @since 1.0.0
+ * @category Utility Types
+ */
+export interface AnyStructSchema extends Pipeable {
+    readonly [Schema.TypeId]: any;
+    readonly make: any;
+    readonly Type: any;
+    readonly Encoded: any;
+    readonly Context: any;
+    readonly ast: AST.AST;
+    readonly fields: Schema.Struct.Fields;
+    readonly annotations: any;
+}
+/**
+ * @since 1.0.0
+ * @category Utility Types
+ */
+export interface AnyTaggedRequestSchema extends AnyStructSchema {
+    readonly _tag: string;
+    readonly success: Schema.Schema.Any;
+    readonly failure: Schema.Schema.All;
+}
+/**
+ * A utility type to convert a `Schema.TaggedRequest` into an `Tool`.
+ *
+ * @since 1.0.0
+ * @category Utility Types
+ */
+export interface FromTaggedRequest<S extends AnyTaggedRequestSchema> extends Tool<S["_tag"], {
+    readonly parameters: S;
+    readonly success: S["success"];
+    readonly failure: S["failure"];
+}> {
+}
+/**
+ * A utility type to extract the `Name` type from an `Tool`.
+ *
+ * @since 1.0.0
+ * @category Utility Types
+ */
+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
+ */
+export type Parameters<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? Schema.Struct.Type<_Config["parameters"]["fields"]> : never;
+/**
+ * A utility type to extract the encoded type of the tool call parameters.
+ *
+ * @since 1.0.0
+ * @category Utility Types
+ */
+export type ParametersEncoded<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? Schema.Schema.Encoded<_Config["parameters"]> : 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
+ */
+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
+ */
+export type Success<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? Schema.Schema.Type<_Config["success"]> : never;
+/**
+ * A utility type to extract the encoded type of the tool call result when
+ * it succeeds.
+ *
+ * @since 1.0.0
+ * @category Utility Types
+ */
+export type SuccessEncoded<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? Schema.Schema.Encoded<_Config["success"]> : 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
+ */
+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
+ */
+export type Failure<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? Schema.Schema.Type<_Config["failure"]> : never;
+/**
+ * A utility type to extract the encoded type of the tool call result when
+ * it fails.
+ *
+ * @since 1.0.0
+ * @category Utility Types
+ */
+export type FailureEncoded<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? Schema.Schema.Encoded<_Config["failure"]> : never;
+/**
+ * A utility type to extract the requirements of an `Tool`.
+ *
+ * @since 1.0.0
+ * @category Utility Types
+ */
+export type Requirements<T> = T extends Tool<infer _Name, infer _Config, infer _Requirements> ? _Config["parameters"]["Context"] | _Config["success"]["Context"] | _Config["failure"]["Context"] | _Requirements : never;
+/**
+ * Represents an `Tool` that has been implemented within the application.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface Handler<Name extends string> {
+    readonly _: unique symbol;
+    readonly name: Name;
+    readonly context: Context.Context<never>;
+    readonly handler: (params: any) => Effect.Effect<any, any>;
+}
+/**
+ * Represents the result of calling the handler for a particular `Tool`.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface HandlerResult<Tool extends Any> {
+    /**
+     * The result of executing the handler for a particular tool.
+     */
+    readonly result: Success<Tool>;
+    /**
+     * The pre-encoded tool call result of executing the handler for a particular
+     * tool as a JSON-serializable value. The encoded result can be incorporated
+     * into subsequent requests to the large language model.
+     */
+    readonly encodedResult: unknown;
+}
+/**
+ * A utility type to create a union of `Handler` types for all tools in a
+ * record.
+ *
+ * @since 1.0.0
+ * @category Utility Types
+ */
+export type HandlersFor<Tools extends Record<string, Any>> = {
+    [K in keyof Tools]: Handler<Tools[K]["name"]>;
+}[keyof Tools];
+/**
+ * A utility type to determine if the specified tool requires a user-defined
+ * handler to be implemented.
+ *
+ * @since 1.0.0
+ * @category Utility Types
+ */
+export type RequiresHandler<Tool extends Any> = Tool extends ProviderDefined<infer _Name, infer _Config, infer _RequiresHandler> ? _RequiresHandler : true;
+/**
+ * Creates a user-defined tool with the specified name and configuration.
+ *
+ * This is the primary constructor for creating custom tools that AI models
+ * can call. The tool definition includes parameter validation, success/failure
+ * schemas, and optional service dependencies.
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "@effect/ai"
+ * import { Schema } from "effect"
+ *
+ * // Simple tool with no parameters
+ * const GetCurrentTime = Tool.make("GetCurrentTime", {
+ *   description: "Returns the current timestamp",
+ *   success: Schema.Number
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export declare const make: <const Name extends string, Parameters extends Schema.Struct.Fields = {}, Success extends Schema.Schema.Any = typeof Schema.Void, Failure extends Schema.Schema.All = typeof Schema.Never, Dependencies extends Array<Context.Tag<any, any>> = []>(
+/**
+ * The unique name identifier for this tool.
+ */
+name: Name, options?: {
+    /**
+     * An optional description explaining what the tool does.
+     */
+    readonly description?: string | undefined;
+    /**
+     * Schema defining the parameters this tool accepts.
+     */
+    readonly parameters?: Parameters | undefined;
+    /**
+     * Schema for successful tool execution results.
+     */
+    readonly success?: Success | undefined;
+    /**
+     * Schema for tool execution failures.
+     */
+    readonly failure?: Failure | undefined;
+    /**
+     * Service dependencies required by the tool handler.
+     */
+    readonly dependencies?: Dependencies | undefined;
+}) => Tool<Name, {
+    readonly parameters: Schema.Struct<Parameters>;
+    readonly success: Success;
+    readonly failure: Failure;
+}, Context.Tag.Identifier<Dependencies[number]>>;
+/**
+ * Creates a provider-defined tool which leverages functionality built into a
+ * large language model provider (e.g. web search, code execution).
+ *
+ * These tools are executed by the large language model provider rather than
+ * by your application. However, they can optionally require custom handlers
+ * implemented in your application to process provider generated results.
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "@effect/ai"
+ * import { Schema } from "effect"
+ *
+ * // Web search tool provided by OpenAI
+ * const WebSearch = Tool.providerDefined({
+ *   id: "openai.web_search",
+ *   toolkitName: "WebSearch",
+ *   providerName: "web_search",
+ *   args: {
+ *     query: Schema.String
+ *   },
+ *   success: Schema.Struct({
+ *     results: Schema.Array(Schema.Struct({
+ *       title: Schema.String,
+ *       url: Schema.String,
+ *       content: Schema.String
+ *     }))
+ *   })
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export declare const providerDefined: <const Name extends string, Args extends Schema.Struct.Fields = {}, Parameters extends Schema.Struct.Fields = {}, Success extends Schema.Schema.Any = typeof Schema.Void, Failure extends Schema.Schema.All = typeof Schema.Never, RequiresHandler extends boolean = false>(options: {
+    /**
+     * Unique identifier following format `<provider>.<tool-name>`.
+     */
+    readonly id: `${string}.${string}`;
+    /**
+     * Name used by the Toolkit to identify this tool.
+     */
+    readonly toolkitName: Name;
+    /**
+     * Name of the tool as recognized by the AI provider.
+     */
+    readonly providerName: string;
+    /**
+     * Schema for user-provided configuration arguments.
+     */
+    readonly args: Args;
+    /**
+     * Whether this tool requires a custom handler implementation.
+     */
+    readonly requiresHandler?: RequiresHandler | undefined;
+    /**
+     * Schema for parameters the provider sends when calling the tool.
+     */
+    readonly parameters?: Parameters | undefined;
+    /**
+     * Schema for successful tool execution results.
+     */
+    readonly success?: Success | undefined;
+    /**
+     * Schema for failed tool execution results.
+     */
+    readonly failure?: Failure | undefined;
+}) => (args: Schema.Simplify<Schema.Struct.Encoded<Args>>) => ProviderDefined<Name, {
+    readonly args: Schema.Struct<Args>;
+    readonly parameters: Schema.Struct<Parameters>;
+    readonly success: Success;
+    readonly failure: Failure;
+}, RequiresHandler>;
+/**
+ * Creates a Tool from a Schema.TaggedRequest.
+ *
+ * This utility function converts Effect's TaggedRequest schemas into Tool
+ * definitions, automatically mapping the request parameters, success, and
+ * failure schemas.
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "@effect/ai"
+ * import { Schema } from "effect"
+ *
+ * // Define a tagged request for user operations
+ * class GetUser extends Schema.TaggedRequest<GetUser>()("GetUser", {
+ *   success: Schema.Struct({
+ *     id: Schema.Number,
+ *     name: Schema.String,
+ *     email: Schema.String
+ *   }),
+ *   failure: Schema.Struct({
+ *     error: Schema.Literal("UserNotFound", "DatabaseError"),
+ *     message: Schema.String
+ *   }),
+ *   payload: {
+ *     userId: Schema.Number
+ *   }
+ * }) {}
+ *
+ * // Convert to a Tool
+ * const getUserTool = Tool.fromTaggedRequest(GetUser)
+ * ```
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export declare const fromTaggedRequest: <S extends AnyTaggedRequestSchema>(schema: S) => FromTaggedRequest<S>;
+/**
+ * Extracts the description from a tool's metadata.
+ *
+ * Returns the tool's description if explicitly set, otherwise attempts to
+ * extract it from the parameter schema's AST annotations.
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "@effect/ai"
+ *
+ * const myTool = Tool.make("example", {
+ *   description: "This is an example tool"
+ * })
+ *
+ * const description = Tool.getDescription(myTool)
+ * console.log(description) // "This is an example tool"
+ * ```
+ *
+ * @since 1.0.0
+ * @category Utilities
+ */
+export declare const getDescription: <Name extends string, Config extends {
+    readonly parameters: AnyStructSchema;
+    readonly success: Schema.Schema.Any;
+    readonly failure: Schema.Schema.All;
+}>(
+/**
+ * The tool to get the description from.
+ */
+tool: Tool<Name, Config>) => string | undefined;
+/**
+ * @since 1.0.0
+ * @category Utilities
+ */
+export declare const getDescriptionFromSchemaAst: (ast: AST.AST) => string | undefined;
+/**
+ * Generates a JSON Schema for a tool.
+ *
+ * This function creates a JSON Schema representation that can be used by
+ * large language models to indicate the structure and type of the parameters
+ * that a given tool call should receive.
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "@effect/ai"
+ * import { Schema } from "effect"
+ *
+ * const weatherTool = Tool.make("get_weather", {
+ *   parameters: {
+ *     location: Schema.String,
+ *     units: Schema.optional(Schema.Literal("celsius", "fahrenheit"))
+ *   }
+ * })
+ *
+ * const jsonSchema = Tool.getJsonSchema(weatherTool)
+ * console.log(jsonSchema)
+ * // {
+ * //   type: "object",
+ * //   properties: {
+ * //     location: { type: "string" },
+ * //     units: { type: "string", enum: ["celsius", "fahrenheit"] }
+ * //   },
+ * //   required: ["location"]
+ * // }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Utilities
+ */
+export declare const getJsonSchema: <Name extends string, Config extends {
+    readonly parameters: AnyStructSchema;
+    readonly success: Schema.Schema.Any;
+    readonly failure: Schema.Schema.All;
+}>(tool: Tool<Name, Config>) => JsonSchema.JsonSchema7;
+/**
+ * @since 1.0.0
+ * @category Utilities
+ */
+export declare const getJsonSchemaFromSchemaAst: (ast: AST.AST) => JsonSchema.JsonSchema7;
+declare const Title_base: Context.TagClass<Title, "@effect/ai/Tool/Title", string>;
+/**
+ * Annotation for providing a human-readable title for tools.
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "@effect/ai"
+ *
+ * const myTool = Tool.make("calculate_tip")
+ *   .annotate(Tool.Title, "Tip Calculator")
+ * ```
+ *
+ * @since 1.0.0
+ * @category Annotations
+ */
+export declare class Title extends Title_base {
+}
+declare const Readonly_base: Context.ReferenceClass<Readonly, "@effect/ai/Tool/Readonly", boolean>;
+/**
+ * Annotation indicating whether a tool only reads data without making changes.
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "@effect/ai"
+ *
+ * const readOnlyTool = Tool.make("get_user_info")
+ *   .annotate(Tool.Readonly, true)
+ * ```
+ *
+ * @since 1.0.0
+ * @category Annotations
+ */
+export declare class Readonly extends Readonly_base {
+}
+declare const Destructive_base: Context.ReferenceClass<Destructive, "@effect/ai/Tool/Destructive", boolean>;
+/**
+ * Annotation indicating whether a tool performs destructive operations.
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "@effect/ai"
+ *
+ * const safeTool = Tool.make("search_database")
+ *   .annotate(Tool.Destructive, false)
+ * ```
+ *
+ * @since 1.0.0
+ * @category Annotations
+ */
+export declare class Destructive extends Destructive_base {
+}
+declare const Idempotent_base: Context.ReferenceClass<Idempotent, "@effect/ai/Tool/Idempotent", boolean>;
+/**
+ * Annotation indicating whether a tool can be called multiple times safely.
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "@effect/ai"
+ *
+ * const idempotentTool = Tool.make("get_current_time")
+ *   .annotate(Tool.Idempotent, true)
+ * ```
+ *
+ * @since 1.0.0
+ * @category Annotations
+ */
+export declare class Idempotent extends Idempotent_base {
+}
+declare const OpenWorld_base: Context.ReferenceClass<OpenWorld, "@effect/ai/Tool/OpenWorld", boolean>;
+/**
+ * Annotation indicating whether a tool can handle arbitrary external data.
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "@effect/ai"
+ *
+ * const restrictedTool = Tool.make("internal_operation")
+ *   .annotate(Tool.OpenWorld, false)
+ * ```
+ *
+ * @since 1.0.0
+ * @category Annotations
+ */
+export declare class OpenWorld extends OpenWorld_base {
+}
+export {};
+//# sourceMappingURL=Tool.d.ts.map