infrastructureL4 OptimizedMCP & Tool Integration

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.

·Toolshed model: 400+ tools accessible behind a unified MCP gateway (Stripe model)
·Agent discovery: agents can query available tools and their capabilities at runtime
·MCP governance covers lifecycle management, versioning, and audit logging

·MCP tool usage analytics track which tools are used, by which agents, how often
·MCP server versioning allows rollback to previous versions without downtime

Evidence

·MCP gateway configuration showing 400+ registered tools
·Agent discovery API or protocol documentation with runtime tool listing
·MCP governance logs showing lifecycle events (deploy, version, deprecate, audit)

What It Is

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."

Why It Matters

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

Getting Started

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.
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").
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.
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.
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.
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.

Tip

Write tool descriptions as if writing for a new employee who knows the domain but doesn't know your specific tools. Don't assume the agent knows your tool names or your naming conventions. The description should convey what the tool does, when to use it, and what kind of response to expect.

6 steps to get from here to the next level

Common Pitfalls

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.

Mistakes teams actually make at this stage - and how to avoid them

How Different Roles See It

BobHead of Engineering

Bob's organization has deployed a Toolshed gateway with 50+ tools, but agents aren't using the newer tools even when those tools would clearly improve their output. The deployment team added a deployment trigger tool three months ago; agents still ask developers to manually trigger deployments rather than using the tool.

What Bob should do: Bob should audit the deployment trigger tool's description and compare it to tools the agents do use successfully. The gap almost always turns out to be in description specificity. A tool named "trigger_deployment" with a description of "Triggers a deployment pipeline" will be skipped by an agent that doesn't know whether this is the right trigger for its current context. A description like "Use this tool to trigger a CI/CD deployment after tests pass - provide the branch name and target environment (staging or production)" gives the agent the context to recognize when to use it. Bob should establish a rule: any tool added to the Toolshed must go through a description review where a team member (not the tool author) confirms the description is clear enough to guide correct use.

What Bob should do - role-specific action plan

SarahProductivity Lead

Sarah wants to use agent discovery to enable a new class of workflows: agents that adapt to the specific environment they're running in (development, staging, production-limited) without requiring separate agent configurations for each environment.

What Sarah should do: Sarah should design environment-scoped tool sets as the foundation for adaptive agents. The development environment exposes: all read tools, code write tools, staging deployment tools. The staging environment adds: staging database read tools, integration test triggers. The production environment adds: read-only production metrics, alert acknowledgment. When an agent discovers its tools, it implicitly understands its current environment based on what's available - no explicit environment variable needed. Sarah should build this capability as a standard pattern and document it as the team's approach to environment-aware agents. The same agent binary runs in all environments; its behavior adapts based on what tools are available via discovery.

What Sarah should do - role-specific action plan

VictorStaff Engineer - AI Champion

Victor is building a meta-agent that orchestrates other agents for complex, multi-step workflows. He wants the orchestrator agent to know what capabilities are available before deciding how to break down a task - essentially using tool discovery as a capability introspection mechanism before planning.

What Victor should do: Victor should implement discovery as the first step of the orchestrator's task decomposition process. When a new task arrives, the orchestrator queries available tools, reasons about which tools are relevant to the task, and decomposes the task into subtasks based on available capabilities. A task that requires database access is only assigned to a sub-agent if database tools are available; otherwise, the orchestrator routes the task differently. This discovery-driven planning makes the orchestrator resilient to tool availability changes and enables capabilities like "if the deploy tool is available, include deployment verification in the plan; if not, end at code commit." Victor should document this pattern as the standard approach for orchestrator agents in the team's agent architecture.

What Victor should do - role-specific action plan