Agent discovery: agent knows what tools are available

Agent discovery is the capability for an agent to dynamically enumerate what tools are available in its current environment and adapt its behavior accordingly. In the MCP protocol, this is implemented via the tools/list method: an agent connects to an MCP server and requests a list of all tools with their names, descriptions, input schemas, and permission requirements. The agent can then reason about which tools to use based on the task at hand, rather than being hardcoded to use a fixed set of tools specified at design time.

The practical significance is substantial. Without discovery, an agent workflow must be designed with a specific, known set of tools. If a new tool becomes available (say, a new MCP server is deployed), the agent doesn't know about it until its prompt or configuration is manually updated. With discovery, the agent queries its available tools at the start of each session and can use any tool that has been made available since the last update. New organizational capabilities are immediately accessible to agents without requiring agent code changes.

Discovery also enables adaptive agent behavior. An agent that discovers it has access to a production metrics tool can use that tool to validate its code changes against actual performance data. An agent without that tool gracefully degrades to a different validation approach. The agent makes these decisions dynamically based on what's available, not based on what was anticipated at design time. This is particularly important in large Toolshed deployments where the tool catalog evolves frequently and agents shouldn't need manual updates to use new capabilities.

The quality of tool descriptions is what makes discovery useful in practice. An agent that enumerates 400 tools and finds uniformly clear, specific descriptions can make good tool selection decisions. An agent that enumerates 400 tools with vague or inconsistent descriptions will either pick wrong tools or ignore tools it should use. Tool description quality is the often-overlooked bottleneck between "discovery is implemented" and "discovery actually improves agent behavior."

• Decouples agent development from tool availability - agents can use new tools as soon as they're deployed without requiring agent code changes; the tool deployment cycle and the agent development cycle are independent
• Enables environment-adaptive agents - an agent running in a production-access environment uses different tools than the same agent running in a development environment with restricted access; discovery makes this adaptation automatic
• Reduces agent maintenance overhead - agents hardcoded to specific tools break when those tools change; agents that discover tools dynamically are resilient to tool additions, removals, and renaming
• Powers the Toolshed model at scale - discovery is what makes 400 tools useful rather than overwhelming; without discovery, 400 tools require 400 manual configuration entries; with discovery, the agent finds them all automatically
• Creates a feedback loop for tool descriptions - when agents use discovery and pick wrong tools based on description ambiguity, the selection errors are visible in logs and motivate description improvements; this feedback loop continuously improves tool quality

1. Verify your MCP client supports tools/list - Claude Code, Cursor, and the Claude API all support the MCP tools/list method. Confirm your specific client version and configuration enables dynamic tool discovery rather than requiring a static tool list in the system prompt.
2. Audit your tool descriptions for discovery quality - for each tool, ask: would an agent with no prior knowledge of this tool, reading only the description, understand when to call it? Be specific about trigger conditions ("use this tool when you need to find which team owns a service or file") rather than generic ("ownership lookup tool").
3. Implement the tools/list endpoint - if you're building a custom MCP server, ensure the tools/list handler returns complete tool metadata: name, description, input schema with parameter descriptions, and any required context about when the tool should be used.
4. Test discovery-driven tool selection - give an agent a task that requires a specific tool without naming the tool in the task description. Observe whether the agent discovers and uses the right tool. If it picks the wrong tool or no tool, the issue is usually in the description quality.
5. Add tool categories to descriptions - with large tool catalogs, agents benefit from categorical context in descriptions. Prefix descriptions with the tool's domain: "[Incident Management] Use this tool to acknowledge an alert in PagerDuty." This helps agents quickly narrow from 400 tools to the relevant subset.
6. Monitor tool selection quality - add logging to track which tools agents select for which task types. Patterns where agents consistently pick the wrong tool for a task type, or consistently fail to use the right tool, reveal description gaps. Use these patterns to drive iterative description improvements.

Writing tool descriptions that describe the implementation, not the use case. "Calls the Jira REST API v3 getIssue endpoint with the issueKey parameter" tells an agent how the tool works, not when to use it. "Use this tool to retrieve the full details of a Jira ticket when you need to understand requirements, acceptance criteria, or issue status" tells the agent when to use it. The latter produces better tool selection.

Not updating descriptions when tool behavior changes. A tool that now does more than its description says will be under-utilized. A tool whose description promises capabilities it no longer has will cause agent failures. Tool description updates should be part of the same PR that changes tool behavior - never decoupled.

Assuming more tools is always better for discovery. Too many tools with overlapping capabilities confuse agents trying to select the right one. If you have five tools that all search documentation in slightly different ways, an agent will pick one semi-randomly. Consolidate overlapping tools; make each tool's scope distinct and non-overlapping.

Not handling the case where a needed tool isn't available. An agent that discovers a tool is unavailable should degrade gracefully - fall back to a different approach, ask a human for help, or clearly communicate the limitation. Agents that silently fail because a discovery attempt returned an empty tool list are hard to debug.