Fixing the 'No tool found with name' ValueError in CrewAI

The Error Message

Few things are more frustrating than your multi-agent system crashing just as it starts thinking. You might see a traceback like this right after the agent attempts to take an action:

ValueError: No tool found with name 'search_tool'. Make sure you have registered the tool correctly.

Why Is This Happening?

CrewAI is strict about its execution context. Unlike simpler wrappers, it requires a direct link between an agent and the tools it is allowed to touch. This error triggers when the LLM decides to use a specific tool, but that tool isn't in its local registry.

Usually, one of these three culprits is to blame:

• The tool exists in your script but wasn't passed to the Agent constructor.
• You passed a list of strings (names) instead of the actual tool objects.
• There is a name mismatch between your custom @tool decorator and the agent's expectations.

Fix 1: Explicitly Register Tools with the Agent

The most frequent cause is a missing entry in the agent definition. Defining a tool globally doesn't automatically grant agents access to it. You must explicitly pass it through the tools parameter.

The Broken Way:

from crewai import Agent
from crewai_tools import SerperDevTool

search_tool = SerperDevTool()

# The agent is blind to the search_tool here
researcher = Agent(
  role='Researcher',
  goal='Find 2024 AI trends',
  backstory='Expert researcher',
  verbose=True
)

The Correct Way:

from crewai import Agent
from crewai_tools import SerperDevTool

search_tool = SerperDevTool()

# Pass the tool object inside a list
researcher = Agent(
  role='Researcher',
  goal='Find 2024 AI trends',
  backstory='Expert researcher',
  verbose=True,
  tools=[search_tool] # This links the object to the agent
)

Fix 2: Pass Objects, Not Strings

CrewAI expects a List[BaseTool], not a List[str]. If you try to pass tools=['search_tool'], the agent will fail. It cannot resolve a string name into an executable function on its own.

# WRONG: This will trigger the ValueError
agent = Agent(..., tools=['search_tool'])

# RIGHT: Pass the instance
search_tool = SerperDevTool()
agent = Agent(..., tools=[search_tool])

Fix 3: Align Custom Tool Names

If you use the @tool decorator, the function name becomes the tool's unique ID. If you manually override the name in the decorator, you must ensure the LLM knows that exact name. A single typo here will break the execution loop.

from langchain.tools import tool

@tool("web_search_api")
def my_custom_search(query: str):
    """Useful for web searches."""
    return "Results..."

# The tool is now registered as "web_search_api", NOT "my_custom_search"
researcher = Agent(
    role='Analyst',
    tools=[my_custom_search],
    verbose=True
)

Fix 4: Check Task-Level Tool Assignment

In CrewAI v0.28.0 and later, you can restrict tools to specific tasks. If a task description explicitly asks for a tool that the assigned agent doesn't have, the system may crash. Ensure the tool is available at the Task level if you want to be safe.

task1 = Task(
  description='Search for 5 specific AI startups.',
  expected_output='A list of names.',
  agent=researcher,
  tools=[search_tool] # Explicitly granting the tool to this task
)

Verification: Run a Health Check

To confirm the fix, add a print statement before you start your crew. This verifies that the agent actually "sees" the tools you think it has.

• Add print(f"Agent Tools: {researcher.tools}") to your script.
• Run the code. You should see a list of objects like [<SerperDevTool name='search_tool'>].
• Watch the logs. If verbose=True, you should see Action: search_tool followed by Observation. If the loop continues, the mapping is successful.

Pro-Tips for Prevention

Keep your environment clean. Run pip install --upgrade crewai crewai-tools to ensure you aren't fighting bugs from older versions. Always use descriptive docstrings in custom tools. CrewAI uses those docstrings to tell the LLM exactly when and how to use the tool, preventing "hallucinated" tool names that don't exist in your registry.