Lesson 6.7 · CrewAI

Tools in CrewAI

Give an agent a tool with @tool and tools=[...]. With llama3, CrewAI’s native tool call is refused and it falls back to the Thought / Action / Observation text format from Module 1. It worked on an easy question - and invented answers when the search found nothing. Searching in code first was faster and more honest.

crewai

What you will be able to do

Create a tool with @tool and give it to an agent
Explain what CrewAI does when the model cannot call tools natively
Read the text tool-calling format CrewAI uses
Recognise the ways tool use fails with a small model
Design better tool messages - and know their limits
Choose between agent tools and searching in code

The idea, in plain English

A tool lets an agent do something outside the model: search notes, call an API, calculate. In CrewAI you write a Python function, mark it with @tool, and give it to an agent with tools=[...].

How the agent calls the tool depends on the model. Models with native tool calling get the tools in a special field. llama3 has none - so what does CrewAI do? We recorded every request to find out.

Then we asked four questions, including ones the notes cannot answer, because that is where tool use usually breaks. CrewAI 1.15.27, llama3 on Ollama.

Worked example: A search_notes tool over a few course notes, used by a researcher agent - the full request sequence recorded, then four questions, then a search-in-code version.

request flowA tool call with a model that cannot call toolsstep 1 / 3

CrewAI

agent with search_notes

llama3

no native tools

✗

search_notes

your Python function

React Flow

1 - Native tool calling: refused

CrewAI first sends the tool in the "tools" field. Ollama answers 400: llama3 does not support tools.

request 1

400

The researcher answers "What do the notes say about checkpoints and threads?" Real requests.

Words you will see in this lesson

Words about tools.

Small dictionary

ToolA function the agent may call: search, calculate, call an API.

@tool("name")CrewAI’s decorator that turns a function into a tool. The docstring becomes its description.

Native tool callingThe model receives tools in a special field and answers with a structured call. llama3 cannot.

Text tool callingTools described in the prompt; the model writes "Action:" and "Action Input:" as text (ReAct, Module 1).

ObservationThe tool’s result, given back to the model.

FabricationThe model inventing facts - here, when the tool found nothing.

An everyday example: a librarian

You ask a librarian a question. A good one searches the catalogue first. (The agent calls a tool.)
If the catalogue has the book, they read you the answer. (The tool result is used.)
If the catalogue has nothing, a good librarian says "we do not have that". A bad one makes something up. (Fabrication.)
Sometimes it is faster to look up the shelf yourself and hand the book to someone who explains it. (Search in code, then ask the agent.)

Example 1 - a search tool

A tool is a normal function with three things that matter:

@tool("search_notes") - the name the agent will use.
The docstring - the description the agent reads. Say what to send ("one keyword, for example 'checkpoint'") and what comes back.
Type hints (query: str) - they become the tool’s argument schema.
tools=[search_notes] on the agent. The calls list records every real call, so we can check.

tools1.py

import sys, time
from crewai import LLM, Agent, Crew, Task
from crewai.tools import tool

base = sys.argv[1] if len(sys.argv) > 1 else "http://localhost:11434"

NOTES = {
    "checkpoint": "A checkpointer saves the graph state after every step.",
    "thread": "Each run has a thread_id; the saved state is stored under it.",
    "resume": "With the same thread_id, a run can continue later, even after a restart.",
    "interrupt": "interrupt() pauses a node until a human answers; Command(resume=...) continues it.",
}
calls = []


@tool("search_notes")
def search_notes(query: str) -> str:
    """Search the course notes. Give one keyword, for example 'checkpoint'. Returns matching notes."""
    calls.append(query)
    found = [text for key, text in NOTES.items() if key in query.lower()]
    return "\n".join(found) if found else "No notes found. Try another keyword."


