The Open Framework for Building Agents
title: "Built-in Tools" description: "The default and opt-in tools eve provides, including glob, grep, and sleep."
eve provides a default tool set for every agent and additional tools you can add with one file. Each default occupies the same agent/tools/<name>.ts slot you would author yourself, so an authored definition replaces it and disableTool() removes it. Use this page to review what the model can call, opt into more capabilities, or override and disable defaults. For custom tools, see Tools.
Default tools
Default tools require no imports. The exact set depends on the agent and session, and the harness advertises only the tools available to the current session.
Disable optional default tools
Optional default tools are enabled unless you set defaultTools: false in agent/agent.ts:
import { defineAgent } from "eve";
export default defineAgent({
defaultTools: false,
model: "openai/gpt-5.4",
});
This turns off the optional defaults described below. Add back only the tools the agent needs with the command in each tool's section. Existing files under agent/tools/ remain available, including same-name replacements such as agent/tools/bash.ts.
defaultTools doesn't affect the catalog tools: eve adds them from what the session can reach, as listed in that section.
bash
bash runs shell commands in the agent's sandbox.
eve add tool/bash
export { default } from "eve/tools/bash";
bash waits up to 30 seconds for a command. A command that finishes in time returns status: "completed" with exitCode, stdout, stderr, and truncated. A command that is still running keeps running in the sandbox as its own process group and returns status: "running" with:
pid: the process group idoutputDirectory: a directory under/tmp/.eve/jobs/stdout,stderr, andtruncated: the output so farmessage: instructions for the model
The command keeps writing to stdout and stderr files in outputDirectory and writes its exit code to an exit file when it finishes. The model checks on or stops it with ordinary shell commands in later bash calls, so the tool's approval policy applies to them:
tail /tmp/.eve/jobs/3f9a1c2e/stdout # latest output
cat /tmp/.eve/jobs/3f9a1c2e/exit # exit code, once the command has finished
kill -- -4312 # stop the command's whole process group
The command keeps running across turns until it exits, the model stops it, or the sandbox stops. Its output files stay in the sandbox until the sandbox stops. Cancelling a turn stops a command that has not yet returned running. The just-bash provider has no background processes, so it runs every command to completion.
Override its description, approval policy, or executor by wrapping the exported definition:
import { defineTool } from "eve/tools";
import { bash } from "eve/tools/bash";
export default defineTool({
...bash,
description: "Run approved project maintenance commands.",
async execute(input, ctx) {
console.info("Running sandbox command", input.command);
return bash.execute(input, ctx);
},
});
Disable only bash:
import { disableTool } from "eve/tools";
export default disableTool();
read_file
read_file reads text files from the sandbox with line-numbered output, and shows PNG, JPEG, GIF, and WebP images up to 3 MiB and 8000 pixels per side, and PDFs up to 20 MiB, to the model as files. Images and PDFs are detected from their bytes, so a missing or mismatched filename extension does not matter, and other text files are always read as text. It accepts absolute paths, paths relative to the workspace root where bash commands start, and paths beginning with $HOME/. Results and errors name the resolved absolute path.
eve add tool/read_file
export { default } from "eve/tools/read_file";
Override it:
import { defineTool } from "eve/tools";
import { readFile } from "eve/tools/read_file";
export default defineTool({
...readFile,
description: "Read project files from the sandbox.",
});
Disable it:
import { disableTool } from "eve/tools";
export default disableTool();
write_file
write_file writes complete files in the sandbox. It enforces read-before-write and stale-read detection, and accepts the same paths as read_file.
eve add tool/write_file
export { default } from "eve/tools/write_file";
Override it:
import { defineTool } from "eve/tools";
import { writeFile } from "eve/tools/write_file";
export default defineTool({
...writeFile,
description: "Write notes in the sandbox's notes directory.",
async execute(input, ctx) {
const sandbox = await ctx.getSandbox();
const notes = `${sandbox.resolvePath("notes")}/`;
if (
input.filePath.startsWith("$HOME") ||
!sandbox.resolvePath(input.filePath).startsWith(notes)
) {
throw new Error("write_file is limited to the notes directory");
}
return writeFile.execute(input, ctx);
},
});
Disable it:
import { disableTool } from "eve/tools";
export default disableTool();
web_fetch
web_fetch fetches URLs from the app runtime. It follows up to ten redirects and checks every destination for SSRF safety. Non-success responses return plain text with the response body when available.
eve add tool/web_fetch
export { default } from "eve/tools/web_fetch";
Override it:
import { defineTool } from "eve/tools";
import { webFetch } from "eve/tools/web_fetch";
export default defineTool({
...webFetch,
description: "Fetch approved public documentation URLs.",
async execute(input, ctx) {
const hostname = new URL(input.url).hostname;
if (hostname !== "docs.example.com") {
throw new Error("web_fetch is limited to docs.example.com");
}
return webFetch.execute(input, ctx);
},
});
Disable it:
import { disableTool } from "eve/tools";
export default disableTool();
web_search
web_search uses provider-managed web search and appears only for supported model providers. AI Gateway models use Exa by default; direct provider models use their native search implementation.
eve add tool/web_search
export { default } from "eve/tools/web_search";
Override the provider-managed configuration for AI Gateway:
import { webSearch } from "eve/tools/web_search";
export default webSearch({ provider: "parallel" });
Select Browserbase Search in the same slot:
import { webSearch } from "eve/tools/web_search";
export default webSearch({ provider: "browserbase" });
Use a Gateway model ID to route searches through Browserbase. AI Gateway executes the search using AI_GATEWAY_API_KEY or Vercel project OIDC credentials; no BROWSERBASE_API_KEY is needed. See Browserbase Search on AI Gateway.
Select the model vendor's own hosted search for a model routed through AI Gateway:
import { webSearch } from "eve/tools/web_search";
export default webSearch({ provider: "native" });
The vendor runs the search server-side and returns citations: OpenAI models use OpenAI web search, Anthropic models use Anthropic web search, and Gemini 3 and later models use Google Search grounding. AI Gateway uses its usual credentials, so no OPENAI_API_KEY, ANTHROPIC_API_KEY, or Google key is needed. Every other Gateway model, including one picked by a dynamic model resolver, doesn't get web_search. That includes Gemini models before Gemini 3, which can't use Google Search alongside other tools.
eve picks the search tool from the requested model, so when AI Gateway's own models fallback serves a call with a model from another vendor, that call can run without search. Anthropic web search runs only on Anthropic's own API. AI Gateway tries another host when Amazon Bedrock or Google Vertex AI rejects the tool. If no host accepts it, eve retries the step without web_search.
Set fallback to give models without native search a provider that works with any Gateway model ("exa", "parallel", or "browserbase"):
import { webSearch } from "eve/tools/web_search";
export default webSearch({ provider: "native", fallback: "exa" });
The provider setting applies only to AI Gateway models. Direct OpenAI, Anthropic, and Gemini 3 and later models always use their native search; other direct models omit web_search.
eve identifies a direct model's vendor by its AI SDK provider name, so a createOpenAI() model pointed at an OpenAI-compatible endpoint, such as Amazon Bedrock's, gets OpenAI web search. When the endpoint rejects it, eve retries the step without web_search, so each step makes one rejected call first. To skip it, give the provider its own name:
import { createOpenAI } from "@ai-sdk/openai";
import { defineAgent } from "eve";
const mantle = createOpenAI({
name: "mantle",
baseURL: "https://bedrock-mantle.us-east-1.api.aws/openai/v1",
apiKey: process.env.BEDROCK_API_KEY,
});
export default defineAgent({ model: mantle("openai.gpt-5.6-sol") });
The agent then gets no web_search, the same as other direct models without native search.
Replace provider-managed search with an authored implementation:
import { defineTool } from "eve/tools";
export default defineTool({
description: "Search the internal documentation index.",
inputSchema: { type: "object" },
async execute(input) {
return { results: [], query: input };
},
});
Disable it:
import { disableTool } from "eve/tools";
export default disableTool();
agent
agent delegates a subtask to a fresh copy of the root agent. It is root-only, and each call is a task: the call returns a receipt, and the child's reply arrives later as the task's result. The child receives the root's instructions, tools, connections, and sandbox, but starts with fresh conversation history and state. See Subagents.
eve add tool/agent
export { default } from "eve/tools/agent";
To let the model choose an AI Gateway model for each root-copy task, export agentWithModel from the same slot:
export { agentWithModel as default } from "eve/tools/agent";
This is a separate workflow tool that calls ctx.agent("agent", { model }). The default agent tool remains unchanged and does not gain a model parameter. The opt-in definition accepts:
{
message: string;
model: string; // AI Gateway model id for the child session
taskId?: string;
}
It otherwise has the default tool's task behavior: a call returns a receipt, the result arrives later, and taskId continues the same root-copy session. The selected model applies to every turn in that session. A continuation must repeat the original model; start a new task to use another one. Because the parent model controls this value, use this tool only when it may choose among every model your AI Gateway credentials and policies allow.
An authored tool at agent/tools/agent.ts replaces the framework behavior. Re-export the default definition above to restore direct root-copy delegation, export agentWithModel to expose model selection, export another tool such as agentRouter() to change the model-facing behavior, or disable the slot. agentRouter() runs each call as a task, which adds eve__task_wait and eve__task_cancel:
import { disableTool } from "eve/tools";
export default disableTool();
eve__search, eve__tool, and eve__skill
These tools let the model reach what isn't in its tool list. eve__search finds tools defined with deferred: true, agents defined with tool: "deferred", every tool from the agent's connections, and deferred skills. eve__tool calls a deferred tool, agent, or connection tool by name, and eve__skill loads a skill, deferred or not. There is no add command; eve adds each one when the session has something it reaches, even when defaultTools is false:
eve__toolcomes with anything it can call: a deferred tool or agent, or a connection.eve__skillcomes with any skill, so an agent whose only catalog entries are listed skills getseve__skillalone.eve__searchcomes with anything it could find: whatevereve__toolcan call, plus deferred skills.- A session with none of these gets no catalog tools.
Entries the agent declares count from the session's first step. An entry a dynamic resolver returns counts from the step where it first appears, so a resolver in agent/tools/ that returns only tools without deferred: true adds no catalog tools. Once a session's tool list includes a catalog tool, the session keeps it, even after a resolver stops returning the entry that brought it. The catalog tools change only when the session first reaches a new kind of entry, such as its first deferred tool or its first connection.
eve__search({ query, limit? })returns the best matches, up tolimit(default 10, at most 50).queryis required and must contain a word. A tool match has its exacttoolname, itsdescription, and a TypeScriptsignaturerendered from its schemas. A very long signature drops its property descriptions before any property name. A deferred skill's match has itsskillname, itsdescription, and thepathof itsSKILL.mdwhen it has supporting files. A result withtoolis called witheve__tool, and one withskillis loaded witheve__skill. Next toresults,searchedcounts the entries the query covered, the whole catalog or one namespace, andremainingcounts the matches pastlimit. A connection behind sign-in counts as its one sign-in result until the user signs in, and an unavailable connection counts as none. Tools and skills rank together, in tiers: an entry whose name is exactly the query, then one whose name after its last__is the query, such aslinear__create_issueorsre__create_issueforcreate_issue, then the tools of a connection named by the query, then entries whose names, or names after their last__, start with the query, then keyword matches in names, parameters, and descriptions. Soeve__search({ query: "linear" })lists thelinearconnection's tools first. One-letter and filler words such asaandthedon't count toward keyword matches unless the query has nothing else.- A query whose first word contains
__searches one namespace: everything before its last__, without trailing underscores. The namespace only filters.eve__searchkeeps names under<namespace>__and anything named exactly the namespace, such as a connection's sign-in entry, then ranks them by the whole query, soeve__search({ query: "linear__" })returns only thelinearconnection's tools, or its sign-in result, and an exact name that contains__still ranks first. eve lists only the connections that can own names in that namespace, so other connections make no network call and don't appear inunavailable. A namespace that matches nothing fails with the closest connection names. Characters that can't appear in a name, such as a leading^, are ignored;queryisn't a regular expression. eve__searchnever asks the user to sign in. A connection whose server won't list its tools until the user signs in appears as one result named after the connection, such aslinear; a connection whose server lists its tools without a token is searched like any other. A connection whose tools fail to load, or don't load within 10 seconds, appears underunavailablewith itserror, such as"crm" did not list its tools within 10s. Try again later.Matches from everything else are still returned, so a slow server doesn't hold up the search. Aneve__toolcall on that connection's tools fails with the same error.eve__tool({ name: "linear" }), with a connection's own name, asks the user to sign in to that connection when its tools need it, and returns once they can be listed, so the nexteve__searchfinds them. On a server that lists its tools without sign-in, it confirms the tools are available without asking.eve__tool({ name, input? })calls the entry namednamewithinput, which defaults to{}. A connection tool's name is<connection>__<tool>, such aslinear__list_issues. eve checksinputagainst the entry's input schema. An invalid input fails with the entry's signature, an unknown name fails with the closest names, and a skill's name fails with a reminder to load it witheve__skill. When the server asks for the user's authorization, the call asks the user to sign in and parks until sign-in completes.eve__skill({ name })loads the named skill, deferred or not, and returns its instructions. An unknown name fails with the closest skill names, a tool's name fails with a reminder to call it witheve__toolor directly, and a name that matches a connection says to find its tools witheve__search({ query: "<connection>__" }).
After eve__tool or eve__skill resolves its entry, the call runs exactly like a direct call to that entry. A skill load reports a load-skill action and a load-skill-result, both with the skill's name, and an execute_tool eve:load-skill span. Approval policies and approvedTools, workflow tools and tasks, agents, endsTurn, toModelOutput, hooks, and stream events all see the entry's own name and input, such as linear__list_issues. Only model history records the call as eve__tool or eve__skill.
eve tells the model what it can reach in an append-only context message rather than in the system prompt: which kinds of deferred entries exist, up to 20 namespaces (the first __ segment of deferred names, such as sre for sre__list_alerts), and up to 20 connections with their descriptions. It never names a deferred entry, so deferred entries stay out of context until eve__search finds them. A later step appends the listing again only when that changes; a deferred entry added to a listed namespace, or without one, changes nothing. After the session first reaches each kind of entry, adding or removing entries, signing in, or resolving more dynamic connections doesn't change the catalog tools, so the cached prompt prefix holds.
The tools eve adds itself all live in the eve namespace: eve__search, eve__tool, eve__skill, eve__task_wait, eve__task_cancel, and eve__reply. Nothing you author or resolve may be named eve or start with eve__: tools, subagents, skills, connections, and extension mounts, static or dynamic, since a connection or mount named eve would own every eve__ name. The compiler rejects an authored tool, skill, connection, or mount, such as agent/tools/eve__search.ts; eve rejects an authored subagent when the agent loads, and a dynamic entry when its resolver returns it. Any other name is free, including search and execute. A connection's own name is also the entry that signs the user in to it.
eve__task_wait and eve__task_cancel
eve adds eve__task_wait and eve__task_cancel when the agent has a tool that runs its calls as tasks: any agent tool, including the built-in agent tool, declared subagents, and remote agents, or a tool such as agentRouter(), the workflow tool, or an authored workflow tool that defines task(input, ctx) or serve(receive, ctx). There is no add command, and the tools are not workflow tools. Like every eve__ name, both are reserved.
eve__task_wait({ timeoutSeconds? })parks the turn until any task has a result, a new message arrives, ortimeoutSecondspass, and returns at once when a result is already waiting. While it waits, the stream reportsturn.waitingfor the open turn. Results arrive in a<task_result>message right after it returns. Waiting never stops a task.eve__task_cancel({ taskId })stops a task's current work and says so, or says the task had no work to stop when it already finished or is an idle resumable task. An id that names no task fails withUNKNOWN_TASK. A resumable task stays available after a cancel.
Review these tools before production use. Disable, wrap, restrict, or require approval for any tool that can access the filesystem, network, shell, or sensitive data.
You can also add the opt-in framework tools described below.
Opt-in framework tools
These framework-provided tools are not added by default. Add only the ones the agent needs.
ask_question
ask_question lets the model ask the user one question, then waits for the answer. The model can offer two or three options, each with a label and a short description, and the user can always type their own answer instead. Channels render the options as native UI, such as Slack select menus. Without the tool, the model can still ask in its reply text and the user answers with their next message. See Human-in-the-loop. Add it:
eve add tool/ask_question
import { askQuestion } from "eve/tools/ask_question";
export default askQuestion();
ask_question is a workflow tool that calls ctx.ask(). The model receives { status: "answered", answer }, where answer is the chosen option's label or the user's own words. A plain follow-up message answers the question too when it is the first open request and the message matches an option or the question allows free text; see Several requests at once. A steering message that doesn't answer it withdraws the question: ask_question resolves as { interrupted: true }, which the model reads as Stopped early because a new message arrived., and the model reads the message next. In a session that cannot request input, such as a markdown schedule, the result is { status: "unavailable" } and the model continues on its own judgment. Remove the file to remove the tool.
glob
glob finds sandbox files by glob pattern. It searches the workspace root unless the model passes a directory, which accepts the same paths as read_file. Add it:
eve add tool/glob
export { default } from "eve/tools/glob";
Customize it by wrapping the framework definition:
import { defineTool } from "eve/tools";
import { glob } from "eve/tools/glob";
export default defineTool({
...glob,
description: "Find project files by glob pattern.",
});
Remove the file to remove the tool. disableTool() is unnecessary because glob is not added by default.
grep
grep searches sandbox file contents with a regular expression. It searches the workspace root unless the model passes a directory or file, which accepts the same paths as read_file. Add it:
eve add tool/grep
export { default } from "eve/tools/grep";
Customize it by wrapping the framework definition:
import { defineTool } from "eve/tools";
import { grep } from "eve/tools/grep";
export default defineTool({
...grep,
description: "Search project files with a regular expression.",
});
Remove the file to remove the tool. disableTool() is unnecessary because grep is not added by default.
no_reply
no_reply ends the turn without a reply. Use it when a scheduled check finds nothing to report, or when an action the agent already took is the whole answer. The model calls it with an optional { reason }, which stays in the session history and traces and is never sent. The turn completes without a final message, so channels and schedule sends post nothing, and later turns see that the agent chose to stay quiet. Add it:
eve add tool/no_reply
import { noReply } from "eve/tools/no_reply";
export default noReply();
no_reply is a defineTool tool with endsTurn: true, so the turn ends only when no other tool runs in the same step. Only root sessions receive it. Slack clears the thread status when the turn completes. Remove the file to remove the tool.
A root session also accepts a successful model call that returns no text with finishReason: "stop", without retrying or reporting a model-call failure. A turn that settles with no text completes without a final message. Use no_reply when the agent should record an explicit choice to stay quiet, including an optional reason. Delegated sessions still retry an empty reply once and report a failure if it remains empty, so the caller can act on the failure.
sleep
sleep pauses and durably resumes the current turn. The model calls it with { seconds }; the wait does not hold an application runtime open. Concurrent calls run in parallel, and the turn resumes after the longest wait. A steering message, the default for a new message, ends the wait early: sleep returns { interrupted: true }, which the model reads as Stopped early because a new message arrived., followed by the message. Add it:
eve add tool/sleep
import { sleep } from "eve/tools/sleep";
export default sleep();
Customize it by wrapping the framework definition:
import { defineWorkflowTool } from "eve/tools";
import { sleep } from "eve/tools/sleep";
export default defineWorkflowTool({
...sleep(),
description: "Pause before checking an external operation again.",
});
Remove the file to remove the tool. disableTool() is unnecessary because sleep is not added by default.
What to read next
- Tools: define your own tools, gate them on approval, and shape their output with
toModelOutput - Dynamic capabilities: generate the tool set per session with
defineDynamic - Sandbox: configure the sandbox used by shell and file tools
- Subagents: declare specialists that the model can delegate to