Building a Multi-Tool Agent

Agents With Multiple Tools

So far we have looked at simple agents with one or two tools. Now let's build an agent with many tools and see how the agent decides which one to use.

Define Multiple Tools

Our research agent will have these tools:

• web_search: Search the web
• fetch_webpage: Get full text of a page
• summarize_text: Create a summary
• get_current_date: Get today's date (for context)

tools = {
  "web_search": web_search,
  "fetch_webpage": fetch_webpage,
  "summarize_text": summarize_text,
  "get_current_date": get_current_date,
}

tool_descriptions = """
You have these tools:

1. web_search(query, num_results=5)
   Search the web for information about a topic.
   Returns a list of search results with titles and snippets.
   Use this to find relevant sources.

2. fetch_webpage(url)
   Fetch the full text content of a webpage.
   Returns the page text.
   Use this after searching, to read the full article.

3. summarize_text(text, max_length=200)
   Create a brief summary of text.
   Returns a summary.
   Use this to condense information for the user.

4. get_current_date()
   Get today's date.
   Returns a date string like "2026-03-29".
   Use this to understand current context.
"""

The Agent Loop

def run_research_agent(user_question):
  conversation = []
  max_iterations = 10
  
  system_message = f"""You are a research assistant.
  
{tool_descriptions}

User question: {user_question}

Step by step:
1. Determine what you need to find.
2. Use web_search to find relevant sources.
3. Use fetch_webpage to read the best sources.
4. Use summarize_text if you have too much information.
5. Return your final answer to the user.

Think carefully about which tool to use at each step.
"""
  
  for iteration in range(max_iterations):
    # Ask the model what to do
    response = call_model(system_message, conversation)
    print(f"\n[Step {iteration+1}] Agent: {response[:200]}...")
    
    # Check if done
    if "<tool_use>" not in response:
      print(f"\nFinal answer:\n{response}")
      return response
    
    # Parse and call the tool
    tool_call = parse_tool_call(response)
    tool_name = tool_call["name"]
    tool_args = tool_call["args"]
    
    print(f"Calling: {tool_name}({tool_args})")
    
    # Call the tool
    if tool_name not in tools:
      result = {"error": f"Unknown tool: {tool_name}"}
    else:
      result = tools[tool_name](**tool_args)
    
    # Add to conversation
    conversation.append({"role": "assistant", "content": response})
    conversation.append({
      "role": "user",
      "content": f"Tool {tool_name} returned: {json.dumps(result)}"
    })
  
  return "Max iterations reached"

How the Agent Chooses Tools

The agent reads the tool descriptions and the user question, then decides which tool to use.

User asks: "What are the latest renewable energy breakthroughs?"

Agent reasons:

• User wants recent information ("latest")
• I need to search for this
• Tool: web_search("renewable energy breakthroughs 2026")

Search returns: [list of results]

Agent reasons:

• I found some results
• Let me read the top one
• Tool: fetch_webpage("https://...")

Fetch returns: Full article text

Agent reasons:

• This article is long and has a lot of detail
• User wants just the breakthroughs
• I should summarize
• Tool: summarize_text("long text")

Summarize returns: Brief summary

Agent reasons:

• Now I have a good answer
• No more tools needed
• Return the summary to the user

Tool Selection Problems

Sometimes the agent picks the wrong tool. Here are common mistakes:

Mistake 1: Agent searches when it should fetch

• User: "Read this article: https://..."
• Agent: Calls web_search instead of fetch_webpage
• Fix: Rewrite the tool description to make it clear
  • Bad: "fetch_webpage: Get a webpage"
  • Good: "fetch_webpage: Use this when you have a URL and want to read the full content. Do NOT use this for searching."

Mistake 2: Agent calls wrong tool for the task

• User: "Summarize the article"
• Agent: Calls web_search
• Fix: Better tool description and system message
  • In system message: "If the user asks to summarize or condense, use summarize_text"

Mistake 3: Agent calls tool with wrong parameters

• Tool: summarize_text(text, max_length)
• Agent calls: summarize_text("text to summarize", "long")
• Fix: Better parameter description
  • Bad: "max_length: The maximum length"
  • Good: "max_length: Maximum characters in summary. Must be an integer like 100 or 500. Default: 200."

Multi-Tool Tips

1. Keep descriptions clear and unique Each tool's description should be distinct. If two tools sound similar, the agent will confuse them.

2. Use examples in system message Show the agent examples of how to use multiple tools together.

Example:
- User: "Find the latest AI news and give me a summary"
- Step 1: web_search("latest AI news 2026")
- Step 2: fetch_webpage("https://...")
- Step 3: summarize_text("full article text")

3. Limit to 5-7 tools Too many tools confuses the agent. It doesn't know which to pick. Keep it focused.

4. Group related tools If you have a search tool and fetch tool, they work together. Explain this relationship.

Tool Ordering Matters

The order you list tools affects how the agent chooses them. List the most important or most likely tools first.

# Good order: Start with search, then fetch, then summarize
tool_descriptions = """
1. web_search: Find sources
2. fetch_webpage: Read full articles
3. summarize_text: Condense information
"""

# Bad order: Summarize is first, confuses the agent
tool_descriptions = """
1. summarize_text: Summarize
2. fetch_webpage: Fetch
3. web_search: Search
"""

Debugging Multi-Tool Agents

When your agent picks the wrong tool:

1. Check the tool descriptions. Are they clear? Do they overlap?
2. Add examples to the system message.
3. Reorder the tools (put the most important one first).
4. Test with a simple query first.
5. Look at the logs. What made the agent pick that tool?

Most tool selection issues come from unclear descriptions or poor examples.