Tools are the boundary between model suggestions and application effects. Effect AI owns their
schemas and handler Layers; your application owns resource access and the meaning of each action.
Yielded Agent validates calls, applies policy, and runs bounded batches.
Creates a user-defined tool with the specified name and configuration.
Details
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.
If a tool accepts no parameters but still needs an explicit empty object
schema, use
EmptyParams
.
Example (Creating a tool without parameters)
import{ Schema }from"effect"
import{ Tool }from"effect/ai"
// Simple tool with no parameters
constGetCurrentTime=Tool.make("GetCurrentTime",{
description:"Returns the current timestamp",
success:Schema.Number
})
GetCurrentTime.name// => "GetCurrentTime"
@stability ― unstable
@category ― constructors
@since ― 4.0.0
make("search_activities",{
description?:string|undefined
An optional description explaining what the tool does.
description:"Find activities in a city.",
parameters?:Schema.Struct<{
readonlycity:Schema.String;
}>|undefined
Schema defining the parameters this tool accepts.
parameters:
importSchema
Schema.
functionStruct<{
readonlycity:Schema.String;
}>(fields:{
readonlycity:Schema.String;
}):Schema.Struct<{
readonlycity:Schema.String;
}>
Defines a struct schema from a map of field schemas.
Details
Each field value is a schema. Use
optionalKey
or
optional
to
mark fields as optional, and
mutableKey
to mark them as mutable.
The resulting schema's Type is a readonly object type with the fields'
decoded types. The Encoded form mirrors the field schemas' encoded types.
Declared fields may be inherited and are copied to own properties in the
output. The __proto__ field is accepted only when it is an own property.
Parsing does not guarantee that output keys retain their input order.
This is the primary constructor for creating toolkits. It accepts multiple
tools and organizes them into a toolkit that can be provided to AI language
models.
Set the Agent’s toolkit to TravelTools and provide TravelToolsLive alongside the model Layer.
Replace the sample data with an application service; its errors and dependencies remain visible
in Effect. The travel-planner snippets
show complete composition.
The engine validates the complete response before starting application handlers. Calls execute
with bounded concurrency; progress can arrive in completion order, while committed results retain
the model’s declaration order. The next model request sees the complete batch.
Use execution budgets to bound turns, calls, output, and concurrency.
Large results are bounded before they enter history or the next prompt.
A declared failure Schema describes expected errors. By default, failureMode: "error"
propagates those errors and fails the Run. Set failureMode: "return" when the model should
receive a failed tool result and try another approach. Invalid native tool arguments can then
return a validation failure without starting the handler. Defects, interruption, and invalid
result encoding still fail.
Treat an empty search result as successful data, such as an empty array.
Install RunToolAuthorization for action-time policy. It checks executable application calls
before handlers start, including programmatic calls from Code Mode.
Durable recovery checks authorization again for unfinished calls. The host must supply actual
caller authority; model-provided identifiers are untrusted. Handlers still enforce access to
the specific resources they use.
Effect AI tools can require approval. A pending approval prevents the handler from starting;
a durable host retains the request and accepts an authorized resolution later. An approval is
a decision about the proposed call, not permission to bypass current resource authorization.
Never infer approval from model prose.
ToolExposure limits declarations sent to a model, and ToolDiscovery lets it search an eligible
catalogue. Host visibility and inherited subagent grants constrain both discovery and execution.
Selection changes what the model sees; it grants no additional authority. Use this when a large
toolkit would crowd out task context. ToolDiscovery.make provides bounded literal search.
For custom ranking, define a native Tool with DiscoveryTool and
ToolExecutionClass: "readonly", read CurrentToolCatalog, and use
Schema.Struct({ toolNames: ToolNames }) as its success schema.
Unannotated tools have execution class "uncertain". If an external effect may have happened but
its result was not recorded, durable recovery records Unknown and does not automatically repeat
it. Resolve the outcome from external evidence before continuing.
Declare "readonly" or "idempotent" only when the handler satisfies that contract. A
DurableStep can retain named results across retries, but its body may execute again. Use the
external system’s idempotency or reconciliation API; Steps do not guarantee exactly-once effects.
See durability.
Use effect/ai/McpClient for MCP connections and discovery. Acquire the client in a Scope
and bind selected remote calls through ordinary Toolkit handlers. Its callTool operation
can decode structured output with the application’s Schema; declare McpClientError from
effect/ai/McpClientError as the Tool’s failure schema when returning remote failures to the model.
Keep the client Scope open while its tool handlers can run, and configure transport and
discovery limits through Effect’s APIs.
Remote calls follow the same authorization, approval, budgets, and uncertainty rules as other
tools. Leave their execution class "uncertain" unless the application can establish a stronger
contract; server hints alone do not establish replay safety.