Mastering MCP Tool Discovery: Zero-to-Hero Tutorial for LLM Agent Builders

In the rapidly evolving world of LLM agent architectures, the Model Context Protocol (MCP) has emerged as a game-changing standard for enabling seamless, dynamic interactions between AI models and external tools. This comprehensive tutorial takes you from zero knowledge to hero-level implementation of MCP Tool Discovery—the mechanism that powers intelligent, scalable agentic systems.

Whether you’re building production-grade AI agents, enhancing IDEs like VS Code, or creating Claude Desktop extensions, mastering tool discovery is essential for creating truly autonomous LLM workflows.[1][7]

What is Tool Discovery in MCP?

Tool Discovery in MCP refers to the standardized process where MCP clients (LLM hosts like chat interfaces or IDEs) dynamically query MCP servers to retrieve a complete list of available tools—executable functions that extend LLM capabilities beyond text generation.[1][3]

Unlike static function calling in traditional LLM APIs, MCP tool discovery enables:

• Runtime adaptability: Tools can be added, removed, or updated without restarting clients or servers
• Universal compatibility: Any MCP-compliant client can use tools from any MCP-compliant server
• Permission-controlled access: Users explicitly approve tool usage for security[3]

graph TD
    A[LLM Host<br/>(VS Code, Claude Desktop)] --> B[MCP Client]
    B --> C[tools/list Request]
    C --> D[MCP Server<br/>(Database, API, File System)]
    D --> E[tools/list Response<br/>JSON Schema Array]
    E --> B
    B --> F[LLM Tool Selection<br/>& Invocation]

Why Tool Discovery is Crucial for Dynamic LLM-to-Tool Interactions

Traditional agent systems suffer from brittle tool integration:

Dynamic discovery transforms agents from rigid scripts into adaptive systems that can:

1. Self-discover new capabilities at runtime
2. Handle tool churn gracefully (tools added/removed)
3. Optimize context by only loading relevant tools
4. Enable composability across multiple servers[6]

The Underlying Mechanism: tools/list and Dynamic Strategies

Core Discovery Flow

MCP tool discovery follows this precise protocol:[1][2][5]

// 1. Client queries available tools
await mcpClient.sendRequest('tools/list', {})

// 2. Server responds with tool definitions
{
  tools: [{    name: "calculate_sum",
    description: "Add two numbers together",
    inputSchema: {
      type: "object",
      properties: {
        a: { type: "number" },
        b: { type: "number" }
      }
    }
  }]
}

Dynamic Update Notifications

Servers notify clients of changes via WebSocket/push notifications:[1]

notifications/tools/list_changed

This enables zero-downtime tool updates—perfect for production agent pipelines.

Discovery Strategies Comparison

How Clients Query and Interpret Available Tools

Client-Side Implementation Pattern

Here’s a production-ready Node.js client that handles discovery + invocation:[2]

import { MCPClient } from '@modelcontextprotocol/client';

class AgenticMCPClient {
  constructor(serverUrl) {
    this.client = new MCPClient(serverUrl);
    this.tools = [];
  }

  async discoverTools() {
    const response = await this.client.sendRequest('tools/list', {});
    this.tools = response.tools.map(tool => ({
      ...tool,
      // Convert MCP schema to OpenAI-compatible format
      parameters: tool.inputSchema
    }));
    console.log(`Discovered ${this.tools.length} tools`);
  }

  async invokeTool(toolCall) {
    const result = await this.client.sendRequest('tools/call', {
      name: toolCall.name,
      arguments: toolCall.arguments
    });
    return result.content;
  }
}

LLM Integration Loop

The canonical agent loop with MCP discovery:[2]

async function agentLoop(userQuery) {
  // 1. Discover tools
  await mcpClient.discoverTools();
  
  // 2. Initial LLM call with discovered tools
  let messages = [{ role: 'user', content: userQuery }];
  let assistantResponse = await llmClient.chat({
    messages,
    tools: mcpClient.tools  // Dynamically discovered!
  });

  // 3. Handle tool calls iteratively
  while (assistantResponse.tool_calls?.length > 0) {
    for (const toolCall of assistantResponse.tool_calls) {
      const toolResult = await mcpClient.invokeTool(toolCall);
      messages.push({
        role: 'tool',
        tool_call_id: toolCall.id,
        content: toolResult
      });
    }
    
    // 4. Feed results back to LLM
    assistantResponse = await llmClient.chat({ messages });
  }
  
  return assistantResponse.content;
}

How Discovery Affects Prompt/Context Size

Context bloat is the #1 killer of production agents. MCP discovery helps by:

