25,000 tools. About 2,000 tokens.
A catalog this size cannot be pasted into a prompt. Discovery ranks it against the task at hand and exposes a working set: small enough to be cheap, complete enough that the agent is never blocked.
Four stages, three orders of magnitude
Scope first, then semantics, then the tools that travel together. Each stage is cheap because the one before it did the heavy cutting.
Scope filter
The key's allowlist runs first. This is a correctness boundary, not an optimisation, but it also shrinks the candidate set before any expensive work.
Semantic rank
Tools are embedded from name, description, parameters and connector. The task is embedded the same way, which is what connects 'refund that order' to stripe.refund.create.
Co-occurrence expansion
Tools travel in packs. An agent that calls ticket.search almost always calls ticket.update next, so the read tool never arrives without its write counterpart.
Progressive disclosure
If the agent's next move falls outside the set, discovery re-runs mid-conversation and widens the window.
25,000 tools in catalog ≈ 2,500,000 tokens
│
├─ scope filter (key allowlist)
▼
400 candidates ≈ 48,000 tokens
│
├─ semantic rank (task embedding)
▼
40 candidates ≈ 4,800 tokens
│
├─ co-occurrence + dedupe
▼
18 tools exposed ≈ 2,100 tokens
reduction: 99.92% ranking time: 38msThe obvious answers all break somewhere
Tool selection is a retrieval problem with unusual properties: a small but highly structured corpus, a task rather than a keyword as the query, and a very high cost for a miss.
Send everything
Impossible at 25,000 tools, and expensive long before it becomes impossible. Every turn pays the full schema cost again.
Keyword match
'Close the loop with the customer' shares no word with zendesk.ticket.update. Lexical matching misses precisely the phrasing people actually use.
One connector at a time
Real tasks cross systems. The interesting ones always do: pipeline in Salesforce, digest in Slack, follow-up in Linear.
Let the user pick
Works until the task needs a tool nobody anticipated, which is most tasks worth automating.
The constraint improves the outcome
The counterintuitive result is that smaller tool sets make better agents. You are not compromising by showing fewer tools: you are removing the noise that was causing the mistakes. Four hundred tools contain a dozen near-duplicates across connectors, and a model asked to choose among them will eventually pick the wrong one.
Discovery questions
Why not just send every tool definition?
A realistic tool definition runs 80 to 150 tokens. Twenty-five thousand of them is around 2.5 million tokens of schema: far past any context window, and expensive well before it becomes impossible.
What if the agent needs a tool that was not in the working set?
Discovery re-runs mid-conversation. When the agent's next move needs something outside the current set, a second retrieval widens the window rather than failing the task.
Does discovery ever surface a tool my key cannot call?
No. Scope filtering runs before ranking, not after. A key without Stripe access will never see a Stripe tool ranked, returned or named in an error.
Does a smaller tool set make the agent worse?
The opposite, in our testing. A model choosing between eighteen relevant tools picks correctly far more often than one choosing between four hundred, where near-duplicates across connectors invite exactly the wrong call.
Can I pin tools that must always be available?
Yes. A key can carry a pinned set that is always exposed regardless of ranking, which is useful for the handful of tools an agent's core loop depends on.
Give your agent 25,000 tools and a small prompt
Connect your apps and watch which tools discovery actually surfaces for a real task.
No credit card required · Free tier available · Self-host on request