effect-ai-tool

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

Effect<A, E, R>
       ↓
Tool<Name, Config, Requirements>

Config := {
  parameters: Schema.Struct<Fields>
  success: Schema<A>
  failure: Schema<E>
  failureMode: "error" | "return"
}

Toolkit Flow

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.

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));
			}
		};
	})
);