Tool shadowing

Tool shadowing is when two or more tools in an agent's toolkit overlap in purpose enough that the model routes ambiguously — usually picking the worse one or oscillating between them.

When agent tool counts climb, related tools (search_web vs fetch_web_page, get_user vs lookup_account) start shadowing each other. The model sees overlapping descriptions, picks one for reasons that don't surface, and either uses the worse fit or alternates between them across steps. Diagnose by inspecting traces — count which tools were chosen on similar-shaped queries. Fix by tightening descriptions to be mutually exclusive, merging tools, or splitting the agent so each sub-agent has a focused non-overlapping toolkit. Tool shadowing is one of the most common reasons multi-tool agents under-perform single-tool ones.

Common mistakes

• Adding tools without auditing the description overlap with existing tools.
• Forcing multiple narrow tools where one general tool with branching args would route better.

FAQ

Related terms

• Tool use (LLM) — Tool use is the umbrella term for any LLM mechanism that lets the model invoke external functions, APIs, or services — function calling, code interpreter, MCP servers, browser actions.
• AI agent — An AI agent is a system where a language model autonomously plans and executes a sequence of tool calls to accomplish a goal.
• Tool router — A tool router is a layer in an agent that decides which tool to call (or which sub-agent to delegate to) for a given step — distinct from a model router which picks the underlying LLM.
• Agent loop — An agent loop is the repeating cycle of an AI agent — observe state, decide on an action (usually a tool call), execute, observe the result, and repeat — until a goal is reached or a stop condition fires.

Last updated: 2026-06-01. Raw markdown: https://promtable.com/glossary/tool-shadowing.md.