Tool-Catalog Indexing (Retrieval over Tools)
When the tool catalog is large, retrieve a small, relevant subset before presenting to the agent: do not dump the full catalog into every prompt.
This page is the complete instruction page for one pattern called "Tool-Catalog Indexing (Retrieval over Tools)." It explains the problem this pattern solves, the idea behind the solution, when you should (and should not) use it, and what happens afterward, both the good effects and the costs.
This matters because building AI agents is not just about making them clever. It is also about making them safe and predictable. Following a well-tested pattern like this one helps avoid common mistakes, and shows you exactly which safety rules and regulations it connects to, listed under "Standards Mesh" on this page.
Context
Model performance on tool selection degrades as catalog size increases. Presenting 200 tools per call both wastes tokens and confuses the model.
Problem
Flat tool catalogs scale poorly past roughly 30–50 tools.
Forces
- Breadth of capability vs selection accuracy
- Retrieval freshness vs cost
Solution
Index tool descriptions in a retrieval store. At runtime, retrieve the top-K tools relevant to the current goal or step. Re-retrieve on plan changes. Mandatory tools (e.g. search, human-handoff) are always included.
Where this pattern acts in the two lifecycles
03 Decide. Tool / route / next-action selection. 7 of 61 catalogue patterns act at this stage.
02 Build & Integrate. Model selection, tool wiring, memory design. 17 of 61 catalogue patterns act at this stage.
Stages and counts from the catalogue data. The Runtime lens is the loop the agent runs each turn; the AgentOps lens is the lifecycle the team runs the agent through. See the Matrix for every pattern at each stage.
Applicability
- Enterprise agent platforms
- Agents with >30 tools
- Marketplace / ecosystem agents
Anti-Patterns
- Hard-coded full catalog in every system prompt
- Pure alphabetical listing
Consequences
- +Scales past flat catalog limits
- +Selection accuracy preserved
- −Retrieval layer to maintain
- −Missed retrievals cause capability gaps
