# Tool shadowing

**Source:** https://promtable.com/glossary/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.

---
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.

## Related terms

- [tool-use](https://promtable.com/glossary/tool-use)
- [agent](https://promtable.com/glossary/agent)
- [tool-router](https://promtable.com/glossary/tool-router)
- [agent-loop](https://promtable.com/glossary/agent-loop)

*Last updated: 2026-06-01*
---

Original page: https://promtable.com/glossary/tool-shadowing
Maintained by Promtable (https://promtable.com). Content: CC BY 4.0. Cite as "Promtable — https://promtable.com/glossary/tool-shadowing".
Contact: info@vibecodingturkey.com.