Skip to content

Dynamic Tools

Dynamic tools keep the definitions of an agent's rarely used tools out of the model's context until the agent searches for them, which saves context on every request. Use them for agents with many optional tools.

Configuration

Field Type Default Effect
defer bool false Keep the tool's function definitions out of the model's context until the agent searches for them.
initial bool false Send a deferred tool as an ordinary tool on every request; requires defer: true.

A tool with neither flag is eager and appears in every request. The starter Mind agent from mindroom config init keeps shell, filesystem, memory, scheduler, update_awareness, and matrix_message eager and defers its other tools.

agents:
  assistant:
    display_name: Assistant
    role: Help in chat
    tools:
      - shell
      - filesystem: {defer: true, initial: true}
      - searxng: {defer: true, host: https://search.example.test, fixed_max_results: 10}
      - name: serper
        defer: true
        overrides: {num_results: 10}

These configurations fail validation:

  • initial: true without defer: true fails with Tool entry initial=true requires defer=true.
  • Deferral is per agent, so defaults.tools entries reject both flags with defaults.tools does not support defer or initial flags: <tools>.
  • Presets such as openclaw_compat cannot be deferred; set the flags on the individual member tools instead.
  • The control-plane tools agent_manager, contacts, delegate, dynamic_tools, external_trigger_manager, invite_router, self_config, and skill_manage cannot be deferred and fail with '<tool>' is a control-plane tool and cannot be deferred; defer/initial are only valid on runtime tools.

Standard-mode agents on these models use the provider's own tool search instead of MindRoom's:

  • Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, and newer on the anthropic and vertexai_claude providers.
  • GPT 5.4 and newer on openai, codex, and openai_codex.

For openai, an explicit api: chat_completions or a custom endpoint selects MindRoom's tool search instead. The endpoint is a non-empty extra_kwargs.base_url, otherwise OPENAI_BASE_URL; native search applies only when it is unset or https://api.openai.com/v1.

On this path, deferred tools stay out of the model's context until the model searches for them, and discovering a tool does not invalidate the prompt cache. The system prompt names the deferred toolkits and tells the model to search them before concluding that a tool is unavailable. Discovered tools are called directly. Deferred tools keep their toolkit and function instructions.

On every other model, an agent with at least one deferred tool gets the dynamic_tools toolkit, with tool_search(query, max_results) and call_tool(name, arguments). Voice calls and subagent personas with their own tool list send deferred tools as ordinary tools instead. The system prompt lists the deferred toolkits with their descriptions. tool_search matches function names, toolkit names, and keywords in descriptions and parameter names, and returns the full definitions of up to max_results functions (default 5, at most 20) with the instructions they and their toolkit would otherwise add to the system prompt. Without a query, tool_search lists each deferred function's name, toolkit, and description, without definitions; when they do not fit in one result it leaves out the descriptions, and if the names still do not fit it says how many functions it left out. The agent then calls a function with call_tool, passing its arguments as a JSON object; approval rules, hooks, and the chat display treat the call as a call of that function. Discovering and calling deferred tools never changes the tool list or the system prompt, so it does not invalidate the provider's prompt cache. Found definitions stay in the conversation until compaction summarizes them, after which the agent searches again. When two toolkits define a function with the same name, the one listed first in tools: provides it; if that one is deferred, the function stays hidden until the agent searches for it, so list the eager toolkit first to keep it visible.

Minimal Mode

In minimal mode, every request still exposes only Bash. The agent lists and calls its deferred tools through mindroom-agent like its other tools.