researcher = Agent(
    role="Researcher",
    goal="Find facts in the course notes",
    backstory="You never answer from memory. You always search the notes first.",
    tools=[search_notes],
    llm=LLM(model="ollama/llama3", base_url=base, temperature=0),
)
task = Task(description="What do the notes say about checkpoints and threads in LangGraph?",
            expected_output="The facts from the notes, as short bullet points.", agent=researcher)
start = time.perf_counter()
result = Crew(agents=[researcher], tasks=[task]).kickoff()
print("--- tool calls:", calls)
print("--- answer:\n" + result.raw)
print(f"--- {time.perf_counter() - start:.1f} s")

Output

ERROR:root:OpenAI API call failed: Error code: 400 - {'error': {'message': 'registry.ollama.ai/library/llama3:latest does not support tools', 'type': 'invalid_request_error', 'param': None, 'code': None}}
--- tool calls: ['checkpoint threads LangGraph']
--- answer:
```
A checkpointer saves the graph state after every step.
Each run has a thread_id; the saved state is stored under it.
```
--- 26.4 s

What happened inside - the recorded requests

With a spy between CrewAI and Ollama we saw three requests:

Request 1 (400): CrewAI sent the tool in the native "tools" field. llama3 does not support tools. The ERROR line in the output is this.
Request 2: CrewAI tried again WITHOUT the tools field and added a message: "Native tool calling is unavailable for this model/provider. Continue using CrewAI text tool calling instead." - plus the tool description and the Thought / Action / Action Input / Observation format.
llama3 answered with Action: search_notes and Action Input {"query": "checkpoint threads LangGraph"} - and then wrote its own invented Observation.
CrewAI threw the invented Observation away, ran the real function, and put the real result in its place. Request 3 got the real notes and gave the final answer.
This is exactly the ReAct loop you built by hand in Module 1 - including the rule that observations come from your code, never from the model.

Request 2 - the text tool-calling message CrewAI added (shortened)

Native tool calling is unavailable for this model/provider. Continue using CrewAI text tool calling instead.

You ONLY have access to the following tools, and should NEVER make up tools that are not listed here:

Tool Name: search_notes
Tool Arguments: { "properties": { "query": { "title": "Query", "type": "string" } }, "required": ["query"], ... }
Tool Description: Search the course notes. Give one keyword, for example 'checkpoint'. Returns matching notes.

IMPORTANT: Use the following format in your response:

Thought: you should always think about what to do
Action: the action to take, only one name of [search_notes], just the name, exactly as it's written.
Action Input: the input to the action, just a simple JSON object, enclosed in curly braces, using " to wrap keys and values.
Observation: the result of the action

Request 3 - the real Observation CrewAI inserted

Thought: I should search the course notes for information about checkpoints and threads in LangGraph
Action: search_notes
Action Input: {"query": "checkpoint threads LangGraph"}
Observation: A checkpointer saves the graph state after every step.
Each run has a thread_id; the saved state is stored under it.

Tip: We also tried to skip the failing first request by telling CrewAI the model has no function calling. CrewAI then used a different, longer prompt; llama3 copied the tool schema into its input and the run stopped making progress. Keep the default.

Example 2 - harder questions

Easy questions worked. We asked three harder ones - one needs the right keyword, one has no notes at all:

"How does a human approve a step?" - llama3 searched "LangGraph approval". No note contains "approval", so the tool said "No notes found" - and llama3 invented an answer about clicking an "Approve" button.
"How can a run continue after a restart?" - it searched "checkpoint", got one note, and added sentences that are not in the notes.
"What is a reducer?" - nothing in the notes. llama3 invented a definition anyway.
The backstory said "You never answer from memory". It did not help when the search came back empty.

Output - three questions (answers shortened)

=== How does a human approve a step in LangGraph?
  tool calls: ['LangGraph approval']  (15.4 s)
  answer: • The user can approve a step in LangGraph by clicking the "Approve" button.
          • The user can also approve a step by clicking the "Checkpoint" button. ...
