A common early scaling failure in an agent tool ecosystem is not execution. It is attention.
An agent with access to ten tools can often keep the full menu in context. With hundreds of tools, multiple MCP servers, plugins, cloud systems, and local capabilities, keeping every complete definition visible becomes increasingly costly and confusing. The tool definitions compete with the user’s request, the working context, tool results, and the instructions that keep the system safe.
The naive answer is to preload everything and hope the model selects well. The opposite naive answer is to give the agent a search box and call the problem solved.
Both miss the real design problem.
Tool discovery is context engineering: it decides which capabilities the model is allowed to reason about at each point in a task.
Anthropic’s advanced-tool-use work makes the pressure visible. Its guidance describes large tool libraries where definitions alone can consume substantial context before an agent begins working, and recommends on-demand discovery so the model sees only the relevant interfaces. But retrieval is only the first step. A reliable system must also teach the agent which result is appropriate, what it can do, what it costs, and when it needs authority.
A proposed capability funnel
Virillio Code Editorial proposes treating tool access as a four-stage funnel rather than a binary “available / unavailable” state. The funnel is an editorial design model, not an MCP requirement or established industry standard.
- Stage: Catalog — What the agent sees: Compact capability metadata — Purpose: Establish that a kind of action exists — Common failure if skipped: The agent invents or overlooks capabilities
- Stage: Shortlist — What the agent sees: A small ranked set of candidate tools — Purpose: Narrow the decision to plausible options — Common failure if skipped: Search returns too many near-duplicates
- Stage: Load — What the agent sees: Full tool contract, examples, constraints, and policy annotations — Purpose: Let the model form a correct call — Common failure if skipped: The model calls a tool from its name alone
- Stage: Operate — What the agent sees: The tool result and follow-up affordances — Purpose: Support the next decision and recovery — Common failure if skipped: The model treats execution as the end of the workflow
Each stage has a different context budget and a different reliability obligation.
This is why tool discovery is not merely an index. A search result should not pretend to be the same thing as an executable tool definition, and a loaded definition should not pretend to be permission to act.
Stage 1: Catalog the capability, not the whole schema
The catalog is the agent’s map of the tool ecosystem. It should be compact enough to keep available without crowding out the task.
Useful catalog fields include:
- capability area: source control, build, issue tracking, document search, deployment, or browser action;
- natural-language purpose;
- high-level resource scope;
- whether the action is observational, mutating, or consequential;
- server or plugin provenance;
- discoverability keywords and aliases;
- stability and availability status.
Avoid including every parameter and output schema in the catalog. At this stage, the agent needs to know that a capability exists and whether it is plausibly relevant—not memorize how to invoke it.
The catalog is also where namespacing earns its keep. Anthropic’s tool-design guidance notes that overlapping tools and vague functional boundaries make selection difficult for agents. A meaningful namespace lets the model distinguish “search project issues” from “search team messages” before it sees a dozen similar query schemas.
Stage 2: Shortlist by task, scope, and consequence
A keyword match is not enough. The shortlist should take account of three questions:
- Task fit: Does this tool advance the user’s actual goal?
- Scope fit: Can it act on the right workspace, account, project, or resource?
- Consequence fit: Is it read-only, reversible, or a side effect that needs confirmation?
For example, a user asks, “Find the regression and tell me what changed.” A high-quality shortlist might surface:
- a code-search capability,
- a test-history or issue-search capability,
- a log or commit-inspection capability.
It should not immediately load every deployment, billing, access-management, or content-publishing tool merely because “changed” is a loose keyword.
The shortlist is a deliberate decision boundary. It says: these are the capabilities worth giving the model more detail about now.
Make alternatives meaningful
Two tools can both match a query and still serve different strategies. Show the difference clearly:
- Candidate: Code search — Best when: The answer is likely in the current repository — Important limit: It cannot prove runtime behavior
- Candidate: Log search — Best when: The failure occurred in a known execution window — Important limit: It may expose incomplete or noisy data
- Candidate: Issue search — Best when: A known report or regression exists — Important limit: It may not reflect the current checkout
The agent can then choose a strategy rather than guessing from a similarly named tool.
Stage 3: Load the complete contract only when it is needed
Once a tool survives shortlisting, load the information required for a correct call:
- precise name and purpose;
- input schema and required fields;
- examples of appropriate use;
- result shape and pagination or artifact behavior;
- execution cost and likely latency;
- permission, confirmation, and side-effect annotations;
- known limitations and error-recovery guidance.
The MCP Tools specification defines several of these elements, including names, descriptions, input schemas, optional output schemas, and client-mediated safety considerations. The agent still needs a usable presentation of that contract. A raw schema alone cannot explain a workflow convention or tell a model when a tool overlaps another option.
This is also a useful boundary for progressive disclosure. Do not load a full integration just because one tool from it is relevant. A system can expose a narrowly selected operation while keeping the rest of the server’s capability set out of the active context.
Stage 4: Operate with a path back to discovery
Tool use is not linear. A loaded tool may return:
- no results,
- an ambiguity,
- a permission requirement,
- a partial result,
- a reference to another artifact,
- evidence that a different capability is now more appropriate.
The operation result should therefore include a next-step affordance, not just data. Examples:
- “No matching repository found; search workspaces by owner first.”
- “Results were truncated; load the next page with this cursor.”
- “This action requires user confirmation; here is the exact intended effect.”
- “The error suggests a project identifier; use the project-discovery tool before retrying.”
In other words, discovery does not end when a tool is called. A well-designed system lets an agent return to the catalog or shortlist when reality invalidates the initial plan.
The three kinds of tool metadata
Large ecosystems often mix metadata that serves different audiences. Keep them separate.
- Metadata type: Discovery metadata — Audience: Agent planning — Examples: Purpose, domain, aliases, high-level scope
- Metadata type: Invocation metadata — Audience: Agent execution and client validation — Examples: Input schema, output schema, examples, pagination
- Metadata type: Governance metadata — Audience: User and policy system — Examples: Consequence level, permissions, confirmation, audit requirements
Putting governance only in a prompt is risky: the model may not see it when a dynamically loaded tool becomes relevant. Putting invocation schemas in the catalog is expensive: they consume context even when the tool is never used. Putting discovery text only in a schema leaves the model with a structurally valid but strategically unclear choice.
The funnel lets each kind of metadata appear at the point where it is useful.
How to measure tool discovery
Do not use only execution success. Track the quality of selection:
- Catalog recall: Did the system surface the relevant capability when it existed?
- Shortlist precision: How many loaded tools were actually plausible for the task?
- Wrong-tool rate: Did the agent choose a near-duplicate or an irrelevant tool?
- Schema-correction rate: How often did a tool error teach the agent missing parameters?
- Context cost: How many definition tokens were loaded before the task advanced?
- Recovery quality: Could the agent discover a better tool after a failed first choice?
- Policy compliance: Did discovery preserve permission and confirmation boundaries?
These measures lead to different fixes. Low catalog recall may need better synonyms or a different taxonomy. High wrong-tool rate may need clearer namespacing or shortlist explanations. High schema-correction rate may need better examples. High context cost may mean the loader is too eager.
Anti-patterns to avoid
“All tools are always visible”
Keeping everything visible can work while the tool set is small. As it grows, complete definitions consume more context on every task and can increase confusion between similar capabilities.
“Search returns an executable action”
A search hit is a hypothesis, not permission to execute. Require the system to load the contract and apply the relevant policy before a side effect.
“Tool names are enough”
Names are weak interfaces. A model needs to understand purpose, conditions, examples, and limits to choose reliably.
“Discovery ignores scope”
A valid capability aimed at the wrong workspace, account, or project may create more risk than withholding it. Scope should participate in ranking and confirmation.
“Errors are dead ends”
A tool failure should often route the agent toward the missing capability, correction, or approval—not leave it guessing inside the same broken call.
A practical adoption path
Start with a tool inventory, not a new retrieval model.
- Assign each existing tool one primary purpose and consequence class.
- Identify near-duplicates and make their boundaries explicit.
- Define a compact catalog record for every tool.
- Build a shortlist that considers task, scope, and consequence.
- Load full schemas and examples only for shortlisted candidates.
- Add recovery links from result and error states back to discovery.
- Evaluate selection, correction, context cost, and policy compliance separately.
This approach works whether the underlying mechanism is MCP, function calling, a plugin registry, or an internal service catalog.
What we are learning building Virillio Code
Virillio Code’s tool-registry work remains in development, but the general design lesson is durable: access to a capability and model-visible understanding of that capability are different things. Good discovery makes the right tool easier to find, the wrong tool harder to call, and the next safe action clear after a failure.
Sources and further reading
- Advanced tool use — Large tool libraries create context and selection problems that can be addressed with progressive, on-demand discovery.
- Writing effective tools for AI agents — Useful agent tools need clear contracts, examples, and evaluation rather than names alone.
- MCP Tools specification — Tool interfaces can provide schemas, structured results, validation, access control, confirmation, and error handling.
Editorial disclosure
This article was substantially researched, drafted, and revised with AI through the Virillio Code editorial workflow. Virillio Code publishes the final text under its editorial byline, and the supporting primary sources are linked above.