The Open Framework for Building Agents
issue: TBD status: proposed last_updated: "2026-10-08"
Deferred tools and skills
Summary
Agents tend to score better on evals when every tool and skill lives on the main agent, so the model doesn't have to hand each specialized task to a subagent. Large teams push that until the tool list and skill list fill the context. A few hundred tool definitions cost tens of thousands of tokens on every request, and the model starts picking the wrong tool. One popular MCP server alone, Playwright, spends 13.7k tokens on 21 tools (source).
This doc proposes a catalog of deferred capabilities that the model reaches
through three fixed tools, eve__search, eve__tool, and eve__skill:
eve__search(opts: {
query: string;
limit?: number; // default 10, at most 50
}): Promise<{
results: Array<
| { tool: string; description: string; signature: string } // call with eve__tool
| { skill: string; description: string; path?: string } // load with eve__skill
>;
unavailable?: Array<{ connection: string; error: string }>;
}>;
eve__tool(opts: { name: string; input?: object }): Promise<unknown>;
eve__skill(opts: { name: string }): Promise<string>;
One opt-in.
- A tool sets
deferred: trueondefineToolordefineWorkflowTool. - A subagent sets
tool: "deferred"on itsdefineAgent. - A skill sets
deferred: truein itsSKILL.mdfrontmatter or ondefineSkill.
Each works for static and dynamic entries. Connection tools are always deferred.
- A tool sets
eve__searchandeve__toolreplaceconnection_searchandconnection_execute, andeve__skillreplacesload_skill. There is one catalog for everything, and noskill_search.One dispatch path.
eve__toolandeve__skilllook the entry up and run it exactly like a direct call:- an inline tool runs inline;
- a workflow tool starts its run;
- a subagent starts its child session;
- a connection tool calls its connection;
eve__skillloads a skill, deferred or not, with today'sload-skillaction.
Registered from declarations. Each tool comes with what it reaches:
eve__toolwith a deferred tool or agent, a connection, or a dynamic tool, subagent, or connection resolver;eve__skillwith any skill, static or dynamic; andeve__searchwith anything it could find, which is whatevereve__toolcalls plus deferred skills and dynamic skill resolvers. An agent with only listed skills getseve__skillalone,main'sload_skillrenamed; with none of these, no catalog tools. The rule reads what the agent declares, never what its resolvers return, so entries, static or dynamic, can join or leave the catalog at any step without changing thetoolsarray.Cache stable. Catalog entries never enter the
toolsarray, the system prompt, or a tool description. They are announced through one append-only listing, under the invariants of cache-stable connection tools.Ready for code mode. Code mode will be a separate tool,
eve__execute({ code }), built on the workflow program runtime, with each call dispatched through the catalog. Theevenamespace reserves the name.
export default defineTool({
description: "Refund a paid Stripe invoice.",
deferred: true,
inputSchema: z.object({ invoiceId: z.string() }),
async execute({ invoiceId }) {
/* ... */
},
});
---
description: Fill and validate PDF forms.
deferred: true
---
This supersedes the model surface in connection-execute.md: the two
connection tools, their nested actions, and the connection listing. The
connection result format, sign-in, approval, and instance pinning carry over.
Current state
Every tool is advertised. Each static tool and each subagent tool the session can use goes into the provider
toolsarray on every step (harness/advertised-tools.ts). The only filters are subagent visibility (availableInSubagents,rootOnly) andtool: false.The harness already knows each tool's kind. Every entry in the
HarnessToolMapcarriesbehavior.handling(tools/behavior.ts):dispatchtoworkflow-tool-call,subagent-call,remote-agent-call, orself-agent-call;provider-tool;- nothing, for a plain tool with an inline
execute.
Coordination reads it to decide whether a call runs inline, starts a workflow run, or starts a child session (
harness/coordination.ts). Dynamic subagents join the same map each step (buildHarnessToolsWithDynamicSubagents).Connection tools are the exception. They aren't harness tools.
connection_execute(execution/tools/connection-tools.ts) is adefineToolclosure that calls the connection and reports a nested<connection>__<tool>action. That pattern can't reach workflow tools or subagents, because the harness has to see their call to park the turn and start the run.Connections already have the cache machinery this doc reuses.
- The listing is a
context.stateannouncement (execution/connection-announcement.ts,harness/announcements.ts). - Search returns TypeScript signatures
(
runtime/connections/tool-signature.ts), ranked byexecution/tools/connection-search-rank.ts.
- The listing is a
Every skill is listed.
- Static skills appear in the system prompt's "Available skills" section,
with name, description, and file path (
formatAvailableSkillsSectioninexecution/skills/instructions.ts). - Dynamic skills are re-announced as a full
context.statelist whenever they change (context/dynamic-skill-lifecycle.ts). - The model loads one with
load_skill({ skill }), a framework action (frameworkAction: "load-skill") that returns the skill's markdown.load_skillexists only when the agent declares skills.
- Static skills appear in the system prompt's "Available skills" section,
with name, description, and file path (
Name clash. Inside the harness, "deferred tool" currently means a workflow-backed tool, as in
Deferred tool "…" has no workflow.(harness/coordination.ts,harness/tool-loop.ts,execution/tasks/tool-entry-point.ts). That internal term gets renamed to "workflow tool" (8 occurrences).
Prior art
AI SDK
Read in the versions eve pins: [email protected], @ai-sdk/[email protected],
@ai-sdk/[email protected], and @ai-sdk/[email protected].
deferLoadingandtoolSearch().BaseTool.deferLoadinghides a tool untiltoolSearch()finds it.createToolSearchState(ai/dist/index.js) keeps adiscoveredset in memory for one generation. Each step filtersactiveToolsdown to tools that aren't deferred plus the ones discovered so far. Search is word overlap on name and description, top five results, and returns{ name, description }with no schema.- It breaks the cache. A tool the model finds is added to
toolson the next step, and the whole cached prefix is lost. The only cache-stable path is code mode withtoolDiscovery: 'conversation'. It also needs every definition before the generation starts and drops discoveries when the generation ends, which doesn't fit eve's durable step-by-step execution. - Provider-native search.
- Anthropic:
toolSearchRegex_20251119andtoolSearchBm25_20251119withproviderOptions.anthropic.deferLoading. ThetoolChangesoption on mid-conversation system messages also adds tools without losing the cache (betamid-conversation-tool-changes-2026-07-01). - OpenAI:
openai.tools.toolSearch()withproviderOptions.openai.deferLoadingand tool namespaces. - In all of these the provider runs discovery and the model calls the tool directly by name. All of it is specific to one provider and some of it is beta.
- Anthropic:
opencode
Sources:
v2@b5c43a4 for the
current tool names, and the earlier
v2@6bffe79
for catalog delivery, read but not run. Neither has deferLoading,
tool_search, or provider-native search.
- Code mode by default. Tools set
codemode: falseto stay native: shell, read, edit,skill({ id }),subagent, and MCP servers configured that way. Everything else is reachable only throughexecute({ code }), whose programs callsearch()andtools.<ns>.<tool>(). There is no tool for a single call outside code, and calling a code-mode tool by name fails with "No tool named … is currently available". - Fixed description, appended catalog. The
executedescription is fixed. The catalog arrives as an instruction baseline followed by appended diffs (codemode/instructions.ts,session/instruction-state.ts). Each child call runs the same permission check as a direct call (tool/mcp.ts). - What carries over:
- one catalog over local and MCP tools;
- skills loaded by their own tool, by id;
executeas the name of the code tool, withsearch()inside programs;- an append-only catalog;
- the same permission checks whichever way a tool is called.
pi
Sources:
earendil-works/pi@6fb2e78
for the current tool names (the repository moved from badlogic/pi-mono), and
the earlier
pi-mono@636703a
for exposure and caching. Built-in MCP, tool_search, and code mode shipped in
0.99.0, which reverses pi's earlier "no MCP" position.
- Per-tool exposure.
ToolExposureisdirect,model-only,codemode,deferred, orhidden. MCP tools default tocodemode, run throughcodemode({ code }). Thedeferredexposure routes a tool throughtool_search. - Search activates matches.
tool_search({ query, limit? }), with a defaultlimitof 8, uses BM25 over name, description, schema text, and namespace, and adds its matches to the active tools. The model then calls them directly by name. To keep the cache, pi depends on provider support:- Anthropic: inline
tool_additionblocks plus adefer_loadingplaceholder tool. Without the placeholder, pi measured a full cache miss on the first tool change. - OpenAI:
additional_tools, or a synthetictool_search_call. - Other providers: pi's own docs say the prefix can be invalidated.
- Anthropic: inline
- Fixed search description. It never lists the searchable tools, so it doesn't change as servers connect.
- No skill tool. Skills are listed by name, description, and path in the
system prompt and read with
read. They aren't searchable. - Community adapters.
pi-mcp-adapteruses a single proxy tool,mcp({ search })thenmcp({ tool, args }).
What we take
| Question | AI SDK | opencode v2 | pi | This design |
|---|---|---|---|---|
| Opt-in | deferLoading |
codemode (default on) |
exposure: "deferred" |
deferred: true |
| One catalog with MCP | No | Yes | Yes | Yes |
| Search | toolSearch(), top 5 |
search() inside code |
tool_search({ query, limit? }), 8 |
eve__search({ query, limit? }), 10 |
| How a found tool is called | Directly, next step | tools.x() in execute |
Directly, next step | eve__tool({ name, input }), same step |
| Skills | None | skill({ id }) |
read on SKILL.md |
eve__skill({ name }) |
| Code mode | toolDiscovery option |
execute({ code }) |
codemode({ code }) |
Later, eve__execute({ code }) |
tools array mid-session |
Grows | Fixed | Grows, except on 2 providers | Fixed |
| Catalog delivery | Search result only | Baseline + diffs | Search result only | Baseline + diffs |
| Discovery state | In memory, one generation | None | Session transcript | None; search is stateless |
Design
tools array (fixed for every session)
┌──────────────────────────────────────────────┐
│ direct tools... eve__search eve__tool eve__skill │
└──────────────────────────────────────────────┘
messages: [system prompt, no catalog names]
[context.state: catalog baseline]
... turns ...
[context.state: catalog diff] ← append only
... compaction ...
[context.state: new baseline]
eve__tool({ name, input }) ← model history only
└─ resolve entry by name → dispatch as a direct call
inline tool → execute
workflow tool → durable run (foreground parks, background returns a task)
subagent → child session (local, remote, or root copy)
connection → connection client ("linear__list_issues")
eve__skill({ name }) ← model history only
└─ resolve skill by name → load-skill action → the skill's markdown
Authoring API
Tools. deferred?: boolean sits next to availableInSubagents in
ToolDefinitionBase, so defineTool and defineWorkflowTool both accept it.
It defaults to false.
import { defineWorkflowTool } from "eve/tools";
import { always } from "eve/tools/approval";
import { z } from "zod";
export default defineWorkflowTool({
description: "Review and deploy a service.",
deferred: true,
approval: always(),
inputSchema: z.object({ service: z.string() }),
async execute({ service }, ctx) {
"use workflow";
/* ... */
},
});
Subagents. A subagent's tool setting already controls whether the
subagent appears as a tool. It widens from boolean to
boolean | "deferred". This applies to defineAgent, remote agents,
workspace agents, and dynamic subagent configs.
export default defineAgent({
description: "Resolve billing disputes and refunds.",
model: "anthropic/claude-sonnet-4.6",
tool: "deferred",
});
- What each value means:
trueis a direct tool,"deferred"is a catalog entry, andfalseis not a tool at all. - On the root agent,
tool: "deferred"defers the built-inagentself-delegation tool. - Why
tooland not a separate flag. A separatedeferredflag ondefineAgentwould allow the contradictiontool: false, deferred: true. ctx.agent(name)is unchanged. It resolves from the full registry whatevertoolsays.
Built-in and extension tools are deferred by spreading them, the same way they're overridden today:
import { defineTool } from "eve/tools";
import { bash } from "eve/tools/bash";
export default defineTool({ ...bash, deferred: true });
Dynamic entries. DynamicToolEntry accepts deferred, and dynamic
subagent configs accept tool: "deferred". Teams use this for catalogs that
depend on the tenant or the user:
import { defineDynamic } from "eve";
import { defineTool } from "eve/tools";
export default defineDynamic({
events: {
"session.started": async (_event, ctx) => {
const actions = await loadTenantActions(ctx.session);
return Object.fromEntries(
actions.map((action) => [
action.id,
defineTool({
description: action.description,
deferred: true,
inputSchema: action.inputSchema,
execute: (input) => runTenantAction(action.id, input),
}),
]),
);
},
},
});
- Same rules as direct dynamic entries.
- A map entry is named by its bare key, with the mount prefix added for an
extension's resolver. Authors add their own prefix when they want one,
such as
tenant__export. - A dynamic tool still can't be a workflow tool.
- An entry the resolver no longer returns can't be called:
eve__toolreports it as unknown and suggests the closest names.
- A map entry is named by its bare key, with the mount prefix added for an
extension's resolver. Authors add their own prefix when they want one,
such as
- Keys are validated. Every dynamic entry name, direct or deferred, must
match
TOOL_SLUG_PATTERN. Today a bad key fails only when the provider rejects it, and a deferred name never reaches a provider. Checking it when the resolver returns it means any entry that works deferred also works direct. - Prefer session- or turn-scoped resolvers. A
step.startedresolver whose set of kinds or namespaces changes every step appends a listing every step. The cache stays intact, but history grows.
Skills. deferred?: boolean joins the skill definition. It defaults to
false and is set in any of three places:
---
description: Fill and validate PDF forms.
deferred: true
---
import { defineSkill } from "eve/skills";
export default defineSkill({
description: "Write release notes from merged pull requests.",
deferred: true,
markdown: "...",
});
import { defineDynamic } from "eve";
import { defineSkill } from "eve/skills";
export default defineDynamic({
events: {
"session.started": async (_event, ctx) => {
const playbooks = await loadTenantPlaybooks(ctx.session);
return Object.fromEntries(
playbooks.map((playbook) => [
playbook.id,
defineSkill({
description: playbook.description,
deferred: true,
markdown: playbook.markdown,
}),
]),
);
},
},
});
- What
deferredchanges. A deferred skill leaves the system prompt's skill section and the dynamic skill announcement. It is found witheve__searchand loaded witheve__skill({ name }). Everything else is the same as today: its markdown, its package files in the sandbox, its activation, and its eval facts. - Dynamic skills keep their rules. They resolve on
session.startedandturn.startedonly. A map entry is named by its bare key, with the mount prefix added for an extension's resolver. A dynamic skill still overrides a same-named authored skill. - Names are validated. Skill names, static and dynamic, must match
TOOL_SLUG_PATTERN. There is no check today, and dynamic skill keys aren't checked at all.
Connection tools are always catalog entries. There is no switch to make
them direct; this matches what connection_search does today.
Provider tools can't be deferred. These are tools with
behavior.handling.kind === "provider-tool", such as native web search. The
provider has to see their definition, so deferring one is a compile error.
The catalog
Every entry has one flat name: the same name it has, or would have, as a
direct tool. __ is the only namespace separator, as it is everywhere in eve
today.
| Entry | Source | Name | Lookup |
|---|---|---|---|
| Inline tool | deferred: true on a static or dynamic tool with an inline execute |
refund_invoice, crm__search, tenant__sync |
Harness tools for the step, no dispatch handling |
| Workflow tool | deferred: true on defineWorkflowTool |
deploy_service |
Harness tools for the step, workflow-tool-call |
| Subagent | tool: "deferred" on a local, remote, dynamic, or root-copy agent |
billing_specialist, crm__reviewer |
Harness tools for the step, subagent-call, remote-agent-call, or self-agent-call |
| Connection | Every tool of every connection, after tools.allow and tools.block |
linear__list_issues, crm__api__list_issues |
The owning connection, then its getToolMetadata() |
| Skill | deferred: true on a static or dynamic skill |
pdf-forms, crm__playbook |
Authored skills and the dynamic skill manifest, under the skill key |
Owners. A
__prefix names the entry's owner:- an extension mount:
crm__search; - a connection:
linear__list_issues; - a memory slot:
<slot>__<key>.
Owners nest. An extension mounted as
crmwithconnections/api.tscontributes connectioncrm__api, whose tools arecrm__api__list_issues. A prefix an author adds by convention, such astenant__export, has no owner.- an extension mount:
A connection owns its name and its
__prefix. No tool, subagent, memory tool, extension contribution, or other connection may be namedlinearor start withlinear__while connectionlinearexists.Only connections need the rule. They are the only entries eve can't list up front, because listing their tools needs a network call and maybe a sign-in. Every other name is known, and exact duplicates are already errors.
Checked on names alone. eve never lists a connection's tools to check it.
When it's checked. Static names are checked at compile time. Dynamic connections, tools, subagents, and memory tools are checked when they resolve. The entry that introduces the conflict is rejected with an error naming both sides, for example:
Dynamic tool "linear__sync" starts with "linear__", which belongs to connection "linear". Rename the map key.Nested connections. Connection
acme__crmconflicts with connectionacme. Without the rule,acme__crm__listcould mean connectionacmewith toolcrm__list, or connectionacme__crmwith toollist.
Routing.
eve__tool({ name })first looks for an exact match among the step's harness tools: authored and dynamic tools plus static and dynamic subagents, in the precedence direct calls use today. Otherwise it finds the connection whose<name>__startsname, and the rest is that connection's tool name, checked against its metadata.- The ownership rule allows at most one candidate, so the order of the checks never changes the result.
- The rest of the name is never split again, so MCP tool names work whatever characters they contain.
Dispatch is decided before anything runs. For harness entries, the dispatch handling is on the definition, which the harness already has. A name under a connection's prefix is always a connection call. So coordination can decide whether a call parks without any network call.
Deferring never renames. The model sees the same name in its tool list, in
eve__searchresults, ineve__toolinput, and in history. All of these keep working whether a tool is direct or deferred: protocol action names, approvals andapprovalKey, evals, hooks,toolResultFrom, display titles, and extension overrides such asagent/tools/crm__search.ts.Namespaces are never parsed. The ownership check compares names against connection names, and a connection entry knows its connection, which gives labels such as
Linear: List issues. Nothing splits a name at__. Code mode will record owners on each entry for program paths such astools.crm.api.list_issues; a convention prefix with no owner stays part of the name, as intools.tenant__export.Scope. The catalog holds only entries advertised to the current session, so a child session never sees a tool with
availableInSubagents: false.Skills have their own key. A skill is addressed as
{ skill }, never{ tool }. Skills and tools keep separate name spaces, as they have today, so a skill can share a name with the tool it documents. The connection ownership rule applies only totoolnames.
Model surface
eve__search
Input:
{ query, limit? }.limitdefaults to 10 and is capped at 50. Results stay in history for the rest of the session, so the default stays small: at 20, results averaged about 660 tokens, and 15 of 32 benchmark queries returned all 20, mostly weak matches, while every expected tool ranked in the top 5.queryis required and must contain a word. Deferred entries are found by what they do or by namespace, not browsed. A connection's name as the query, such aslinear, lists that connection's tools first.- Namespace queries. A query whose first word contains
__searches one namespace: everything before its last__, with trailing underscores trimmed. 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. Solinear__list_issuesstill finds thelinearsign-in entry when Linear needs sign-in, and an exact name that contains__still ranks first. Connection ownership means no tool outside a connection uses its prefix, soeve__searchlists only the connections that can own names in the namespace (linear, orcrm__apiunder an extension mounted ascrm). Other connections make no network call and don't appear inunavailable. A namespace that matches nothing fails with the closest connection names instead of returning an empty list. Characters that can't appear in a name, such as a leading^, are ignored, and regex isn't supported. The description tells the model to use this when it already knows a name or namespace, from the listing, a result, or an error. - There is no connection filter and no sign-in flag. The query already
selects a connection, and sign-in is an
eve__toolcall. - There is no paging and no match count.
eve__searchreturns the best matches up tolimit, and the model narrows the query or raiseslimitfor more. Paging and counts assume a fixed, countable match list, which a future search that asks a model to choose entries wouldn't have.
Async.
eve__searchreturns a promise, so the way it picks results can change, for example to a decision model, without changing its signature.Result:
{ results, unavailable? }.- A tool entry is
{ tool, description, signature }.toolis the exact name to pass toeve__tool. signatureis TypeScript rendered from the input and output schemas byrenderToolSignature, which moves to a shared module. It is more compact than JSON Schema, includes the output type, and is what a code-mode program calls.- Results don't say whether a tool is inline, a workflow, a subagent, or a
connection tool. The call is the same for all of them. Notes eve appends
to a direct tool's description, such as the
endsTurnsentence or background-task guidance, go at the end ofdescriptioninstead. - A skill entry is
{ skill, description, path? }.pathis the skill'sSKILL.mdunder the skills root, present when the skill has package files. It is the same path the skill section shows for a skill that isn't deferred, so relative references inside the skill still resolve. - Tools and skills rank together, so one query such as "fill a PDF form"
can return a
pdf_filltool and apdf-formsskill. - A connection whose tools can't be listed until the user signs in appears
as a tool result named after the connection, such as
{ tool: "linear", description: "Sign in to use the Linear tools: …" }. unavailablereports only connections that failed to list or can't start an interactive sign-in.- Listing a connection's tools stops waiting after 10 seconds. Every
unscoped search lists every connection, so without a bound a search for
a local tool would wait on the slowest server, and a hung one would stall
the step. The connection is reported in
unavailablewith"<connection>" did not list its tools within 10s. Try again later., and aneve__toolcall on its tools fails with the same error. The bound covers listing only, not sign-in or tool calls. Clients share one in-flight listing and take no signal, so eve stops waiting instead of cancelling; a late result fills only that step's client, and the registry is rebuilt every step.
- A tool entry is
Ranking. Matches rank in tiers, and an exact name always ranks first:
- the query's words equal the entry's full name, such as
linear__create_issue; - they equal the name after its last
__, whatever the namespace, such ascreate_issueforlinear__create_issueorsre__create_issue; - they start the entry's connection name and the full name, so
linearreturns thelinearconnection's tools; - they start the entry's full name or its name after the last
__, with the last word allowed to be partial, such ascreate_iss; - keyword matches, weighted by field: the name, then the connection name,
input property names, the description, and last property descriptions
and the connection description. One-letter and filler words such as
a,to, andthedon't score when the query has other words, since they match nearly any name by prefix.
A score breaks ties within a tier, then the connection name, then the entry name. A skill has only a name and a description to match.
eve__tool's andeve__skill's closest-name suggestions use the same ranking.Measured on the
agent-tool-discoverycatalog plus two connections (Linear and GitHub) with 32 queries phrased as models send them, matching names after any namespace and ignoring filler words raised recall@1 from 27/32 to 29/32 and MRR from 0.907 to 0.939; recall@5 stayed at 32/32.- the query's words equal the entry's full name, such as
Sign-in.
eve__searchnever prompts. It lists a connection that needs sign-in as a result, andeve__tool({ name: "<connection>" })asks the user to sign in.Description. Fixed for each eve version. It names no entry. It says that
eve__searchfinds the agent's own tools and services, not web pages, so the model doesn't use it in place ofweb_search.Label. People see
Search tools for “<query>”, thenSearched tools for “<query>”, found <n>when it returns, never the tool's name.
eve__tool
- Input:
{ name: string, input?: object }.inputdefaults to{}. - Wire schema. One flat object schema with
namerequired. Skills have their own tool, so there is notool-or-skillunion to work around: Anthropic rejectsoneOf,anyOf, andallOfat the top of a tool's input schema (example). - Any entry, no prior search. It calls any catalog entry by name, whether or not it was searched for. There is no discovered set to persist or replay.
- Validation. eve checks
inputagainst the entry's input schema before dispatching, because the provider never saw that schema. Failures come back as data the model can act on:- An unknown name lists the closest tool names.
- A skill's name says to load it with
eve__skill. - eve's own catalog and task tools, and tools a provider or client runs,
return
"<name>" is in your tool list; call it directly. - Invalid input returns the entry's
signature.
- Sign-in. A connection's own name is an entry.
eve__tool({ name: "linear" })finishes a pending sign-in or starts one, the same way a call to one of its tools does, and parks until the user signs in. It then says the connection's tools can be searched. When the tools are already listable, it only confirms. It has no approval, and its label isSign in to Linear. Every path that finishes a sign-in, whether ineve__search, a tool call, or this entry, goes through one helper. - Description. Fixed for a deployment: "Call a tool that isn't in your
tool list by its exact name from eve__search, with
inputmatching its signature." Only with connections, it adds the preference for connected services over web search or general knowledge, a sentence that moves over fromconnection_search.
eve__skill
- Input:
{ name: string }, required. - Loads every skill. It loads any skill the session can see, deferred or
not, and replaces
load_skill. An agent whose only catalog entries are listed skills getseve__skillalone, which isload_skillrenamed. - Validation. An unknown name lists the closest skill names. A tool's
name says to call it with
eve__tool, or directly when it's in the tool list. A name that matches a connection says to find its tools witheve__search({ query: "<connection>__" }), a hint that moves over fromload_skill. - Description.
load_skill's trigger, fixed for a deployment: "Load a skill's instructions when the request clearly matches a listed skill or the user asks for it, then follow them." It mentionseve__searchonly when search can find skills. An audit found that a skill clause placed after a generic call-a-tool text left only the system prompt prompting skill loads. The skill section of the system prompt and the dynamic skill announcement tell the model to load listed skills the same way.
All three
Present from what the agent declares. Each agent, root or subagent, decides from its own declarations, once per deployment:
eve__toolwith a deferred tool or agent the session sees, a connection, or a dynamic tool, subagent, or connection resolver;eve__skillwith any skill, static or from a dynamic skill resolver;eve__searchwith anything it could find: whatevereve__toolreaches, plus deferred skills and dynamic skill resolvers;- none otherwise, so such an agent's tool list is
main's minusload_skill.
A rule like "present while the catalog is non-empty" would flip the array the first time a resolver returns a deferred entry; reading declarations keeps it fixed for the deployment, so parked approvals and restored steps see the same tools. No text points at a catalog tool the agent lacks.
Why not always. The first design registered its catalog tools for every agent. A pre-merge audit measured about 290 extra tokens per request (net of the removed
load_skill) for agents with nothing to find, whereeve__searchalways returned{ results: [] }and the call tool described nothing the agent had. gpt-6-sol also serialized parallel tool calls whenever the catalog tools were present.One reserved namespace. Every tool eve adds at runtime is named
eve__<name>:eve__search,eve__tool,eve__skill,eve__task_wait,eve__task_cancel, andeve__reply, witheve__executeheld for code mode. Nothing authored or dynamic may be namedeveor start witheve__: tools, subagents, skills, connections, and extension mounts, since a connection or mount namedevewould own everyeve__name. One rule in one helper replaces a list of reserved names, sosearchandexecutestay ordinary names an author can use. The prefix also tells the model these tools are eve's and can't be replaced. Static entries fail at compile time or when the agent loads, and dynamic ones when they resolve, with an error that tells the author to rename.defaultTools: falsedoesn't remove them.
Dispatch
An eve__tool or eve__skill call is dispatched as if the model had called
its entry directly. The harness resolves the entry once per call
(resolveCatalogEntry(toolCall, tools)) and uses it everywhere the harness
looks a call up by name. Model history is the only place that keeps the
catalog tool's name. Both are thin fronts on one resolver and one dispatch
path.
| Concern | Harness entries (inline, workflow, subagent) | Connection entries |
|---|---|---|
| Action name on the protocol | The entry's name | <connection>__<tool>, as today |
| Approval | The entry's approval and approvalKey |
The connection's approval, keyed <connection>__<tool>, with instance pinning |
| Execution | Inline execute, a workflow run, or a child session, chosen by behavior.handling |
The connection client, with result conversion and auth parking unchanged |
toModelOutput, endsTurn |
The entry's | The connection's file-part projection |
ctx.toolName, ctx.callId |
The entry's name and the model's call id | n/a |
| Labels, hooks, audience policy | The entry | Linear: List issues, as today |
| Eval assertions | t.calledTool("deploy_service"), t.calledSubagent(...) |
t.calledTool("linear__list_issues"), unchanged |
| Model history | eve__tool call and result, same call id |
Same |
One name everywhere. The name the model passes to
eve__toolis also the protocol action name, the approvaltoolNameand key, and the eval assertion name. For connection tools that is today's<connection>__<tool>. So existing approval policies, recorded "always approve" decisions,toolResultFrom, and eval assertions keep working.Harness entries need nothing new. Once a call resolves to its entry, the harness dispatches it exactly like a direct call, because the dispatch handling is already on the definition.
- A foreground workflow tool parks the turn and starts its run.
- A background workflow tool returns its task receipt, and
eve__task_waitandeve__task_cancelwork on thetaskId. - A subagent starts its child session, and the child's
session.startedrecords the model's call id asparentCallId.
Connection entries become harness definitions. At resolve time, eve builds a harness definition from the connection's metadata that is never advertised: an
executethat calls the client, the connection's approval, and its model-output projection. The code is today'sexecuteConnectionTool,connection-approval.ts, andtool-result.ts, moved behind that definition. The definition is built only after the call is already known to be a connection call, so the network lookup it needs never delays the decision to park.Skill entries run the
load-skillaction.eve__skill({ name })becomes the same runtime actionload_skillproduces today (kind: "load-skill"). So protocol events, activation, package files under the skills root, andt.loadedSkill(...)are unchanged. Its label readsLoad skill <name>, thenLoaded skill <name>once it loads. History holds aneve__skillcall whose result is the skill's markdown. Loading needs no approval, as today.No nested actions. Every entry, including a connection tool, is reported as the call itself. The nested-action helper and the tool-call action's
parentCallIdfield lose their only producer and are removed. Code mode adds the field back for calls made from a program.eve__toolandeve__skillinside the AI SDK. The AI SDK decides per tool name whether to run a tool, so both always have a run function. For an inline entry or a skill it runs the entry's ownexecute. For a workflow tool or subagent it returns a dispatch marker that the harness strips from the step, then dispatches the resolved call through the existing workflow and child-session path. The marker is hidden from telemetry and lives in one module.Harness seams. These are the places that look up by tool name today:
buildToolApprovalandbuildToolSet(harness/tools.ts);createRuntimeActionRequestFromToolCall,createCoordinationRequestFromToolCall, subagent dispatch, and theload-skillmapping thatframeworkActiondrives today (harness/coordination.ts);- label and
endsTurnlookup inprepareModelTools(harness/tool-loop.ts); - the history writer, which must record the catalog tool rather than
result.toolName,subagentName, orload_skill.
This is a change to the harness, and it is needed: without it, workflow tools and subagents can't be deferred, and skills can't load without
load_skill.Never AI SDK
deferLoading. eve builds its AI SDK tools itself and never setsdeferLoadingor passestoolSearch(). Either one would bring back the growingtoolsarray.
Catalog listing
One announcement under the key catalog replaces the connection listing.
- Baseline. On a session's first model step, eve appends one
context.statemessage. It says which kinds of deferred entries exist (tools, agents, skills) and tells the model to look for a tool witheve__search, which searches its own catalog rather than the web, before saying it has no tool for a task. It then lists namespaces and connections, each capped. - No deferred names. A deferred entry is meant to stay out of context until a search finds it, so the listing never names one. It doesn't count entries either: counts would change, and append a message, whenever a dynamic resolver adds or drops one.
- Namespaces. The first
__segment of deferred tool, agent, and skill names, such assreforsre__list_alerts, whether the entries come from an extension mount or are vendored under that prefix. A namespace query (eve__search({ query: "sre__" })) searches exactly that set. At most 20 are listed: the 20 with the most entries, rendered by name, so a namespace growing or shrinking only changes the listing at the cap. A longer list ends with "and more". A namespace that is also a connection's name is listed only as the connection. - Connections are listed by name and description, capped at 20 the same way. Listing their tools would mean connecting to every server, and possibly asking for sign-in, at session start.
- Skills that aren't deferred stay where they are: static skills in the
system prompt's skill section, dynamic skills in their announcement. Only
the load instruction in both changes, to
eve__skill({ name }). - Changes. The listing only changes when the kinds present, the listed
namespaces, or the listed connections change: when a dynamic resolver adds
the first entry of a kind or namespace, a dynamic connection resolves, or
the session upgrades to a new deployment. eve then appends the full
listing again, prefixed with "The catalog changed.", and names any
namespace or connection that is gone. A deferred entry added to a listed
namespace, or without one, appends nothing;
eve__searchfinds it. - After compaction, the next step appends a fresh baseline.
- Empty catalog, no message.
You have more tools, agents, and skills than are loaded here. Before saying you have no tool for a task, look for one with eve__search, which searches your own catalog, not the web. Call tools with eve__tool({ name, input }) and load skills with eve__skill({ name }).
Namespaces, whose entries are named <namespace>__<name>; search one with "<namespace>__": d0, index, sre, support
Connections, whose tools are named <connection>__<tool>; search one connection's tools with "<connection>__":
- linear: Linear issues and projects
- petstore: Pet store inventory API
Cache invariants
- Fixed tools. The
toolsarray is identical on every step of a session: same names, descriptions, schemas, and order. Catalog changes, static or dynamic, never touch it, because which catalog tools are present follows from what the agent declares, never from what its resolvers return. - No session-specific text in the system prompt or any tool description.
- Append-only history. Listing changes only append messages, and earlier messages are never rewritten.
- No system-message fallback. Announcements are always messages appended to history. They never fall back to the system prompt, including on the step that runs approved calls.
- Deterministic rendering. Listings are sorted, and a signature is a
pure function of its schema, so the same entry always renders the same
text.
eve__searchrenders signatures only for the results it returns. - Calling an entry adds nothing. An
eve__toolcall, skill load, approval, park, sign-in, child session, or resume never adds a definition. That is exactly where AI SDKtoolSearch()and pi's activation path lose the cache.
Implementation
Principles
The result must read as if eve had been designed around the catalog from the start.
- Expect a net deletion. This work replaces three model surfaces
(
connection_search,connection_execute,load_skill) and the special cases each one grew. It should remove more code than it adds. - One path per job. Each job in the table below has exactly one
implementation. A direct call and an
eve__toolcall share everything after name resolution. No adapter, fallback, or second branch does the same work another way. - No compatibility layer. There are no aliases for removed tools, no flags that restore old behavior, and no code or comments that mention the old surface. Pre-1.0, eve prefers the breaking change.
- Old tests are deleted, not ported. A test that covers a removed path is deleted along with the path. Tests for the new design are written fresh in the testing PR, against the new surface. Old assertions are never adjusted to fit.
- Generalize, then delete the original. Code that survives, such as the ranker, the signature renderer, connection approval, and instance pinning, moves to where the unified path needs it. No copy stays behind under its old name.
One path per job
| Job | Today | After |
|---|---|---|
| Find a capability by name | Authored tool map, dynamic tool list, dynamic subagent merge, presentation map (prepareModelTools), and connection_execute's own lookup |
One table of the step's entries, built once per step and used both to advertise direct tools and to resolve eve__tool and eve__skill |
| Run a call | AI SDK execute, workflow dispatch, subagent dispatch, the load_skill frameworkAction, and the connection_execute closure |
Resolve the entry, then dispatch on its handling, the same for direct and catalog calls |
| Approve a call | Per-tool approval functions on AI SDK tool objects, plus connection approval delegated through connection_execute |
The resolved entry's approval, for every call |
| Announce state | A dedicated availableSkills field and the keyed announcements (harness/current-messages.ts) |
Keyed announcements only: catalog, plus skills that aren't deferred |
| Load a skill | load_skill, the frameworkAction marker, and reserved-name handling in the subagent registry |
eve__skill({ name }) to the load-skill action |
| Report a call | An action, plus nested actions for connection calls | One action per call, named for the entry |
| Label a call | Entry labels, plus connection_execute special cases in toolCallDisplayName, the dev TUI, and the channel task card |
Entry labels |
| Mock model | Special handling and skill selection for load_skill (runtime/agent/mock-model-*) |
The mock model calls eve__search, eve__tool, and eve__skill like a real one |
Deletion inventory
- Connection tools.
execution/tools/connection-tools.ts,execution/tools/connection-target.ts,tools/framework/connection-tools.ts,execution/connection-announcement.ts, and the connection slots incompiler/default-tool-policy.ts.connection-search-rank.tsandruntime/connections/tool-signature.tsmove to the catalog.connection-approval.tsmoves behind the connection entry's definition.
- Nested actions.
harness/nested-actions.tsand its callers inharness/emission.tsandharness/step-hooks.ts, plus their rendering in the dev TUI trace view and the channel task card, and the tool-call action'sparentCallIdfield with its span attribute. load_skill.execution/tools/load-skill.ts,tools/provided/load-skill.ts,public/tools/load-skill.ts, theeve/tools/load_skillexport, its framework source registration, theload-skillvalue offrameworkAction,LOAD_SKILL_TOOL_NAME, and its reserved-name entry inruntime/resolve-agent-graph.ts. An authoredagent/tools/load_skill.tsbecomes an ordinary tool. Theload-skillaction kind stays, because the protocol, traces, andt.loadedSkillreport skill loads with it.- Skill announcement channel.
PendingSkillAnnouncementKey, theavailableSkillsannouncement field, and its history state. Dynamic skills use a keyed announcement instead. - Special cases. Every branch that names
connection_search,connection_execute, orload_skill, including the TUI tool presentation, the channel task card,load_skill's connection hint (which moves toeve__tool), and the mock model. - Internal naming. The harness's "deferred tool" for workflow-backed tools becomes "workflow tool".
- Tests. Every unit, integration, and e2e test for the paths above,
deleted in the PR that removes the path. That is 18 unit and integration
test files and 23 tracked e2e files today, led by
execution/tools/connection-tools.test.ts,execution/tools/load-skill.test.ts,execution/connection-announcement.test.ts, the connection evals inagent-openapi-swaggerandagent-workflow-tools, and theload_skillevals inagent-skillsandextensions. A test file that also covers surviving behavior loses only the removed cases.
Pull requests
Three stacked PRs. The first two hold all of the implementation and add no tests. The third holds all of the new tests.
| PR | Scope |
|---|---|
| [1/3] Catalog | Naming groundwork (connection prefix ownership, key and name validation, the internal rename); deferred on tools and workflow tools; tool: "deferred" on subagents; dynamic entries; eve__search and eve__tool; the step entry table and call resolution; the catalog listing; connection tools as entries; removal of the connection tools and nested actions |
| [2/3] Skills | deferred in frontmatter and defineSkill, static and dynamic; skill results in eve__search; eve__skill({ name }); removal of load_skill and the skill announcement channel |
| [3/3] Tests | Every new test, listed below. Fixes the tests surface go back into [1/3] or [2/3] before the stack merges. |
- The stack merges together. [1/3] and [2/3] delete the old e2e evals with the paths they cover, and [3/3] adds the new ones. So [1/3] and [2/3] pass unit tests on their own, but the e2e suites are only meaningful with [3/3] stacked on top.
- Docs and changesets go with the implementation. [1/3] and [2/3] each
update the docs for the behavior they change and carry a
minorchangeset.
Tests and rollout
Everything in this section lands in [3/3].
Captured-request unit test. It drives one session through each entry:
- an
eve__search, theneve__toolof an inline tool; - a foreground workflow tool that parks and resumes;
- a background workflow tool;
- a deferred subagent;
- a connection tool that parks for sign-in;
- a connection listed for sign-in, then
eve__toolof its name; - a dynamic connection resolving;
- a dynamic deferred tool and a dynamic deferred subagent appearing mid-session, then one of them disappearing;
- a
eve__searchthat returns a tool and a skill with the same name, theneve__skill({ name })for a deferred static skill with package files; - a deferred dynamic skill appearing on
turn.started, then loading; eve__skill({ name })for a skill that isn't deferred;- a catalog change on the step that runs an approved call;
- compaction.
It asserts all six invariants. A second case covers an agent with only listed skills:
eve__skillis its only catalog tool and no listing is appended.- an
E2E: a new
agent-deferred-toolsfixture. About 40 deferred entries: inline tools, a workflow tool with approval, a background workflow tool, a deferred subagent, deferred static and dynamic skills, a session-scoped dynamic resolver returning deferred tools, and the self-contained petstore OpenAPI connection.- World suites with the mock model: approval keyed to the entry, the
workflow tool parking and resuming, the background task receipt, the
subagent's child session, a deferred skill loaded with
t.loadedSkill, and a misspelled name corrected from the suggestion. - Real-model suite: cache reads on the steps after discovery, following
agent-prompt-cache.
- World suites with the mock model: approval keyed to the entry, the
workflow tool parking and resuming, the background task receipt, the
subagent's child session, a deferred skill loaded with
New evals in the existing fixtures.
agent-openapi-swagger,agent-workflow-tools,agent-skills, andextensionsget new evals written againsteve__search,eve__tool, andeve__skill. They cover what the deleted evals covered: connection approval, sign-in, dynamic connections, MCP result content, input validation, dynamic skills, skill overrides, and extension skills. They are written from the behavior, not ported from the old files.Unit coverage for rules whose old tests were deleted. Subagent visibility in the step catalog, the task tools offered per session, connection prefix ownership at compile and resolve time, dynamic tool and subagent collisions (including the
tool: falsewrapper pattern), connection input validated before approval, and listing failures that aren't sign-in.Measurements. Run one task set three ways:
- all tools and skills direct,
- long-tail tools and skills deferred,
- long-tail tools and skills in subagents.
Compare task success, input tokens, cache read ratio, and model calls, at a moderate tool count and at a large one.
Ship gate.
- Arm 2 matches arm 1 on success at the moderate count and beats it at the large count.
- Arm 2 beats arm 3 on success.
- Connection and skill evals don't regress.
- Agents with nothing to find get neither tool, so they behave as on
main. - The model doesn't call
eve__searchfor web questions on agents that haveweb_search. - No cache regression after discovery.
Later, gated by evals. A real-model eval of discovery with a large catalog and no connections, which decides whether the listing needs more than kinds and namespaces.
Docs, updated in [1/3] and [2/3]:
tools/overview: deferring a tool, and which tools to defer (keep frequently used tools direct and defer the long tail).tools/workflows,subagents/*(tool: "deferred"), andconcepts/built-in-tools(eve__search,eve__tool, andeve__skillinstead of the connection tools andload_skill).skills,instructions,concepts/context-control,evals/assertions,reference/typescript-api, and the team playbooks tutorial: deferring a skill and loading witheve__skill({ name }).connections/overview,connections/mcp,guides/dynamic-capabilities(bare map keys, and the connection prefix rule), andextensions(the reserved names and how mount prefixes nest with connections).
Changesets, one
minorin each of [1/3] and [2/3]. Together they:- remove
connection_search,connection_execute, andload_skill; - reserve the
evenamespace in every agent; - reject names that start with a connection's prefix, which an existing
agent may already have, such as connection
linearbeside a tool namedlinear__sync.
- remove
Decisions and alternatives considered
| Decision | Chosen | Rejected |
|---|---|---|
| Tool names | eve__search, eve__tool, and eve__skill, under the eve__ namespace eve reserves for every tool it adds |
search and execute unprefixed (reserves two common words authors want, and nothing marks them as eve's); $search ($ isn't legal in tool names for eve or some providers); _search (tool names start with a letter, and a leading underscore reads as private); tool_search and tool_execute (still reserves names outside any namespace) |
| Search surface | One eve__search over every entry, connections included |
Keeping connection_search next to it (two places to look, two listings); a separate skill_search |
| Split by kind | eve__tool({ name, input? }) for tools and eve__skill({ name }) for skills, each with a flat schema that requires name |
One eve__execute taking tool or skill (providers reject a top-level oneOf, so it needs both keys optional plus an exactly-one check; loading a skill reads as a clause of a call-a-tool description and loses load_skill's trigger; one tool registered for two unrelated reasons); eve__connection for connection tools (connection tools are tools, and the model would have to classify a tool by where it comes from); markers such as skill:pdf in one name space |
| Presence | From what the agent declares, per tool: eve__tool with anything it can call, eve__skill with any skill, eve__search with anything it could find |
Always (about 290 tokens per request with nothing to find, and serialized parallel calls on gpt-6-sol); only while the catalog is non-empty (flips tools when a dynamic entry appears); an agent-level flag |
| Dynamic entries | Deferrable, like static ones | Static only (rules out per-tenant catalogs) |
| Opt-in | deferred: true on tools and skills; tool: "deferred" on agents |
An agent-level list of names; deferLoading (eve never loads the definition); pi's exposure enum |
| Discovery mechanism | Fixed catalog tools | AI SDK toolSearch() or activation (grows tools); provider-native search (one provider at a time, partly beta) |
| Dispatch | Resolve to an entry, then dispatch it like a direct call | A defineTool proxy (can't reach workflow tools or subagents; duplicates approval) |
| Entry names | One flat name, __ as the only namespace separator, and connections own their prefix |
<connection>.<tool> (a second separator for one owner, and it renames connection tools); dots everywhere, encoded as __ for providers (deferring would rename a tool); a separate connection argument (a two-part key) |
| Owners | Recorded on each entry as data, added with code mode | Recovered by splitting names at __ (can't tell an owner from a convention prefix) |
| Dispatch marker | eve__tool returns a marker for workflow and subagent entries; the harness strips it |
Renaming calls in a provider middleware (connection tools can't join the tool set without listing every connection, so they would need a second path) |
| Search output | TypeScript signature |
Raw JSON Schema (larger, and code mode needs the signature anyway) |
| Protocol shape | Actions carry the entry's name; only history says eve__tool or eve__skill |
An outer catalog-tool action with a nested entry action |
| Search state | Stateless; any entry can be executed | A durable discovered set that execution checks |
| Listed tools | eve__tool runs them as a direct call would, unannounced; eve's own and provider-run tools still error |
An error saying to call the tool directly (costs a step) |
| Listing | One append-only listing: the kinds present, capped namespaces, and capped connections | Nothing (the model can't tell when to search); every deferred name (defeats deferring and grows without bound); counts (churn on dynamic changes) |
| Old paths and tests | Deleted with no compatibility layer; old tests deleted, and new tests written fresh in [3/3] | Aliases or flags for removed tools; porting old tests to the new surface; tests spread across the implementation PRs |
| Loading skills | eve__skill({ name }) for every skill, registered with any skill; load_skill is removed |
Keeping load_skill beside eve__skill (two ways to load); load_skill only for skills that aren't deferred (the model must know which kind it has) |
Later: code mode
Code mode will be a separate tool, eve__execute({ code }), built on the
workflow program runtime. Each call a program makes is dispatched through the
catalog, as an eve__tool call is. The rest of this design carries over:
| This design | Code mode |
|---|---|
eve__search(opts) tool |
search(opts) inside the program, same result shape |
eve__tool({ name, input }) |
tools.deploy_service(input), tools.linear.list_issues(input) |
eve__skill({ name }) |
Loading a skill from the program |
One action per eve__tool call |
One nested action per call, with parentCallId added back |
| Approval on the model's call | Approval on the nested action, parking mid-program |
| Catalog listing | Unchanged |
Signatures in eve__search results |
The types the program is written against |
eve__tool({ name, input })is a one-call program, so both forms share one dispatch path.- Each entry records its owners, and program paths come from that record,
not from splitting names:
linear__list_issuesistools.linear.list_issues,crm__api__list_issuesistools.crm.api.list_issues, andtenant__export, which has no owner, istools.tenant__export. eve__executeappears only when code mode is on. That is fixed per agent and eve version, never per step, so thetoolsarray stays stable.- Names with
-aren't JavaScript identifiers. A kebab-case connection such asgoogle-driveis called astools["google-drive"].list_files(input).