=== How can a run continue after the program restarts?
  tool calls: ['checkpoint']  (25.7 s)
  answer: • The run can continue after the program restarts because a checkpointer saves the graph state after every step.
          • The checkpointing mechanism ensures that the program can resume from the last saved state. ...
=== What is a reducer in LangGraph?
  tool calls: ['reducer LangGraph']  (14.4 s)
  answer: [{"title": "Reducer", "content": "A reducer in LangGraph is a function that takes two arguments: the current state and the incoming event. It returns the new state."}]

A better "not found" message - and its limits

We changed the tool’s answer for "nothing found": list the topics that exist, and say exactly what to answer otherwise:

The reply now says: "The notes only cover: checkpoint, thread, resume, interrupt. Search one of these, or answer exactly: The notes do not cover this."
Result: different, not better. For the approval question the "final answer" was a raw "Thought: ... Action: search_notes" block - llama3 wanted to search again, but its text was taken as the answer.
The reducer question crashed: "ValueError: No valid task outputs available to create crew output."
Good tool messages still matter with strong models. With a small model, text tool calling stays fragile.

The improved tool

def search_notes(query: str) -> str:
    """Search the course notes. Give one keyword, for example 'checkpoint'. Returns matching notes."""
    calls.append(query)
    found = [text for key, text in NOTES.items() if key in query.lower()]
    if found:
        return "\n".join(found)
    return (f"No notes match '{query}'. The notes only cover: {', '.join(NOTES)}. "      # tell the model what exists
            "Search one of these, or answer exactly: The notes do not cover this.")   # and what to do if nothing fits

Example 3 - search in code first

For a small model, take the search out of the agent’s hands:

search() is plain Python and ALWAYS runs - with a small list of words per topic.
The results go into the task through inputs, as in Lesson 6.5.
The task says what to answer when nothing was found.
Results: about 1 second per question instead of 15-26, and no invented answers.
But it went too far once: for the approval question the interrupt() note WAS found, and llama3 still said "The notes do not cover this." A strict prompt can make the model refuse too often.

search_first.py

import time
from crewai import LLM, Agent, Crew, Task

NOTES = {
    "checkpoint": "A checkpointer saves the graph state after every step.",
    "thread": "Each run has a thread_id; the saved state is stored under it.",
    "resume": "With the same thread_id, a run can continue later, even after a restart.",
    "interrupt": "interrupt() pauses a node until a human answers; Command(resume=...) continues it.",
}
WORDS = {"checkpoint": ["checkpoint", "save"], "thread": ["thread"], "resume": ["continue", "restart", "resume"],
         "interrupt": ["human", "approve", "pause", "interrupt"]}


def search(question: str) -> str:                      # plain Python: the search ALWAYS runs
    q = question.lower()
    found = [NOTES[key] for key, words in WORDS.items() if any(w in q for w in words)]
    return "\n".join(found) if found else "(nothing found)"


writer = Agent(
    role="Course assistant",
    goal="Answer questions using only the course notes you are given",
    backstory="You never add facts that are not in the notes.",
    llm=LLM(model="ollama/llama3", base_url="http://localhost:11434", temperature=0),
)
task = Task(
    description="Question: {question}\nNotes:\n{notes}\n"
                "Answer only from the notes. If the notes are '(nothing found)', answer exactly: The notes do not cover this.",
    expected_output="One or two short sentences.",
    agent=writer,
)
for question in ["How does a human approve a step in LangGraph?",
                 "How can a run continue after the program restarts?",
                 "What is a reducer in LangGraph?"]:
    notes = search(question)
    start = time.perf_counter()
    answer = Crew(agents=[writer], tasks=[task]).kickoff(inputs={"question": question, "notes": notes}).raw
    print(f"=== {question}\n  notes: {notes!r}\n  answer: {answer.strip()!r}  ({time.perf_counter() - start:.1f} s)")

Output

=== How does a human approve a step in LangGraph?
  notes: 'interrupt() pauses a node until a human answers; Command(resume=...) continues it.'
  answer: 'The notes do not cover this.'  (1.5 s)
