Tool Discovery and the Tool Overload Problem

The previous subtopic showed that mcp-use's agent setup 'discovers available tools, and exposes them to the LLM in a structured way.' That discovery step sounds simple, but it creates a real problem once the number of discovered tools grows — this is exactly the common pitfall this course calls out directly.

When LLMs gain access to many server tools, certain predictable issues appear. This course documents 3 specific failure modes:

1. Tool-name hallucinations — the model may invent a tool that does not exist. This usually happens when the tool list is large or poorly named, since the model is essentially pattern-matching against a long list of similar-sounding names and can 'blend' two real tool names into one that was never actually registered.

2. Confusion between similar tools — if a server exposes several tools with overlapping responsibilities, the model may struggle to choose the correct one. Two tools that both 'search' something, or both 'update' something, become genuinely hard for the model to disambiguate from their names and descriptions alone.

3. Degraded decision quality with large toolsets — presenting too many tools at once increases cognitive load for the LLM, leading to inconsistent tool selection or unnecessary calls. This isn't specific to any one tool being confusing; it's a general degradation that comes purely from the SIZE of what's being presented, regardless of how well each individual tool is named or described.

This course is explicit that these issues arise from typical LLM behavior when exposed to large toolsets — meaning this isn't a bug in a particular model or a fixable prompt-engineering problem alone; it's a structural consequence of how much a model can effectively reason over at once, closely related to the context-window and cognitive-load concerns covered elsewhere in this curriculum. This is precisely the motivation for the Server Manager mechanism covered in the next subtopic — a purpose-built fix for exactly these 3 failure modes.

# Illustrating why tool discovery at scale creates the 3 documented
# failure modes -- purely from toolset SIZE, not any one bad tool.

def simulate_tool_selection_difficulty(tool_names: list[str], query: str) -> dict:
    """A stand-in for what an LLM faces when many similar tool
    names are all presented in its context at once."""
    overlapping = [t for t in tool_names if any(kw in t for kw in ["search", "get", "fetch"])]
    return {
        "total_tools_in_context": len(tool_names),
        "overlapping_candidates": overlapping,   # source of failure mode #2
        "hallucination_risk": "high" if len(tool_names) > 20 else "low",  # failure mode #1
        "cognitive_load": "high" if len(tool_names) > 20 else "manageable",  # failure mode #3
    }

many_tools = [
    "search_flights", "search_hotels", "get_flight_status", "fetch_flight_price",
    "search_car_rentals", "get_weather", "fetch_weather_forecast",
    # ... imagine 20+ more, spread across multiple connected servers
]
print(simulate_tool_selection_difficulty(many_tools, "find me a flight"))