Baseline Context Costs

Static tools (100 tools × 200 tokens): 20K tokens
MCP dynamic (top-10 relevant tools): 2K tokens
Savings: 90% reduction

Optimization Techniques

1. Tool Filtering: Clients request only relevant tools based on query semantics
2. Pagination: tools/list?limit=20&offset=0
3. Compression: Use tool summaries instead of full schemas for initial discovery
4. Caching: Cache tool lists with TTL + subscribe to change notifications[1]

// Optimized discovery with filtering
const relevantTools = await mcpClient.sendRequest('tools/list', {
  filter: {
    categories: ['math', 'data'],
    maxTools: 10
  }
});

Practical Implementation: Building a Production MCP Server

FastMCP Server with Dynamic Tools (Python)

from fastmcp import FastMCP
from pydantic import BaseModel
import asyncio

app = FastMCP("MathAgent")

class SumInput(BaseModel):
    a: float
    b: float

@app.tool()
async def calculate_sum(state: SumInput) -> str:
    """Add two numbers together"""
    return str(state.a + state.b)

@app.list_tools()
async def list_tools():
    # Dynamic tool list - can change at runtime!
    return app.tools

if __name__ == "__main__":
    app.run()

Go Implementation with Discovery Package[6]

package main

import (
    "github.com/paularlott/mcp/discovery"
    "github.com/paularlott/mcp/server"
)

func main() {
    s := server.New()
    
    // Register dynamic tools
    discovery.RegisterTool(s, &discovery.Tool{
        Name: "db_query",
        InputSchema: discovery.Schema{
            Type: "object",
            Properties: map[string]discovery.Schema{
                "query": {Type: "string"},
            },
        },
    })
    
    s.Listen(":8080")
}

Common Pitfalls and How to Avoid Them

1. Context Bloat ⚠️

❌ BAD: Load all 500 tools every request
✅ GOOD: Semantic filtering + lazy loading

2. Stale Tool Lists

❌ BAD: Cache forever
✅ GOOD: TTL + tools/list_changed subscriptions

3. Schema Mismatches

❌ BAD: OpenAI schema ≠ MCP schema
✅ GOOD: Use MCP client libraries for conversion

4. Permission UX

❌ BAD: No user approval flow
✅ GOOD: Clear permission prompts per tool category

Best Practices for Scalable Tool Discovery

1. Implement Semantic Discovery

// Embed tool descriptions, search by query similarity
const relevantTools = await semanticSearch(userQuery, allTools);

2. Use Tool Sets/Groups [7]

{
  "toolset": {
    "name": "Database Tools",
    "tools": ["query_db", "list_tables"]
  }
}

3. Registry-Based Discovery

   • Central tool registry for enterprise
   • Versioning and deprecation handling
   • Security scanning integration

4. Monitoring & Observability

// Track discovery success rates
metrics.track('mcp_discovery', {
  success: true,
  tools_count: tools.length,
  latency_ms: 45
});

Advanced: Semantic + Registry-Based Systems

Hybrid Discovery Architecture

User Query → Semantic Router → [Registry → MCP Servers] → Filtered Tools

Implementation:

1. Embed tool descriptions in vector DB
2. Query-time semantic search finds top-K candidates
3. Batch MCP discovery for candidates only
4. Cache results with query embeddings as keys

This achieves 95% context reduction while maintaining 99% tool coverage.

Conclusion: Building the Future of Agentic Systems

MCP Tool Discovery isn’t just a protocol feature—it’s the foundation of truly autonomous, scalable LLM agents. By mastering dynamic discovery, you unlock:

• Universal tool interoperability
• Runtime adaptability
• Enterprise-grade scalability
• Developer productivity

Start small: implement tools/list in your next agent. Scale smart: add semantic discovery and registries. The agentic future belongs to those who master dynamic tool interactions.

Top 10 Authoritative MCP Tool Discovery Resources

1. MCP Official Tools & Discovery - Core protocol specification[1]
2. MCP Wiki Fundamentals - Beginner-friendly explanations
3. Google Cloud MCP Overview - Enterprise perspective[6]
4. DEV Community: MCP Server Concepts - Practical implementation guide
5. MCP Tool Discovery Strategies - Advanced patterns
6. Go MCP Discovery Package - Production Go implementation[6]
7. MCP Server Manager - Deployment utilities
8. Dynamic Self-Discovery Article - Strategic insights
9. The Verge: MCP Real-World Impact - Industry analysis
10. MCP Security & Monitoring - Production hardening

Build with MCP. Scale with discovery. Agentify everything. 🚀