Custom Tools & Multi-Tool Agents

What you will be able to do

• ✓Wrap a retriever as a tool, so RAG becomes one capability among several
• ✓Build an agent with a calculator, a search tool and a document tool
• ✓Follow how one question can use one tool, several, or none
• ✓Write tool names and descriptions a model can route between
• ✓Handle unknown tools, bad arguments and tool exceptions
• ✓Keep control of what tools may do, and who they act for

The idea, in plain English

Lesson 2.12’s RAG chain retrieves for every question - even "What is 125 * 48?". An agent turns it around: retrieval becomes a tool, search_documents, next to calculate and search, and the model decides per question which to call. Calculation goes to the calculator, policy questions to the documents, current events to search - and a question that needs two gets two.

The model chooses from what it can see: each tool’s name, description and argument schema (Lesson 2.6). Your application runs the chosen tool and returns the result (Lesson 2.7). Nothing about the loop is new; what is new is that the choice between capabilities now matters, and so do the descriptions that drive it.

Our llama3 cannot call tools, so the agent runs below use a scripted model for the choices, as in Lesson 2.7 - with the real tools, the real create_agent loop and real retrieval. To test the choosing itself, we asked llama3 to pick a tool from the descriptions with structured output: 8 of 8 right with good descriptions, 6 of 8 with vague ones.

Worked example: Multi-tool assistant.

RAG chain vs RAG tool

A RAG chain is a fixed path: every question is retrieved for, then answered. A RAG tool is optional: the agent retrieves only when the question needs the documents. "What is 20 * 12?" goes straight to the calculator; "how many leave days?" goes to the documents.

The cost is predictability. A chain always does the same thing and is easy to test. An agent can choose wrongly, skip a tool it needed, or call one it did not - which is why the rest of this lesson is about making the choice easy and the consequences safe.

Three tools

calculate is Lesson 1.6’s safe evaluator as a @tool - numbers and + - * / only. Not eval(): with eval the model’s argument is Python on your machine. search is a placeholder that returns "Search results for: ..."; in a real system it calls a search API. search_documents wraps the retriever: call retriever.invoke(question), join the chunks, return the text.

LangChain has a helper for the last one: create_retriever_tool(retriever, "search_documents", description) from langchain_core.tools returns the same kind of tool, with an argument named query. Writing it yourself lets you choose the argument name and how chunks are formatted - for example with page numbers, as in Lesson 2.12.

The model routes by description

The model never sees your code. It sees name, description and parameters - the JSON schema from Lesson 2.6 - for every tool, on every call. "Search." tells it nothing about which search; "Search the company’s internal documents. Use this for questions about company policies, procedures or internal documentation." tells it when.

We tested this with llama3. It cannot call tools, but it can choose one with structured output, so we gave it the tool names and descriptions and eight questions. With our descriptions it chose correctly 8 of 8 times. With every description cut to "Calculate." or "Search.", 6 of 8: "How many days a week can I work from home?" and "Can I claim my taxi fare from last month’s client visit?" both went to "none" - policy questions that never say "documents", so nothing told the model the documents were the place to look.

One question, one tool - or several

Each question took its own route through the same agent. "What is 125 * 48?" - calculate, 6000. "According to our documents, how many annual leave days...?" - search_documents, which returned the leave chunk and, because k=2, the travel-expenses chunk too. "Search for information about Python 3.13." - search.

A question that needs two capabilities can get them in sequence - search_documents, then calculate, then the answer - or in a single reply with two tool calls, which the tools node runs in the same step. Either way the order is the model’s decision. A fixed chain would have to retrieve for "What is 20 * 12?" too.

When tools go wrong

Three failures, three behaviours. A tool that does not exist - the model asked for delete_file - is answered for you: "Error: delete_file is not a valid tool, try one of [calculate, search, search_documents]." Wrong arguments are too: calculate called with {"expr": ...} came back as "Error invoking tool ‘calculate’ ... expression: Field required. Please fix the error and try again." The model sees the error and can correct itself.

An exception inside a tool is different: a search tool that raised TimeoutError ended the whole run (as in Lesson 2.1). Either catch it inside the tool and return the error as text (Lesson 1.10), or add ToolErrorMiddleware(on_error) - your function decides which exceptions become a message for the model ("search timed out - try again later or answer without it.") and which still stop the run. It is opt-in on purpose: unhandled internal errors are never shown to the model unless you choose.

The model decides; your application controls

The tool list is the agent’s whole reach. It cannot delete files without a delete tool, and it cannot run code through a calculator that only does arithmetic - the safe calculate answered __import__(‘os’).getcwd() with "Calculation error: only numbers and + - * / are allowed."

Inside each tool, validate as if the arguments came from a stranger - they did. Allowlist paths and operations, never pass model text to SQL or a shell, add timeouts, log every call. And keep identity out of the model’s hands: on a multi-tenant platform, search_documents should filter by the logged-in user’s tenant_id from your session, not by a tenant_id argument the model fills in.

Watch out: Never make permissions a tool argument. A tenant_id, user_id or role that the model supplies is a value the model - or a cleverly worded document - can change.

How many tools?

Every tool’s schema is sent on every model call, and every extra tool is another option to choose wrongly between. Start with the few the task needs. Give each one job and a name that says it - search_documents, not do_search - and descriptions that say when to use it, not only what it does.

Hard-coded routing (if "document" in question: ...) works for two tools and breaks for twenty, and our vague-description test shows why: real questions rarely contain the keyword. An agent routes by meaning - as well as its descriptions allow.

Multi-tool agent vs multi-agent system

This lesson is one agent with several tools. A multi-agent system has several agents - a researcher, a writer, a reviewer - each with its own prompt and tools, coordinated by code or by a supervisor agent. Lesson 1.11 had two agents talking; LangGraph (Module 3) is where those systems are built properly.

Step-by-step code

Tip: Write down ten real questions and the tool each should use. Run them after every change to a tool’s name or description - it is the cheapest test an agent has.

Multi-tool agents at a glance

@tool def search_documents(question: str)

create_retriever_tool(retriever, name, description)

create_agent(llm, tools=[calculate, search, search_documents])

Error: ... is not a valid tool

Please fix the error and try again.

ToolErrorMiddleware(on_error)

Try it yourself

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

What usually goes wrong

✗ return str(eval(expression))

✓ return str(evaluate(ast.parse(expression, mode="eval").body))

✗ """Search."""

✓ """Search the company's internal documents. Use this for questions about company policies..."""

✗ def search_documents(question: str, tenant_id: str)

✓ filter={"tenant_id": current_user.tenant_id}  # inside the tool

Quick check before you move on

1. 1.

   With vague descriptions, where did llama3 send "How many days a week can I work from home?"

   Show answer
2. 2.

   The model calls calculate with {"expr": "2 * 3"}. What happens?

   Show answer
3. 3.

   A tool raises TimeoutError. What happens by default, and how do you change it?

   Show answer
4. 4.

   Why should tenant_id not be an argument of search_documents?

   Show answer

Interview questions