Why it matters
A model can only call tools it has been told about, and the context window is finite. With five tools, listing everything works. With fifty, descriptions crowd out the task and selection accuracy drops because similar names compete. With a protocol, the list can change between sessions, which adds staleness to the problem. Discovery exists to decide which subset of a large, changing catalogue enters the context for a given request.
Mental model
Tool discovery is a toolbox with a label on each drawer: you open the drawer that matches the job. The metaphor breaks because the labels are written by different teams, some drawers contain the same tool under two names, and the model reads all the labels at once.
How it works
- 1Maintain a registry of tools with a canonical name, a one-line purpose, an owner and a permission scope.
- 2Filter the registry by the caller's permissions before any selection, so the model never sees a tool it cannot use.
- 3For small catalogues, list all tools with concise descriptions and accept the token cost.
- 4For large catalogues, embed tool descriptions and retrieve the top few per request, then include their full schemas.
- 5Deduplicate near-identical tools and rename overlapping ones so the choice is decidable from the description alone.
- 6Refresh the registry on change notifications and expire cached descriptions, so a renamed tool does not linger.
Step 1 of 6
Maintain a registry of tools with a canonical name, a one-line purpose, an owner and a permission scope.
Figure. The mechanism in this page's own steps. The figure adds sequence, not new claims.
What to notice. A step can be read alone, but the order is the mechanism. The control lets you stop on any one.
Text version
The page's steps: 1. Maintain a registry of tools with a canonical name, a one-line purpose, an owner and a pe… 2. Filter the registry by the caller's permissions before any selection, so the model never … 3. For small catalogues, list all tools with concise descriptions and accept the token cost. 4. For large catalogues, embed tool descriptions and retrieve the top few per request, then … 5. Deduplicate near-identical tools and rename overlapping ones so the choice is decidable f… 6. Refresh the registry on change notifications and expire cached descriptions, so a renamed…
- Maintain a registry of tools with a canonical name, a one-line purpose, an owner and a permission scope.
- Filter the registry by the caller's permissions before any selection, so the model never sees a tool it cannot use.
- For small catalogues, list all tools with concise descriptions and accept the token cost.
- For large catalogues, embed tool descriptions and retrieve the top few per request, then include their full schemas.
- Deduplicate near-identical tools and rename overlapping ones so the choice is decidable from the description alone.
- Refresh the registry on change notifications and expire cached descriptions, so a renamed tool does not linger.
Trade-offs
| Choice | Good for | Cost | Fails when |
|---|---|---|---|
| List every tool | No retrieval errors, full awareness | Context cost and selection confusion | The catalogue exceeds a few dozen tools |
| Retrieve tools per request | Scales to large catalogues | Misses tools the query did not resemble | The task needs an unfamiliar tool |
| Hierarchical namespaces | Readable grouping | Extra indirection in the name | The model picks the namespace and stops |
| Protocol discovery at runtime | Always current | Latency, staleness and trust in the server | The server is slow or unavailable |
Good for
No retrieval errors, full awareness
Cost
Context cost and selection confusion
Fails when
The catalogue exceeds a few dozen tools
- The catalogue exceeds a few dozen tools
- The task needs an unfamiliar tool
- The model picks the namespace and stops
- The server is slow or unavailable
Figure. Each choice with what it buys, what it costs, and the case where it loses.
What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.
Text version
Four trade-offs: List every tool is good for No retrieval errors, full awareness, costs Context cost and selection confusion, and fails when The catalogue exceeds a few dozen tools. Retrieve tools per request is good for Scales to large catalogues, costs Misses tools the query did not resemble, and fails when The task needs an unfamiliar tool. Hierarchical namespaces is good for Readable grouping, costs Extra indirection in the name, and fails when The model picks the namespace and stops. Protocol discovery at runtime is good for Always current, costs Latency, staleness and trust in the server, and fails when The server is slow or unavailable
Failure modes
- Wrong tool for the job. Two tools have similar descriptions and the model picks the broader one. Debug: log selection per query and review cases where the chosen tool's owner differs from the expected domain.
- Missing tool. Retrieval returns nothing relevant and the agent answers without tools. Debug: measure recall of the tool retriever against a labelled set of query-tool pairs.
- Stale catalogue. A tool was renamed on the server and the host still advertises the old name. Debug: diff the cached tool list against a fresh discovery call after each deploy.
In production
Monitor selection accuracy on a labelled query set and the token cost of the tool block. MCP mandates tools/list and change notifications, while cache lifetime and retrieval strategy are host choices, so alert when discovery returns a different tool count than the last snapshot.
Common misconceptions
People think: More tools always increase capability.
Actually: Past a point they reduce selection accuracy and consume context that the task needs.
People think: The model can search for a tool itself.
Actually: Only if the runtime exposes a search step; otherwise the catalogue must be selected before the call.
Interview angle
A strong answer frames discovery as retrieval with permissions and freshness, and gives a threshold for listing versus retrieving. It also mentions naming as an index problem. Weak answers say to put all tools in the prompt.
Sources
- MCP specification, Server Tools — tools/list, change notifications and schemas.
- Qin et al., ToolLLM — tool selection over a large API collection.
- Patil et al., Gorilla — retrieval of the right API for a request.