Fix: CrewAI Tool Not Found

Q: Does “tool not found” always crash the crew?

No. With the default **`warn`** policy, CrewAI records the failure and continues. Check `result.has_tool_failures` before trusting the final answer.

Beginner ~7 min read Last tested October 2026

Updated 2026-10-27

CrewAI records a tool not found failure when the model calls a tool name that is not registered on the agent, or when the tool object was never attached to that agent. The run may still finish, so you must inspect tool_failures or enable stricter policies. Last tested 2026-10-27.

Docs used:

Prerequisites

A CrewAI project (pip install 'crewai[tools]')
A failing crew or agent log that mentions an unknown tool name

Steps

1. Confirm the tool is on the same agent that runs the task

Tools are per agent. A tool on the researcher agent is invisible to writer.

from crewai import Agent, Task, Crew
from crewai_tools import SerperDevTool

search_tool = SerperDevTool()

researcher = Agent(
    role="Researcher",
    goal="Find facts",
    backstory="...",
    tools=[search_tool],  # must list every callable tool here
    verbose=True,
)

writer = Agent(
    role="Writer",
    goal="Draft copy",
    backstory="...",
    tools=[],  # writer cannot call search_tool unless you add it
    verbose=True,
)

If the log shows the writer invoking serper_search, either move the tool to writer or split the work into a research task owned by researcher.

2. Match the tool `name` to what the model emits

Custom tools must expose a stable name string. It should be short, unique, and described in description (the model reads the description when choosing tools).

from typing import Type
from crewai.tools import BaseTool
from pydantic import BaseModel, Field

class LookupInput(BaseModel):
    sku: str = Field(..., description="Product SKU to look up")

class InventoryTool(BaseTool):
    name: str = "inventory_lookup"
    description: str = "Return stock count for a SKU."
    args_schema: Type[BaseModel] = LookupInput

    def _run(self, sku: str) -> str:
        return f"{sku}: 12 units"

If you rename name in code but your prompt still says “call lookup_inventory”, the model may hit a tool not found path until prompts and names align.

3. Install optional tool packages

Built-in tools such as SerperDevTool and FileReadTool live in crewai_tools, installed with:

pip install 'crewai[tools]'

Import errors before the crew starts are different from tool-not-found at runtime, but a missing package often means you never attached the tool object at all.

4. Inspect failures after `kickoff`

CrewAI treats “agent called a missing tool” as a structured failure when policies are enabled:

result = crew.kickoff()

if result.has_tool_failures:
    for record in result.tool_failures:
        print(record.tool_name, record.failure.message)

See Reporting tool failures in the CrewAI docs.

5. Tighten policy while debugging

Default policy is warn. During development, set tool_failure_policy=ToolFailurePolicy.RAISE on the agent or task so missing tools stop the run immediately:

from crewai.tools.tool_failure import ToolFailurePolicy

researcher = Agent(
    ...,
    tools=[search_tool],
    tool_failure_policy=ToolFailurePolicy.RAISE,
)

6. Separate “tool not found” from tool execution errors

If the tool exists but returns an error string, the model may still narrate a failure without raising. Return ToolFailure from _run when the external API rejects the call (Slack channel_not_found, HTTP 403, etc.) so telemetry distinguishes missing tools from bad inputs.

Common errors

Model invents a tool name: Add explicit instructions (“Only use inventory_lookup”) and reduce the tool list to what the task needs.

Typo in @tool("name") decorator: The decorated name must match what you export in tools=[...].

Task delegation without tools: Delegated agents need their own tools= list; delegation does not inherit tools from the manager.

Async tool not awaited: Use async def _run only with CrewAI’s async tool support; a sync _run that returns a coroutine object can produce confusing failures. See Asynchronous tool support.

FAQ

Does “tool not found” always crash the crew?

No. With the default warn policy, CrewAI records the failure and continues. Check result.has_tool_failures before trusting the final answer.

Can one tool be shared by multiple agents?

Yes. Instantiate once and pass the same object in each agent’s tools list if that agent should call it.

Is this the same as LangGraph or OpenAI tool errors?

No. CrewAI’s missing-tool detection is specific to its agent runtime. For LangGraph loops, see Fix: LangGraph recursion limit.