feat: Tool search and deferred loading (#535)

* Tool search with deferred execution

* Frontend implementation

* Fixes and error improvements

* Adapt tool_search to be a bit more maintainable

* PR feedback

Author: cmsparks

Makefile

@@ -452,13 +452,15 @@ test-live-openai-responses:
 	@$(LOAD_DOTENV); \
 	: "$${OPENAI_API_KEY:?OPENAI_API_KEY is required for live OpenAI Responses tests}"; \
 	$(GO) test -count=1 -v -tags=live ./internal/model -run '^TestLivePromptCache/openai_responses$$' && \
+	$(GO) test -count=1 -v -tags=live ./internal/model -run '^TestLiveDeferredToolsLoadAfterSearch/openai_responses' && \
 	$(SERVICE_E2E_ENV) $(GO) test -count=1 -v -timeout=25m -tags='integration servicee2e live' ./internal/e2e -run '^TestServiceE2ELiveOpenAIResponses(ModelTurn|CompactionRecall|DockerDaemonProcessTools)$$' && \
 	$(TEST_DB_ENV) $(GO) test -count=1 -v -tags='integration live' ./internal/compaction -run '^TestRunnerLiveOpenAIResponsesCompactionCreatesCheckpoint$$'
 
 test-live-openai-chat-completions:
 	@$(LOAD_DOTENV); \
 	: "$${OPENAI_API_KEY:?OPENAI_API_KEY is required for live OpenAI Chat Completions tests}"; \
 	$(GO) test -count=1 -v -tags=live ./internal/model -run '^TestLivePromptCache/openai_chat$$' && \
+	$(GO) test -count=1 -v -tags=live ./internal/model -run '^TestLiveDeferredToolsLoadAfterSearch/openai_chat' && \
 	$(GO) test -count=1 -v -tags=live ./internal/model/openaichatcompletions -run '^TestLiveOpenAIChatCompletionsText$$' && \
 	$(SERVICE_E2E_ENV) $(GO) test -count=1 -v -timeout=25m -tags='integration servicee2e live' ./internal/e2e -run '^TestServiceE2ELiveOpenAIChatCompletions(ModelTurn|CompactionRecall|DockerDaemonProcessTools)$$' && \
 	$(TEST_DB_ENV) $(GO) test -count=1 -v -tags='integration live' ./internal/compaction -run '^TestRunnerLiveOpenAIChatCompletionsCompactionCreatesCheckpoint$$'
@@ -467,6 +469,7 @@ test-live-openrouter:
 	@$(LOAD_DOTENV); \
 	: "$${OPENROUTER_API_KEY:?OPENROUTER_API_KEY is required for live OpenRouter tests}"; \
 	$(GO) test -count=1 -v -tags=live ./internal/model -run '^TestLivePromptCache/openrouter_.*$$' && \
+	$(GO) test -count=1 -v -tags=live ./internal/model -run '^TestLiveDeferredToolsLoadAfterSearch/openrouter_' && \
 	$(GO) test -count=1 -v -tags=live ./internal/model/openaichatcompletions -run '^TestLiveOpenRouterChatCompletions' && \
 	$(SERVICE_E2E_ENV) $(GO) test -count=1 -v -timeout=25m -tags='integration servicee2e live' ./internal/e2e -run '^TestServiceE2ELiveOpenRouter(ModelTurn|CompactionRecall|DockerDaemonProcessTools)$$' && \
 	$(TEST_DB_ENV) $(GO) test -count=1 -v -tags='integration live' ./internal/compaction -run '^TestRunnerLiveOpenRouterCompactionCreatesCheckpoint$$'
@@ -475,6 +478,7 @@ test-live-anthropic:
 	@$(LOAD_DOTENV); \
 	: "$${ANTHROPIC_API_KEY:?ANTHROPIC_API_KEY is required for live Anthropic tests}"; \
 	$(GO) test -count=1 -v -tags=live ./internal/model -run '^TestLivePromptCache/anthropic$$' && \
+	$(GO) test -count=1 -v -tags=live ./internal/model -run '^TestLiveDeferredToolsLoadAfterSearch/anthropic' && \
 	$(SERVICE_E2E_ENV) $(GO) test -count=1 -v -timeout=25m -tags='integration servicee2e live' ./internal/e2e -run '^TestServiceE2ELiveAnthropic(ModelTurn|CompactionRecall|DockerDaemonProcessTools)$$' && \
 	$(TEST_DB_ENV) $(GO) test -count=1 -v -tags='integration live' ./internal/compaction -run '^TestRunnerLiveAnthropicCompactionCreatesCheckpoint$$'
 

docs/agents/configuration.mdx

@@ -131,6 +131,19 @@ Existing machine configs gain missing machine-tool defaults only when saved agai
 
 Slack's `send_integration_message` remains contextual: it is available in Slack conversations without being added to the saved config, unless explicitly disabled. The builder only shows this tool when it is explicitly listed in the config.
 
+### Deferred tools
+
+Set `deferred: true` on any tool (built-in, custom, or MCP) to keep its definition out of the model's context until the model asks for it. Deferring a tool implicitly enables the built-in `tool_search` tool, which the model calls with a regular expression to load matching deferred tools by name, description, and argument names. Keep the tools the agent needs on almost every turn loaded; defer large or rarely used tool sets.
+
+```yaml
+tools:
+  web_search: {}                # always loaded
+  web_fetch:
+    deferred: true              # loaded only after a tool_search match
+```
+
+Deferred loading keeps the provider's prompt cache intact on Anthropic Messages and OpenAI Responses. On Chat Completions the model calls loaded tools through `call_deferred_tool` with the tool's name and arguments, so `call_deferred_tool` is a reserved tool name.
+
 ### Custom tools
 
 A custom tool describes an operation that your system performs. Its `description` tells the model when to use it, and its `input_schema` defines the arguments.

docs/tools/built-in.mdx

@@ -20,6 +20,7 @@ The tools are grouped by what they do:
 | Files | `upload_file`, `download_file`, `read_file`, `search_files` |
 | Integrations | `send_integration_message`, `set_integration_target` |
 | Skills | `skill` |
+| Tool loading | `tool_search` |
 
 A red <span style={{ color: "#c97a7a", fontWeight: 700 }}>*</span> marks required inputs.
 
@@ -266,6 +267,17 @@ Lists the agent's subagents with their `agent_id`, name, key, state, and last ac
 
 Loads an attached skill. Requires its [skill](/tools/skills) `name`. The tool returns the skill's instructions and, when the agent has machines, installs its supporting files there.
 
+## Tool loading
+
+### `tool_search`
+
+Added automatically when any tool is [deferred](/agents/configuration#deferred-tools). Searches deferred tools by name, description, and argument names, and loads the matches so the model can call them.
+
+| Input | Type | Notes |
+| --- | --- | --- |
+| `pattern`<span style={{ color: "#c97a7a", fontWeight: 700 }}>*</span> | string | Case-insensitive regular expression, at most 200 characters |
+| `max_results` | integer | 1–50; default 5 |
+
 <Info>
 Full inputs and defaults, live from your deployment: [Get tool catalog](/api-reference/endpoints/configs-and-profiles/get-tool-catalog).
 </Info>

docs/tools/mcp.mdx

@@ -48,6 +48,7 @@ mcp:
 | `auth.region` | AWS signing region. Required for `sigv4`. |
 | `permission` | Server-wide default mode; per-tool `permission` overrides it. MCP tools default to `always_ask` — third-party code asks first. |
 | `default_enabled` | `false` disables tools by default. Set `enabled: true` for each tool you want to expose. |
+| `deferred` | `true` keeps the server's tools out of the model's context until `tool_search` loads them; per-tool `deferred` overrides it. See [Deferred tools](/agents/configuration#deferred-tools). |
 
 ### How MCP tools are named
 

frontend/apps/web/src/components/agents/AgentConfigMcpServersField.tsx

@@ -209,7 +209,7 @@ export function AgentConfigMcpServersField({
                 <div className="pb-2">
                   <OverridesCollapsible title="Tools" keepMounted>
                     <div className="space-y-4">
-                      <div className="grid gap-4 sm:grid-cols-2">
+                      <div className="grid gap-4 sm:grid-cols-3">
                         <Field>
                           <FieldLabel>Default permission</FieldLabel>
                           <Select
@@ -261,6 +261,29 @@ export function AgentConfigMcpServersField({
                             </SelectContent>
                           </Select>
                         </Field>
+                        <Field>
+                          <FieldLabel>Default loading</FieldLabel>
+                          <Select
+                            value={server.deferred ? 'deferred' : 'loaded'}
+                            onValueChange={(value) => {
+                              updateServer(server.id, {
+                                deferred: value === 'deferred' || undefined,
+                              })
+                            }}
+                          >
+                            <SelectTrigger className="w-full" aria-label="MCP default loading">
+                              <SelectValue>{server.deferred ? 'Deferred' : 'Loaded'}</SelectValue>
+                            </SelectTrigger>
+                            <SelectContent>
+                              <SelectItem value="loaded">Loaded</SelectItem>
+                              <SelectItem value="deferred">Deferred</SelectItem>
+                            </SelectContent>
+                          </Select>
+                          <FieldDescription>
+                            Deferred tools stay out of the model&apos;s context until it finds them
+                            with tool_search.
+                          </FieldDescription>
+                        </Field>
                       </div>
                       <AgentConfigMcpServerTools
                         orgId={orgId}

frontend/apps/web/src/components/agents/AgentConfigMcpToolOverrideList.tsx

@@ -170,6 +170,27 @@ function ToolOverrideRow({
           ))}
         </SelectContent>
       </Select>
+      <Select
+        value={tool.deferred == null ? inheritValue : tool.deferred ? 'deferred' : 'loaded'}
+        onValueChange={(value) => {
+          onChange({ deferred: value === inheritValue ? null : value === 'deferred' })
+        }}
+      >
+        <SelectTrigger
+          size="sm"
+          className="min-w-0 flex-1 sm:w-32 sm:flex-none"
+          aria-label={`${tool.name} loading`}
+        >
+          <SelectValue>
+            {tool.deferred == null ? 'Default' : tool.deferred ? 'Deferred' : 'Loaded'}
+          </SelectValue>
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value={inheritValue}>Default</SelectItem>
+          <SelectItem value="loaded">Loaded</SelectItem>
+          <SelectItem value="deferred">Deferred</SelectItem>
+        </SelectContent>
+      </Select>
       <Button
         type="button"
         size="icon"

frontend/apps/web/src/components/agents/AgentConfigToolPreview.test.tsx

@@ -334,7 +334,7 @@ it('does not offer the Slack tool when it is absent from the source', async () =
     {
       source_format: 'json',
       source: JSON.stringify({
-        tools: { web_search: {} },
+        tools: { web_search: { type: 'built_in', permission: { mode: 'always_ask' } } },
         mcp: {},
         machine_sources: [],
         skills: [],
@@ -362,7 +362,9 @@ it('includes configured MCP servers in previews and removes them after deletion'
     />,
   )
   await vi.waitFor(() => {
-    expect(requests.at(-1)).toHaveProperty('mcp', { docs: { url: 'https://example.com/mcp' } })
+    expect(requests.at(-1)).toHaveProperty('mcp', {
+      docs: { url: 'https://example.com/mcp', default_enabled: false },
+    })
   })
   clickLabel('Remove MCP')
   await vi.waitFor(() => {

frontend/apps/web/src/components/agents/AgentConfigToolsField.tsx

@@ -28,6 +28,7 @@ export interface BasicTool {
   name: string
   enabled?: boolean
   permission: PermissionSelection | null
+  deferred?: boolean
 }
 
 const toolDescriptions = new Map([
@@ -62,7 +63,7 @@ export function AgentConfigToolsField({
 }) {
   const catalogTools = catalog?.built_in_tools ?? []
   const catalogByName = new Map(catalogTools.map((entry) => [entry.name, entry]))
-  const displayedTools = [
+  const displayedTools: BasicTool[] = [
     ...tools,
     ...(resolvedTools ?? [])
       .filter((tool) => !tools.some((configured) => configured.name === tool.name))
@@ -155,6 +156,19 @@ export function AgentConfigToolsField({
                     )
                   }}
                 />
+                <ToolLoadingSelect
+                  name={tool.name}
+                  deferred={tool.deferred === true}
+                  onChange={(deferred) => {
+                    onToolsChange(
+                      tools.map((currentTool) =>
+                        currentTool.name === tool.name
+                          ? { ...currentTool, deferred: deferred || undefined }
+                          : currentTool,
+                      ),
+                    )
+                  }}
+                />
                 <Button
                   type="button"
                   size="icon"
@@ -319,6 +333,42 @@ function ToolName({ name, entry }: { name: string; entry?: ToolCatalogEntry }) {
   )
 }
 
+export function ToolLoadingSelect({
+  name,
+  deferred,
+  onChange,
+}: {
+  name: string
+  deferred: boolean
+  onChange: (deferred: boolean) => void
+}) {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <div className="min-w-0 flex-1 sm:w-28 sm:flex-none">
+          <Select
+            value={deferred ? 'deferred' : 'loaded'}
+            onValueChange={(value) => {
+              onChange(value === 'deferred')
+            }}
+          >
+            <SelectTrigger size="sm" className="w-full" aria-label={`${name} loading`}>
+              <SelectValue>{deferred ? 'Deferred' : 'Loaded'}</SelectValue>
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="loaded">Loaded</SelectItem>
+              <SelectItem value="deferred">Deferred</SelectItem>
+            </SelectContent>
+          </Select>
+        </div>
+      </TooltipTrigger>
+      <TooltipContent side="top" className="max-w-xs px-3 py-2 text-sm leading-relaxed">
+        Deferred tools stay out of the model&apos;s context until it finds them with tool_search.
+      </TooltipContent>
+    </Tooltip>
+  )
+}
+
 function permissionModeLabel(entry: ToolCatalogEntry | undefined, value: string) {
   return entry?.permission_modes.find((mode) => mode.name === value)?.label ?? value
 }

frontend/apps/web/src/components/agents/agentConfigBasicExtract.ts

@@ -3,6 +3,7 @@ import { type Document, isAlias, isScalar, visit } from 'yaml'
 import { z } from 'zod'
 
 import type { BasicSubagent } from '@/components/agents/agentConfigSubagents'
+import type { BasicTool } from '@/components/agents/AgentConfigToolsField'
 import type {
   BasicConfig,
   BasicMachineSource,
@@ -81,6 +82,7 @@ const mcpAuth = z.discriminatedUnion('type', [
 const mcpToolEntry = z.strictObject({
   enabled: z.boolean().nullable().optional(),
   permission: permission.optional(),
+  deferred: z.boolean().nullable().optional(),
 })
 
 export type McpToolEntry = z.infer<typeof mcpToolEntry>
@@ -89,6 +91,7 @@ const mcpEntry = z.strictObject({
   url: z.string(),
   permission: permission.optional(),
   default_enabled: z.boolean().nullable().optional(),
+  deferred: z.boolean().optional(),
   auth: mcpAuth.optional(),
   tools: z.record(z.string(), mcpToolEntry).optional(),
 })
@@ -99,6 +102,7 @@ const toolEntry = z.strictObject({
   type: z.literal('built_in').optional(),
   enabled: z.boolean().nullable().optional(),
   permission: permission.optional(),
+  deferred: z.boolean().optional(),
 })
 
 export type ToolEntry = z.infer<typeof toolEntry>
@@ -174,11 +178,7 @@ export function extractBasicConfig(document: Document): BasicConfig | null {
     providerConfig: doc.model?.provider_config ?? '',
     modelName: doc.model?.name ?? '',
     machineSources,
-    tools: Object.entries(doc.tools ?? {}).map(([name, entry]) => ({
-      name,
-      enabled: entry.enabled ?? undefined,
-      permission: permissionDraft(entry.permission),
-    })),
+    tools: Object.entries(doc.tools ?? {}).map(([name, entry]) => toolDraft(name, entry)),
     mcpServers: Object.entries(doc.mcp ?? {}).map(([name, entry]) => mcpServerDraft(name, entry)),
     skillIds: doc.skills ?? [],
     subagents: Object.entries(doc.subagents ?? {}).map(([key, entry]) => subagentDraft(key, entry)),
@@ -205,6 +205,16 @@ export function normalizeMultiline(value: string) {
   return value.replace(/\r\n?/g, '\n').trimEnd()
 }
 
+function toolDraft(name: string, entry: z.infer<typeof toolEntry>): BasicTool {
+  const draft: BasicTool = {
+    name,
+    enabled: entry.enabled ?? undefined,
+    permission: permissionDraft(entry.permission),
+  }
+  if (entry.deferred) draft.deferred = true
+  return draft
+}
+
 function permissionDraft(
   value: z.infer<typeof permission> | undefined,
 ): PermissionSelection | null {
@@ -267,7 +277,7 @@ function countDraft(value?: number): string {
 
 function mcpServerDraft(name: string, entry: z.infer<typeof mcpEntry>): BasicMcpServer {
   const auth = entry.auth
-  return {
+  const draft: BasicMcpServer = {
     id: crypto.randomUUID(),
     name,
     url: entry.url,
@@ -277,12 +287,18 @@ function mcpServerDraft(name: string, entry: z.infer<typeof mcpEntry>): BasicMcp
     secretId: auth?.secret_id ?? '',
     service: auth?.type === 'sigv4' ? auth.service : '',
     region: auth?.type === 'sigv4' ? auth.region : '',
-    tools: Object.entries(entry.tools ?? {}).map(
-      ([name, tool]): BasicMcpTool => ({
-        name,
-        enabled: tool.enabled ?? null,
-        permission: permissionDraft(tool.permission),
-      }),
-    ),
+    tools: Object.entries(entry.tools ?? {}).map(([name, tool]) => mcpToolDraft(name, tool)),
+  }
+  if (entry.deferred) draft.deferred = true
+  return draft
+}
+
+function mcpToolDraft(name: string, tool: z.infer<typeof mcpToolEntry>): BasicMcpTool {
+  const draft: BasicMcpTool = {
+    name,
+    enabled: tool.enabled ?? null,
+    permission: permissionDraft(tool.permission),
   }
+  if (tool.deferred != null) draft.deferred = tool.deferred
+  return draft
 }

frontend/apps/web/src/components/agents/agentConfigMcp.ts

@@ -11,6 +11,7 @@ export interface BasicMcpTool {
   name: string
   enabled: boolean | null
   permission: PermissionSelection | null
+  deferred?: boolean | null
 }
 
 export interface BasicMcpServer {
@@ -19,6 +20,7 @@ export interface BasicMcpServer {
   url: string
   permission: PermissionSelection | null
   defaultEnabled: boolean
+  deferred?: boolean
   authType: McpAuthType
   secretId: string
   service: string
@@ -30,6 +32,7 @@ export function mcpWire(server: BasicMcpServer): McpEntry {
   const wire: McpEntry = { url: server.url.trim() }
   if (server.permission != null) wire.permission = permissionWire(server.permission)
   wire.default_enabled = server.defaultEnabled
+  if (server.deferred) wire.deferred = true
   if (server.authType !== 'none') {
     const secretId = server.secretId.trim()
     wire.auth =
@@ -42,7 +45,9 @@ export function mcpWire(server: BasicMcpServer): McpEntry {
           }
         : { type: server.authType, secret_id: secretId }
   }
-  const tools = server.tools.filter((tool) => tool.enabled != null || tool.permission != null)
+  const tools = server.tools.filter(
+    (tool) => tool.enabled != null || tool.permission != null || tool.deferred != null,
+  )
   if (tools.length > 0) {
     wire.tools = Object.fromEntries(tools.map((tool) => [tool.name, mcpToolWire(tool)]))
   }
@@ -53,6 +58,7 @@ function mcpToolWire(tool: BasicMcpTool): McpToolEntry {
   const wire: McpToolEntry = {}
   if (tool.enabled != null) wire.enabled = tool.enabled
   if (tool.permission != null) wire.permission = permissionWire(tool.permission)
+  if (tool.deferred != null) wire.deferred = tool.deferred
   return wire
 }