opencode-effect-enforcer 0.2.0

package/skills/effect-ai-tool/SKILL.md

@@ -0,0 +1,1132 @@
+---
+name: effect-ai-tool
+description: Define and implement AI tools using Effect AI's Tool and Toolkit APIs. Use when building LLM integrations with type-safe tool definitions, parameter validation, and handler implementations. Covers user-defined tools, provider-defined tools, and toolkit composition.
+---
+
+# Effect AI Tool Skill
+
+Use this skill when implementing tools for AI language models using the Effect AI library. This covers tool definition, parameter schemas, success/failure handling, and toolkit composition.
+
+## Effect AI Documentation Access
+
+For comprehensive Effect AI documentation, view the Effect v4 repository at `packages/ai/`
+
+Reference this for:
+
+- Tool.make, Tool.dynamic, and Tool.providerDefined APIs
+- Toolkit.make for composing multiple tools
+- Schema.Struct(...) for Tool.make parameters
+- Handler implementation patterns
+- OpenAI provider-defined tools via `@effect/ai-openai/OpenAiTool`
+
+## Core Concepts
+
+### Tool Anatomy
+
+```typescript
+Effect<A, E, R>
+       ↓
+Tool<Name, Config, Requirements>
+
+Config := {
+  parameters: Schema.Struct<Fields>
+  success: Schema<A>
+  failure: Schema<E>
+  failureMode: "error" | "return"
+}
+```
+
+### Toolkit Flow
+
+```typescript
+Tool₁, Tool₂, Tool₃
+       ↓ Toolkit.make
+Toolkit<{tool1: Tool₁, tool2: Tool₂, tool3: Tool₃}>
+       ↓ .toLayer(handlers)
+Layer<Handlers>
+       ↓ Effect.provide
+Effect with tool execution capability
+```
+
+## Production Harness Pattern: Effectful Local Tool Wrappers
+
+`Tool.make` is the core user-defined Effect AI tool API. Effect AI also has `Tool.dynamic` for runtime-discovered tools and `Tool.providerDefined` for native provider capabilities. In larger coding-agent harnesses, it is common to wrap local tool definitions in an effectful layer so it can capture services once and keep a single `Effect.runPromise` bridge at the outer async framework boundary.
+
+This wrapper is local to your harness, not part of Effect AI itself.
+
+```typescript
+import { Effect } from 'effect';
+
+export const ReadTool = defineEffect(
+	'read',
+	Effect.gen(function* () {
+		const fs = yield* AppFileSystem.Service;
+
+		const run = Effect.fn('ReadTool.execute')(function* (params: Params) {
+			return yield* fs.readFileString(params.path);
+		});
+
+		return {
+			description: 'Read a file',
+			async execute(params: Params) {
+				return Effect.runPromise(run(params));
+			}
+		};
+	})
+);
+```
+
+Use this pattern when the surrounding framework wants an async callback surface but your real implementation should stay in Effect.
+
+## Creating User-Defined Tools
+
+### Basic Tool Definition
+
+```typescript
+import * as Tool from 'effect/unstable/ai/Tool';
+import * as Schema from 'effect/Schema';
+
+const GetCurrentTime = Tool.make('GetCurrentTime', {
+	description: 'Returns the current timestamp in milliseconds',
+	success: Schema.Number
+});
+
+const result = Tool.Success<typeof GetCurrentTime>;
+```
+
+**Key Pattern: Tool.make**
+
+- First parameter: tool name (string literal)
+- Second parameter: configuration object
+- No parameters field = empty parameters `{}`
+- Default success: `Schema.Void`
+- Default failure: `Schema.Never`
+
+### Tool from Domain Schema
+
+If you have an existing domain schema you want to use as a tool, create the tool with `Tool.make` and reference the schema directly:
+
+```typescript
+import * as Tool from 'effect/unstable/ai/Tool';
+import * as Schema from 'effect/Schema';
+
+const UserResult = Schema.Struct({
+	id: Schema.String,
+	name: Schema.String
+});
+
+const GetUserTool = Tool.make('GetUser', {
+	description: 'Retrieve user information by ID',
+	parameters: Schema.Struct({
+		userId: Schema.String
+	}),
+	success: UserResult
+});
+
+type Params = Tool.Parameters<typeof GetUserTool>;
+type ParamsEncoded = Tool.ParametersEncoded<typeof GetUserTool>;
+type Success = Tool.Success<typeof GetUserTool>;
+```
+
+**Key Pattern: Tool.make with domain schemas**
+
+- Use `Tool.make` for user-defined tools
+- Reference existing domain schemas in `parameters`, `success`, and `failure` fields
+- Tool name is the first argument (string literal)
+- Use `Tool.dynamic` for runtime-discovered tools and `Tool.providerDefined` / `OpenAiTool` for provider-native tools
+- There is no `Tool.fromTaggedRequest` in v4
+
+### Tool with Parameters
+
+```typescript
+import * as Tool from 'effect/unstable/ai/Tool';
+import { Schema } from 'effect';
+
+const GetWeather = Tool.make('GetWeather', {
+	description: 'Get weather information for a location',
+	parameters: Schema.Struct({
+		location: Schema.String,
+		units: Schema.optional(Schema.Literals(['celsius', 'fahrenheit']))
+	}),
+	success: Schema.Struct({
+		temperature: Schema.Number,
+		condition: Schema.String,
+		humidity: Schema.Number
+	})
+});
+
+type Params = Tool.Parameters<typeof GetWeather>;
+type Success = Tool.Success<typeof GetWeather>;
+```
+
+**Key Pattern: parameters**
+
+- `Tool.make` parameters must be an Effect `Schema.Top`
+- Wrap field records with `Schema.Struct({...})`; `Tool.make` does not wrap raw field objects automatically
+- `Tool.dynamic` can use either typed Effect schemas or raw JSON Schema discovered at runtime
+- Use `Schema.optional()` for optional parameters
+
+### Tool with Failure Handling
+
+```typescript
+import * as Tool from 'effect/unstable/ai/Tool';
+import { Schema } from 'effect';
+
+class UserNotFound extends Schema.TaggedError<UserNotFound>()(
+	'UserNotFound',
+	{
+		userId: Schema.String
+	}
+) {}
+
+class DatabaseError extends Schema.TaggedError<DatabaseError>()(
+	'DatabaseError',
+	{
+		message: Schema.String
+	}
+) {}
+
+const FindUser = Tool.make('FindUser', {
+	description: 'Find user by ID',
+	parameters: Schema.Struct({
+		userId: Schema.String
+	}),
+	success: Schema.Struct({
+		id: Schema.String,
+		name: Schema.String,
+		email: Schema.String
+	}),
+	failure: Schema.Union([
+		Schema.instanceOf(UserNotFound),
+		Schema.instanceOf(DatabaseError)
+	]),
+	failureMode: 'error'
+});
+
+type Error = Tool.Failure<typeof FindUser>;
+```
+
+**Key Pattern: failureMode**
+
+- `"error"` (default): Failures go to Effect error channel
+- `"return"`: Failures returned as tool result (captured, not thrown)
+
+### Tool with Service Dependencies
+
+```typescript
+import * as Tool from 'effect/unstable/ai/Tool';
+import * as Context from 'effect/Context';
+import { Schema } from 'effect';
+
+class Database extends Context.Service<
+	Database,
+	{
+		readonly query: (sql: string) => Effect.Effect<unknown>;
+	}
+>()('Database') {}
+
+const QueryDatabase = Tool.make('QueryDatabase', {
+	description: 'Execute a database query',
+	parameters: Schema.Struct({
+		sql: Schema.String
+	}),
+	success: Schema.Unknown,
+	dependencies: [Database]
+});
+
+type Requirements = Tool.Requirements<typeof QueryDatabase>;
+```
+
+**Key Pattern: dependencies**
+
+- Array of service tags
+- Requirements extracted at type level
+- Must be provided when creating handlers
+
+## Creating Toolkits
+
+### Basic Toolkit
+
+```typescript
+import * as Toolkit from 'effect/unstable/ai/Toolkit';
+import * as Tool from 'effect/unstable/ai/Tool';
+import { Effect, Schema } from 'effect';
+
+const GetCurrentTime = Tool.make('GetCurrentTime', {
+	description: 'Get the current timestamp',
+	success: Schema.Number
+});
+
+const GetWeather = Tool.make('GetWeather', {
+	description: 'Get weather for a location',
+	parameters: Schema.Struct({
+		location: Schema.String
+	}),
+	success: Schema.Struct({
+		temperature: Schema.Number,
+		condition: Schema.String
+	})
+});
+
+const MyToolkit = Toolkit.make(GetCurrentTime, GetWeather);
+
+type Tools = Toolkit.Tools<typeof MyToolkit>;
+```
+
+**Key Pattern: Toolkit.make**
+
+- Accepts variadic tool arguments
+- Returns `Toolkit<Record<Name, Tool>>`
+- Tools indexed by their name property
+
+### Implementing Tool Handlers
+
+```typescript
+import { Effect } from 'effect';
+
+const MyToolkitLayer = MyToolkit.toLayer({
+	GetCurrentTime: () => Effect.succeed(Date.now()),
+
+	GetWeather: ({ location }) =>
+		Effect.gen(function* () {
+			const data = yield* fetchWeatherData(location);
+			return {
+				temperature: data.temp,
+				condition: data.conditions
+			};
+		})
+});
+
+declare const fetchWeatherData: (location: string) => Effect.Effect<{
+	readonly temp: number;
+	readonly conditions: string;
+}>;
+```
+
+**Key Pattern: toLayer**
+
+- Object mapping tool names to handler functions
+- Handler signature: `(params, context) => Effect<Success, Failure, Requirements>`; `context.toolCallId` exposes the provider call ID when available, and `context.preliminary(...)` emits progress updates
+- Handler parameters are decoded `Tool.Parameters<T>` values
+- Returns `Layer<Handlers>`
+
+### Alternative: Handlers as Context
+
+```typescript
+import { Effect } from 'effect';
+
+const program = Effect.gen(function* () {
+	const handlers = yield* MyToolkit.toHandlers({
+		GetCurrentTime: () => Effect.succeed(Date.now()),
+
+		GetWeather: ({ location }) =>
+			Effect.gen(function* () {
+				const data = yield* fetchWeatherData(location);
+				return {
+					temperature: data.temp,
+					condition: data.conditions
+				};
+			})
+	});
+
+	const result = yield* Effect.provide(myEffect, handlers);
+	return result;
+});
+
+declare const fetchWeatherData: (location: string) => Effect.Effect<{
+	readonly temp: number;
+	readonly conditions: string;
+}>;
+
+declare const myEffect: Effect.Effect<unknown, never, Handlers>;
+```
+
+**Key Pattern: toHandlers**
+
+- Similar to toLayer but returns a `Context` instead of Layer
+- Use when you need direct handler context (not Layer composition)
+- Returns `Effect<Context<Handlers>>`
+- Provide directly to effects that require handlers
+
+### Providing Dependencies to Handlers
+
+```typescript
+import * as Context from 'effect/Context';
+import { Effect } from 'effect';
+
+interface WeatherData {
+	readonly temperature: number;
+	readonly condition: string;
+}
+
+class WeatherService extends Context.Service<
+	WeatherService,
+	{
+		readonly fetch: (location: string) => Effect.Effect<WeatherData>;
+	}
+>()('WeatherService') {}
+
+const GetWeatherWithDeps = Tool.make('GetWeather', {
+	parameters: Schema.Struct({
+		location: Schema.String
+	}),
+	success: Schema.Struct({
+		temperature: Schema.Number,
+		condition: Schema.String
+	}),
+	dependencies: [WeatherService]
+});
+
+const toolkit = Toolkit.make(GetWeatherWithDeps);
+
+const toolkitLayer = toolkit.toLayer({
+	GetWeather: ({ location }) =>
+		Effect.gen(function* () {
+			const service = yield* WeatherService;
+			const data = yield* service.fetch(location);
+			return {
+				temperature: data.temperature,
+				condition: data.condition
+			};
+		})
+});
+
+const program = Effect.gen(function* () {
+	const handlers = yield* toolkitLayer;
+	const resultStream = yield* handlers.handle('GetWeather', { location: 'NYC' });
+	return resultStream;
+}).pipe(Effect.provide(WeatherServiceLive));
+
+declare const WeatherServiceLive: Layer<WeatherService>;
+```
+
+**Key Pattern: Handler Context**
+
+- Handlers run with injected dependencies
+- Access via `yield* Tag` in Effect.gen
+- Dependencies must be provided to final effect
+
+## Dynamic Tools
+
+Use `Tool.dynamic` when tool schemas are discovered at runtime, such as from MCP or external configuration. If `parameters` is an Effect `Schema`, handlers receive typed decoded params; if `parameters` is raw JSON Schema, handler params are `unknown`.
+
+```typescript
+const TypedDynamic = Tool.dynamic('runtimeSearch', {
+	description: 'Search with a runtime-provided typed schema',
+	parameters: Schema.Struct({ query: Schema.String }),
+	success: Schema.Array(Schema.String)
+});
+
+type TypedParams = Tool.Parameters<typeof TypedDynamic>; // { query: string }
+
+const UntypedDynamic = Tool.dynamic('mcpTool', {
+	description: 'Runtime MCP tool with raw JSON Schema',
+	parameters: {
+		type: 'object',
+		properties: { query: { type: 'string' } },
+		required: ['query']
+	}
+});
+
+type UntypedParams = Tool.Parameters<typeof UntypedDynamic>; // unknown
+```
+
+## Registry-Owned Tool Resolution
+
+In production agent harnesses, resolve tools through a registry service instead of scattering direct imports across prompt/session code.
+
+The registry is the right place to:
+
+- initialize effect-built tools once
+- compute dynamic descriptions from permissions, config, or available subagents
+- expose stable named handles for orchestration and tests
+
+```typescript
+export namespace ToolRegistry {
+	export interface Interface {
+		readonly named: {
+			task: LocalToolInfo;
+			read: LocalToolInfo;
+		};
+	}
+}
+
+const registry = yield* ToolRegistry.Service;
+const task = yield* Effect.promise(() => registry.named.task.init());
+```
+
+Keep static descriptions on the tool for invariant behavior. Put runtime-specific descriptions and policy shaping in the registry layer.
+
+### Merging Toolkits
+
+```typescript
+import * as Toolkit from 'effect/unstable/ai/Toolkit';
+
+const mathToolkit = Toolkit.make(
+	Tool.make('add', {
+		parameters: Schema.Struct({ a: Schema.Number, b: Schema.Number }),
+		success: Schema.Number
+	}),
+	Tool.make('subtract', {
+		parameters: Schema.Struct({ a: Schema.Number, b: Schema.Number }),
+		success: Schema.Number
+	})
+);
+
+const utilityToolkit = Toolkit.make(
+	Tool.make('getCurrentTime', { success: Schema.Number }),
+	Tool.make('generateUUID', { success: Schema.String })
+);
+
+const combined = Toolkit.merge(mathToolkit, utilityToolkit);
+
+type AllTools = Toolkit.Tools<typeof combined>;
+```
+
+**Key Pattern: Toolkit.merge**
+
+- Combines multiple toolkits into one
+- Later toolkits override earlier ones on name collision
+- Type-safe union of all tools
+- **Note**: In v4, the preferred pattern is `Toolkit.make(tool1, tool2, ...)` — passing all tools to the constructor rather than merging separate toolkits. Use `Toolkit.make` with all tools when possible.
+
+## Provider-Defined Tools
+
+`Tool.providerDefined` models provider-native capabilities. For OpenAI, prefer the curated `OpenAiTool` constructors from `@effect/ai-openai` (`WebSearch`, `CodeInterpreter`, `FileSearch`, `ImageGeneration`, `Mcp`, plus handler-required local tools such as `Shell`, `LocalShell`, and `ApplyPatch`).
+
+### Basic Provider Tool
+
+```typescript
+import * as Tool from 'effect/unstable/ai/Tool';
+import { Schema } from 'effect';
+
+const AnthropicBash = Tool.providerDefined({
+	id: 'anthropic.bash',
+	customName: 'Bash',
+	providerName: 'bash_20241022',
+	args: Schema.Struct({
+		command: Schema.String
+	})
+});
+
+const bashTool = AnthropicBash({ command: 'ls -la' });
+
+type ToolType = typeof bashTool;
+```
+
+**Key Pattern: Tool.providerDefined**
+
+- Returns a function that accepts args
+- `id`: Unique identifier `<provider>.<tool-name>`
+- `customName`: Name used by Effect AI / Toolkit to identify this tool
+- `providerName`: Name recognized by the AI provider
+- `args`: Schema for provider-specific configuration arguments
+- `requiresHandler`: Set to `true` only when your application must execute/process provider tool calls locally
+
+### OpenAI Provider Tools
+
+```typescript
+import { OpenAiTool } from '@effect/ai-openai';
+
+const nativeTools = Toolkit.make(
+	OpenAiTool.WebSearch({}),
+	OpenAiTool.FileSearch({ vector_store_ids: ['vs_123'] }),
+	OpenAiTool.ImageGeneration({}),
+	OpenAiTool.Mcp({
+		server_label: 'docs',
+		server_url: 'https://mcp.example.com/mcp'
+	})
+);
+```
+
+`OpenAiTool.Mcp` uses the canonical custom name `OpenAiMcp`. Treat handler-required local OpenAI tools (`Shell`, `LocalShell`, `ApplyPatch`) as privileged operations: provide handlers only behind sandboxing, authorization, and audit policy.
+
+### Provider Tool with Handler
+
+```typescript
+import * as Tool from 'effect/unstable/ai/Tool';
+import { Schema } from 'effect';
+
+const WebSearch = Tool.providerDefined({
+	id: 'custom.web_search',
+	customName: 'WebSearch',
+	providerName: 'web_search',
+	args: Schema.Struct({
+		maxResults: Schema.Number
+	}),
+	requiresHandler: true,
+	parameters: Schema.Struct({
+		query: Schema.String
+	}),
+	success: Schema.Struct({
+		results: Schema.Array(
+			Schema.Struct({
+				title: Schema.String,
+				url: Schema.String,
+				snippet: Schema.String
+			})
+		)
+	})
+});
+
+const searchTool = WebSearch({ maxResults: 10, failureMode: 'return' });
+
+const toolkit = Toolkit.make(searchTool);
+
+const toolkitLayer = toolkit.toLayer({
+	WebSearch: ({ query }) =>
+		Effect.gen(function* () {
+			const results = yield* performSearch(query);
+			return { results };
+		})
+});
+
+declare const performSearch: (query: string) => Effect.Effect<
+	Array<{
+		readonly title: string;
+		readonly url: string;
+		readonly snippet: string;
+	}>
+>;
+```
+
+**Key Pattern: requiresHandler**
+
+- `false` (default): Provider executes tool completely
+- `true`: Your handler processes provider results
+- Handler receives `parameters` from provider
+
+## Tool Result Flow
+
+### Understanding ToolCallPart and ToolResultPart
+
+```typescript
+import * as Prompt from 'effect/unstable/ai/Prompt';
+
+const toolCallPart = Prompt.makePart('tool-call', {
+	id: 'call_123',
+	name: 'GetWeather',
+	params: { location: 'NYC' },
+	providerExecuted: false
+});
+
+const toolResultPart = Prompt.makePart('tool-result', {
+	id: 'call_123',
+	name: 'GetWeather',
+	result: {
+		temperature: 72,
+		condition: 'sunny'
+	},
+	isFailure: false
+});
+```
+
+**Key Pattern: Tool Call Flow**
+
+1. LLM generates `ToolCallPart` in response
+2. Your code runs `yield* toolkit.handle(...)` to get a `Stream` of handler results
+3. Preliminary results can be emitted for progress; the final result is authoritative
+4. Create a `ToolResultPart` from the final handler result for manual loops (LanguageModel does this automatically when tool resolution is enabled)
+5. Send the tool result back to the LLM
+
+### Approval Flow
+
+`Tool.make` and `Tool.dynamic` support `needsApproval`. When approval is needed, automatic tool resolution emits a `tool-approval-request` instead of executing the handler. The caller appends a `Prompt.toolApprovalResponsePart` in a tool message and calls the model again.
+
+```typescript
+const DeleteFile = Tool.make('DeleteFile', {
+	parameters: Schema.Struct({ path: Schema.String }),
+	success: Schema.Void,
+	needsApproval: true
+});
+
+// Replace an existing tool's static or dynamic approval policy.
+const DeleteFileWithoutApproval = DeleteFile.setNeedsApproval(false);
+
+const DeleteOutsideWorkspace = DeleteFile.setNeedsApproval(
+	({ path }, { toolCallId, messages }) =>
+		path.startsWith('/tmp/') ||
+		(toolCallId.length > 0 && messages.length === 0)
+);
+
+const approvalResponse = Prompt.toolApprovalResponsePart({
+	approvalId: 'approval_123',
+	approved: false,
+	reason: 'User denied deletion'
+});
+```
+
+Approved calls execute on the next model call; denied calls are converted to failed tool results with `{ type: 'execution-denied', reason }`.
+
+`setNeedsApproval` returns a cloned tool with the replacement policy. A dynamic policy receives decoded parameters plus `{ toolCallId, messages }` and may return either `boolean` or `Effect<boolean>`.
+
+### Executing Tool Handlers
+
+```typescript
+import { Effect, Stream } from 'effect';
+
+const program = Effect.gen(function* () {
+	const toolkit = yield* MyToolkitLayer;
+
+	const resultStream = yield* toolkit.handle('GetWeather', {
+		location: 'San Francisco'
+	});
+
+	yield* resultStream.pipe(
+		Stream.runForEach((result) =>
+			Effect.gen(function* () {
+				yield* Effect.log(result.preliminary ? 'progress' : 'final');
+				yield* Effect.log(result.isFailure);
+				yield* Effect.log(result.result);
+				yield* Effect.log(result.encodedResult);
+			})
+		)
+	);
+});
+
+interface HandlerResult<T> {
+	readonly isFailure: boolean;
+	readonly result: Result<T>;
+	readonly encodedResult: unknown;
+	readonly preliminary: boolean;
+}
+
+type Result<T> = Tool.Success<T> | Tool.Failure<T>;
+```
+
+Handlers can emit progress before the final result with `context.preliminary(...)`:
+
+```typescript
+const toolkitLayer = LongRunningToolkit.toLayer({
+	LongTask: (params, context) =>
+		Effect.gen(function* () {
+			yield* Effect.logDebug('handling tool call').pipe(
+				Effect.annotateLogs({ toolCallId: context.toolCallId })
+			);
+			yield* context.preliminary({ status: 'started' });
+			const result = yield* runLongTask(params);
+			return { status: 'done', result };
+		})
+});
+```
+
+**Key Pattern: toolkit.handle**
+
+- `toolkit.handle(name, params, toolCallId?)` accepts `Tool.ParametersEncoded<Tool>` and returns `Effect<Stream<HandlerResult<Tool>>>`
+- `handle` decodes the encoded input with the tool's parameter schema before invoking the handler; the handler still receives `Tool.Parameters<Tool>`
+- The optional call ID is forwarded to the handler as `context.toolCallId`
+- `preliminary: true`: progress update; do not persist as final history
+- `preliminary: false`: final result to send/persist
+- `isFailure`: Whether handler failed
+- `result`: Typed success or failure value
+- `encodedResult`: JSON-serializable for LLM
+
+The encoded/decoded distinction matters for transforming schemas:
+
+```typescript
+const Repeat = Tool.make('Repeat', {
+	parameters: Schema.Struct({ times: Schema.NumberFromString }),
+	success: Schema.Number
+});
+
+const RepeatToolkit = Toolkit.make(Repeat);
+const RepeatLive = RepeatToolkit.toLayer({
+	Repeat: ({ times }) => Effect.succeed(times + 1) // times is number
+});
+
+const program = Effect.gen(function* () {
+	const handlers = yield* RepeatToolkit;
+	return yield* handlers.handle('Repeat', { times: '3' }); // encoded input is string
+}).pipe(Effect.provide(RepeatLive));
+```
+
+Passing the decoded `{ times: 3 }` directly to `handle` is now a type error. Use the encoded boundary type and let `handle` perform the schema decode.
+
+## Advanced Patterns
+
+### Tool Annotations
+
+```typescript
+import * as Tool from 'effect/unstable/ai/Tool';
+import { Schema } from 'effect';
+
+const ReadOnlyQuery = Tool.make('query', {
+	parameters: Schema.Struct({ sql: Schema.String }),
+	success: Schema.Unknown
+})
+	.annotate(Tool.Readonly, true)
+	.annotate(Tool.Destructive, false)
+	.annotate(Tool.Idempotent, true);
+```
+
+**Available Annotations and Defaults:**
+
+- `Tool.Readonly`: Tool only reads data; default `false`
+- `Tool.Destructive`: Tool performs destructive operations; default `true`
+- `Tool.Idempotent`: Safe to call multiple times; default `false`
+- `Tool.OpenWorld`: Can handle arbitrary external data; default `true`
+- `Tool.Strict`: OpenAI strict JSON Schema override; default `undefined` so provider/config decides
+- `Tool.Title`: Human-readable title
+
+MCP emits the first four annotations as tool hints. They are hints, not authorization decisions. OpenAI function tools use `Tool.Strict` or `OpenAiLanguageModel.Config.strictJsonSchema` for strict mode.
+
+### JSON Schema Generation
+
+```typescript
+import * as Tool from 'effect/unstable/ai/Tool';
+
+const tool = Tool.make('example', {
+	parameters: Schema.Struct({
+		name: Schema.String,
+		age: Schema.optional(Schema.Number)
+	})
+});
+
+const jsonSchema = Tool.getJsonSchema(tool);
+```
+
+**Output:**
+
+```json
+{
+	"type": "object",
+	"properties": {
+		"name": { "type": "string" },
+		"age": { "type": "number" }
+	},
+	"required": ["name"],
+	"additionalProperties": false
+}
+```
+
+### Tool Guards
+
+```typescript
+import * as Tool from 'effect/unstable/ai/Tool';
+
+const userTool = Tool.make('example');
+const providerTool = Tool.providerDefined({
+	id: 'provider.tool',
+	customName: 'Example',
+	providerName: 'example',
+	args: Schema.Struct({})
+})({});
+
+Tool.isUserDefined(userTool);
+Tool.isProviderDefined(providerTool);
+```
+
+### Dynamic Tool Selection
+
+```typescript
+import { Effect, Match } from 'effect';
+
+const executeTool = (toolName: string, params: unknown) =>
+	Effect.gen(function* () {
+		const toolkit = yield* MyToolkitLayer;
+
+		const handler = Match.value(toolName).pipe(
+			Match.when('GetWeather', () =>
+				toolkit.handle('GetWeather', params)
+			),
+			Match.when('GetCurrentTime', () =>
+				toolkit.handle('GetCurrentTime', params)
+			),
+			Match.orElse(() =>
+				Effect.fail(new Error(`Unknown tool: ${toolName}`))
+			)
+		);
+
+		return yield* handler;
+	});
+```
+
+## Complete Example
+
+```typescript
+import * as Tool from 'effect/unstable/ai/Tool';
+import * as Toolkit from 'effect/unstable/ai/Toolkit';
+import { Effect, Schema, Layer, Stream } from 'effect';
+
+class UserNotFound extends Schema.TaggedError<UserNotFound>()(
+	'UserNotFound',
+	{
+		userId: Schema.String
+	}
+) {}
+
+class Database extends Context.Service<
+	Database,
+	{
+		readonly query: (sql: string) => Effect.Effect<unknown>;
+	}
+>()('Database') {}
+
+const GetUser = Tool.make('GetUser', {
+	description: 'Retrieve user information by ID',
+	parameters: Schema.Struct({
+		userId: Schema.String
+	}),
+	success: Schema.Struct({
+		id: Schema.String,
+		name: Schema.String,
+		email: Schema.String
+	}),
+	failure: Schema.instanceOf(UserNotFound),
+	failureMode: 'error',
+	dependencies: [Database]
+});
+
+const CreateUser = Tool.make('CreateUser', {
+	description: 'Create a new user',
+	parameters: Schema.Struct({
+		name: Schema.String,
+		email: Schema.String
+	}),
+	success: Schema.Struct({
+		id: Schema.String,
+		name: Schema.String,
+		email: Schema.String
+	}),
+	dependencies: [Database]
+});
+
+const GetCurrentTime = Tool.make('GetCurrentTime', {
+	description: 'Get the current Unix timestamp',
+	success: Schema.Number
+});
+
+const UserToolkit = Toolkit.make(GetUser, CreateUser, GetCurrentTime);
+
+const UserToolkitLive = UserToolkit.toLayer({
+	GetUser: ({ userId }) =>
+		Effect.gen(function* () {
+			const db = yield* Database;
+			const user = yield* db.query(
+				`SELECT * FROM users WHERE id = ?`,
+				userId
+			);
+
+			if (!user) {
+				return yield* Effect.fail(new UserNotFound({ userId }));
+			}
+
+			return user as { id: string; name: string; email: string };
+		}),
+
+	CreateUser: ({ name, email }) =>
+		Effect.gen(function* () {
+			const db = yield* Database;
+			const id = crypto.randomUUID();
+
+			yield* db.query(
+				`INSERT INTO users (id, name, email) VALUES (?, ?, ?)`,
+				id,
+				name,
+				email
+			);
+
+			return { id, name, email };
+		}),
+
+	GetCurrentTime: () => Effect.succeed(Date.now())
+});
+
+const DatabaseLive = Layer.succeed(Database, {
+	query: (sql: string, ...params: ReadonlyArray<unknown>) =>
+		Effect.logInfo(`Query: ${sql}`).pipe(Effect.as({}))
+});
+
+const program = Effect.gen(function* () {
+	const toolkit = yield* UserToolkitLive;
+
+	const createStream = yield* toolkit.handle('CreateUser', {
+		name: 'Alice',
+		email: 'alice@example.com'
+	});
+
+	yield* createStream.pipe(
+		Stream.runForEach((result) => Effect.log('Created user:', result.result))
+	);
+
+	const getStream = yield* toolkit.handle('GetUser', {
+		userId: 'user-123'
+	});
+
+	yield* getStream.pipe(
+		Stream.runForEach((result) => Effect.log('Retrieved user:', result.result))
+	);
+
+	const timeStream = yield* toolkit.handle('GetCurrentTime', {});
+
+	yield* timeStream.pipe(
+		Stream.runForEach((result) => Effect.log('Current time:', result.result))
+	);
+}).pipe(Effect.provide(DatabaseLive));
+```
+
+## Import Patterns
+
+**CRITICAL**: Always use namespace imports:
+
+```typescript
+import * as Tool from 'effect/unstable/ai/Tool';
+import * as Toolkit from 'effect/unstable/ai/Toolkit';
+import * as Prompt from 'effect/unstable/ai/Prompt';
+import { Schema, Effect, Data, Context, Layer } from 'effect';
+
+const myTool = Tool.make('example');
+const myToolkit = Toolkit.make(myTool);
+```
+
+**NEVER** do this:
+
+```typescript
+import { make } from 'effect/unstable/ai/Tool';
+import { make as makeToolkit } from 'effect/unstable/ai/Toolkit';
+```
+
+## Quality Checklist
+
+### Mandatory - Every Tool
+
+- [ ] Tool name is descriptive and unique
+- [ ] Description explains what the tool does
+- [ ] Parameters use `Schema.Struct(...)` or another `Schema.Top` schema (not raw field objects)
+- [ ] Success schema matches handler return type
+- [ ] Failure schema includes all tagged errors
+- [ ] failureMode matches recovery strategy
+- [ ] Dependencies declared if accessing services
+- [ ] Handler implements correct signature
+- [ ] Type signatures use Tool.Parameters, Tool.Success, Tool.Failure
+
+### Conditional - Include When Appropriate
+
+- [ ] Tool.Readonly annotation for read-only tools
+- [ ] Tool.Destructive annotation for mutating operations
+- [ ] Tool.Idempotent annotation for safe retries
+- [ ] Custom annotations via Tool.annotate
+- [ ] Provider-defined tools for native provider features
+- [ ] Toolkit.make with all tools (preferred in v4) or Toolkit.merge for combining tool collections
+- [ ] Error handling with catchTag in handlers
+
+## Common Patterns
+
+### Validation in Handlers
+
+```typescript
+const ValidatedTool = Tool.make('validate', {
+	parameters: Schema.Struct({
+		input: Schema.String
+	}),
+	success: Schema.Struct({
+		valid: Schema.Boolean,
+		errors: Schema.Array(Schema.String)
+	})
+});
+
+const toolkit = Toolkit.make(ValidatedTool);
+
+const toolkitLayer = toolkit.toLayer({
+	validate: ({ input }) =>
+		Effect.gen(function* () {
+			const errors: Array<string> = [];
+
+			if (input.length < 3) {
+				errors.push('Input too short');
+			}
+
+			if (!/^[a-z]+$/.test(input)) {
+				errors.push('Input must be lowercase letters');
+			}
+
+			return {
+				valid: errors.length === 0,
+				errors
+			};
+		})
+});
+```
+
+### Async Operations in Handlers
+
+```typescript
+const FetchTool = Tool.make('fetch', {
+	parameters: Schema.Struct({
+		url: Schema.String
+	}),
+	success: Schema.String
+});
+
+const toolkit = Toolkit.make(FetchTool);
+
+const toolkitLayer = toolkit.toLayer({
+	fetch: ({ url }) =>
+		Effect.tryPromise({
+			try: () => fetch(url).then((r) => r.text()),
+			catch: (error) => new Error(`Fetch failed: ${error}`)
+		})
+});
+```
+
+### Conditional Tool Execution
+
+```typescript
+const ConditionalTool = Tool.make('process', {
+	parameters: Schema.Struct({
+		mode: Schema.Literals(['fast', 'thorough'])
+	}),
+	success: Schema.String
+});
+
+const toolkit = Toolkit.make(ConditionalTool);
+
+const toolkitLayer = toolkit.toLayer({
+	process: ({ mode }) =>
+		mode === 'fast'
+			? Effect.succeed('Fast result')
+			: Effect.gen(function* () {
+					yield* Effect.sleep('1 second');
+					return 'Thorough result';
+				})
+});
+```
+
+## When to Use This Skill
+
+- Building LLM integrations with tool calling
+- Creating type-safe AI agent capabilities
+- Implementing function calling for Claude/OpenAI
+- Defining validated tool parameters and results
+- Composing multiple tools into toolkits
+- Managing tool handler dependencies
+- Integrating provider-native tools (bash, web search)
+
+## Key Principles Summary
+
+1. **Tool.make** - Define user tools with parameters, success, and failure schemas
+2. **Tool.dynamic** - Define runtime-discovered tools; raw JSON Schema params are `unknown`
+3. **Tool.providerDefined / OpenAiTool** - Use provider-native tools with `customName`
+4. **Parameters** - `Tool.make` takes `Schema.Top` schemas such as `Schema.Struct(...)`; raw JSON Schema belongs with `Tool.dynamic`
+5. **Toolkit.make** - Compose multiple tools together
+6. **toLayer** - Implement handlers returning Layer
+7. **toHandlers** - Implement handlers returning Context
+8. **toolkit.handle** - Execute tools and consume a Stream of preliminary/final results
+9. **ParametersEncoded** - Pass encoded schema input to `handle`; handlers receive decoded `Parameters`
+10. **HandlerResult** - Access typed result, encoded JSON, failure flag, and preliminary flag
+11. **needsApproval** - Produces approval requests until caller supplies approval responses
+12. **setNeedsApproval** - Clone a tool with a replacement static or effectful approval policy
+13. **toolCallId** - Pass the call ID through `toolkit.handle` and read it from handler context
+14. **failureMode** - Control error vs return failure strategy
+15. **dependencies** - Declare service requirements
+16. **Namespace imports** - Always `import * as Tool`
+17. **Prompt.makePart** - Create tool-call, tool-result, and approval parts with params
+
+Your tool implementations should be type-safe, validated, and provide excellent developer experience with full schema support.
+
+## Related Skills
+
+- effect-ai-language-model - Using tools with generateText/streamText
+- effect-ai-prompt - Tool call/result message integration
+- effect-ai-streaming - Processing tool call streams
+- effect-ai-provider - Provider-defined tools