Multi-Tool Router (by Embedding)

Background

Agents with many tools need a router: which tool should this query call? The simplest approach: embed each tool's natural-language description, embed the query, return the most cosine-similar tool. Adding a new tool needs no code change — just a new description.

Problem statement

Implement route_to_tool(query_emb, tool_embs). L2-normalise both sides, compute cosine similarity, return the index of the most-similar tool. Tie-break by lower index via a stable argmax.

Input

• query_emb — 1-D np.ndarray of length $d$.
• tool_embs — 2-D np.ndarray shape $(n_{\text{tools}}, d)$.

Output

Returns a Python int in $[0, n_{\text{tools}})$.

Examples

Example 1 — picks the most-similar tool

Input:  q = [1, 0]; tools = [[0, 1], [1, 0], [0.5, 0.5]]
Output: 1   (tool 1 is parallel to q)

Example 2 — tie-break by lower index

Input:  q = [1, 0]; tools = [[1, 0], [1, 0], [0, 1]]
Output: 0

Example 3 — returns Python int, not numpy

Input:  any valid query and tools
Output: isinstance(result, int) is True

Constraints

• Add $\epsilon = 10^{-12}$ when normalising to avoid division-by-zero on zero vectors.
• Returns Python int, not np.int64.
• n_tools >= 1.

Notes

• vs LLM routing. An LLM-as-router is more flexible (chain-of-thought reasoning over the tool list) but vastly more expensive. Embedding routing is the right pre-filter at scale.
• Threshold. Real systems add a confidence threshold below which they fall back to "ask the LLM directly" — a tool with cosine 0.3 isn't a confident match.