=== How can a run continue after the program restarts?
  notes: 'With the same thread_id, a run can continue later, even after a restart.'
  answer: 'With the same thread_id, a run can continue later, even after a restart.'  (1.4 s)
=== What is a reducer in LangGraph?
  notes: '(nothing found)'
  answer: 'The notes do not cover this.'  (0.9 s)

Agent tools or search in code?

Use agent tools when the agent must choose between many tools, or search several times based on what it finds.
Search in code when the same lookup is always needed - and especially with a small local model.
Either way: check answers against the sources (a guardrail - Lesson 6.4).

Which approach?

Agent toolsThe agent decides when and what to search. Flexible - needs a model that calls tools well.

Search in codeYour code always searches; the agent only explains. Fast and predictable - fits small models.

With llama3Tools: 15-26 s, invented answers, one crash. Code first: about 1 s, no inventions, one too-strict refusal.

The recipe

1. @tool("clear_name") on a function with type hints and a docstring that says what to send and what comes back.
2. Agent(tools=[...]) - only the tools that agent needs.
3. Make "nothing found" a clear, helpful message.
4. Record real calls (a list, verbose=True or a trace) and compare with the answer.
5. With a small model, prefer searching in code and passing results through inputs.

Tools at a glance

Make a tool

Docstring = description.

@tool("search_notes")
def search_notes(query: str) -> str: ...

Give it to an agent

Only this agent can use it.

Agent(..., tools=[search_notes])

Text tool calling

Automatic fallback.

Thought / Action / Action Input / Observation

Search in code

For small models.

crew.kickoff(inputs={"question": q, "notes": search(q)})

Try it yourself

The code does not change. Swap the content string and the program does something else entirely.

Two tools

“Add a calculator tool to the researcher and ask a question that needs both tools.”

Better keywords

“Add "approve" and "human" as keys that find the interrupt note. Does the approval question work with agent tools now?”

Fix the refusal

“In search_first.py, change the task text so llama3 uses the interrupt note for the approval question.”

Guard it

“Add a guardrail that rejects answers containing sentences that are not in the notes.”

What usually goes wrong

Trusting "never answer from memory"

The backstory did not stop llama3 inventing answers when the tool found nothing.

A vague "not found" message

"No notes found" gave no next step. Say what exists and what to answer.

Patching CrewAI internals

Turning off native calling up front changed the prompt and made the run stall.

Not checking the calls

Record which tool calls really happened and compare with the answer.

Key points

@tool + a clear docstring + type hints make a tool; Agent(tools=[...]) gives it to an agent.
With llama3, native tool calling fails (400) and CrewAI falls back to text tool calling - the ReAct format from Module 1.
CrewAI replaced llama3’s invented Observation with the real tool result.
When the search found nothing, llama3 invented answers; a better tool message did not reliably fix it.
Searching in code first was about 15 times faster and did not invent - but could refuse too strictly.

Quick check before you move on

What becomes the tool’s description?

The function’s docstring.

What did Ollama answer to CrewAI’s first, native tool request?

400: llama3 does not support tools.

What did CrewAI do next?

It switched to text tool calling: the tool described in the prompt and the Thought / Action / Observation format.

What did llama3 do when the search found nothing?

It invented an answer.

Quiz

1.
llama3 wrote its own Observation. Did that reach the final answer?
2.
Why did the approval question fail with agent tools?
3.
What are the benefits and the cost of searching in code first?
4.
When should an agent own its tools?

Interview questions

How does CrewAI handle tools for models without function calling?

It attempts native function calling, and on failure falls back to a ReAct-style text protocol: tools are described in the prompt, the model emits Action/Action Input, and CrewAI executes the tool and injects the real Observation.

How do you reduce hallucination when tools return nothing?

Return explicit not-found messages with next steps, constrain the answer format, retrieve deterministically in code when possible, and validate answers against retrieved sources with a guardrail.

Comments

Loading comments...