XIV · Anti-PatternsAnti-pattern✕

Tool Loadout Hot-Swap

also known as Mid-Run Tool Set Mutation, Dynamic Tool Definitions Mid-Iteration, Reshuffling Tools During a Task

Anti-pattern: add or remove tool definitions during a running task so the tool set the model sees changes from turn to turn.

Context

A team is using an agent framework that grows or shrinks its tool palette dynamically during a run — exposing new MCP (Model Context Protocol) servers as the task moves into new territory, removing tools as conditions change, or swapping the registry between iterations of the loop. From the framework's perspective this looks like good hygiene against tool-explosion: only show the agent the tools it currently needs.

Problem

Mutating tool definitions in the middle of a running task invalidates the prefix key-value cache for everything in the conversation that came after the change, because the model conditions on the original system message and tool list. The agent then becomes uncertain which tools it can still call: recent turns may reference tools that have just been removed, or tools the model has not yet been told about, leading to hallucinated calls and broken composition between steps. The cost of the cache invalidation also shows up as a latency spike on the very next turn. Hot-swapping the loadout mid-run trades a small inventory benefit for serious correctness and performance damage.

Forces

  • Tool palettes feel like they should grow with the task as new affordances become relevant.
  • Removing tools mid-run looks like good hygiene against tool-explosion.
  • Modern LLM serving relies on prefix KV-cache reuse; any change above the cursor invalidates it.
  • The model conditions on the system message and earlier turns; redefining tools makes those conditioning tokens contradict the present state.

Example

A research agent dynamically attaches MCP servers as new domains become relevant during a long-running task. Each attachment redefines the tool list mid-run; KV-cache hit rate drops to near zero and per-step latency triples. Worse, the agent occasionally tries to call a tool that was just unmounted, because earlier turns referenced it. The team switches to a stable loadout for the whole run plus logit masking to constrain which tools are callable in a given state. KV-cache reuse returns and the contradictory tool references disappear.

Diagram

Solution

Therefore:

Don't mutate tool definitions mid-task. Define the tool palette once at the start of a run and keep it stable. To constrain what the model is allowed to call in a given state, mask the corresponding tool-name token logits during decoding (or use response prefill) instead of removing the tool. See tool-loadout (pick the subset at run start, not mid-run), tool-search-lazy-loading (discover tools without redefining the registry), prompt-caching (KV-cache reuse depends on stable prefixes).

What this pattern forbids. By definition, this anti-pattern imposes no useful constraint; the missing rule — tool definitions must not change mid-run — is itself the failure mode.

And the patterns that stand alongside it, or against it —

  • alternative-toTool Loadout★★— Select a small task-relevant subset of available tools per request rather than exposing the full registry to the model.
  • alternative-toTool Search Lazy Loading★— Defer loading tool schemas into the context window until a search step shows they are needed.
  • complementsPrompt Caching★★— Order prompts so the unchanging prefix can be cached by the provider, cutting per-call cost and latency.
  • complementsTool Explosion✕— Anti-pattern: expose every available tool in every request and watch function-calling accuracy collapse.
  • complementsTool Over-Broad Scope✕— Anti-pattern: grant the agent tools scoped so broadly that a single hallucinated argument can escalate into a privilege incident.
  • complementsProgressive Tool Access★— Grant tool permissions on a need-to-use basis, starting minimum and expanding only as the agent proves competency, mirroring how humans earn system access.

Neighbourhood

Click any neighbour to follow the language. Scroll to zoom, drag to pan.

References

Provenance