Defining and Using Tools

While the LLM is a powerful reasoning engine, it has significant limitations. By itself, an LLM is a closed system; it cannot access real-time information from the web, perform precise mathematical calculations, execute code, or interact with external APIs. To overcome these limitations and build truly capable agents, agents are equipped with tools.

A tool is simply a function that an agent can decide to call to perform a specific action. This could be anything from a simple calculator to a complex integration with a company's internal database. By providing an agent with a set of tools, you give it the ability to interact with the external environment, gather information, and perform actions to achieve its goal. The LLM's role shifts from trying to know the answer to knowing how to find the answer.

The Anatomy of a Tool

In the Kerb toolkit, a tool is more than just a Python function. It's a structured object that provides the LLM with all the necessary information to understand and use it effectively. Each tool consists of several important components:

• Name: A unique, descriptive name for the tool (e.g., calculator, web_search). The LLM uses this name to specify which tool it wants to use.
• Description: A clear, natural language description of what the tool does, when it should be used, and what its inputs and outputs are. This is arguably the most important part, as the LLM relies heavily on the description to make its reasoning decisions.
• Function: The actual Python function that gets executed when the agent decides to use the tool.
• Parameters: A schema that defines the arguments the function accepts, including their names, types, and descriptions. This allows the LLM to structure its Action Input correctly.

Creating Your First Tool

There are two primary ways to define a tool: using the Tool class directly or with the create_tool helper function. Let's start with the Tool class to build a simple calculator.

First, define the Python function that will perform the work:

def calculate(expression: str) -> str:
    """A simple calculator tool."""
    try:
        # Using eval() for simplicity, but use safer methods in production
        result = eval(expression)
        return f"Result: {result}"
    except Exception as e:
        return f"Error: {str(e)}"

Next, wrap this function in a Tool object. This provides the necessary metadata for the agent's LLM to understand how to use it.

from kerb.agent import Tool

calc_tool = Tool(
    name="calculator",
    description="Performs mathematical calculations on a given expression. Use this for any math-related questions.",
    func=calculate,
    parameters={
        "expression": {
            "type": "string",
            "description": "The mathematical expression to evaluate (e.g., '15 * 7')."
        }
    }
)

Notice how the description is written for the LLM. It clearly states the tool's purpose ("Performs mathematical calculations") and provides guidance on when to use it ("Use this for any math-related questions"). The parameters dictionary defines the input expression that the calculate function expects.

Using the create_tool Helper

For a more concise way to define tools, you can use the create_tool function. It achieves the same result with a slightly simpler syntax. Let's define another tool, this time for a mock web search.

from kerb.agent import create_tool

def search(query: str) -> str:
    """A mock search tool."""
    # In a real application, this would call a search API
    if "python" in query.lower():
        return "Python is a high-level programming language."
    return f"No results found for: {query}"

search_tool = create_tool(
    name="search",
    description="Searches for information on a given topic. Use this to find up-to-date information.",
    func=search,
    parameters={
        "query": {
            "type": "string",
            "description": "The topic or question to search for."
        }
    }
)

Both Tool(...) and create_tool(...) produce the same type of object that can be passed to an agent. Choose the one that best fits your coding style.

Equipping an Agent with Tools

Once you have defined your tools, you need to make the agent aware of them. You do this by passing a list of Tool objects to the agent's constructor.

from kerb.agent.patterns import ReActAgent

# A mock LLM function for demonstration
def mock_llm_react(prompt: str) -> str:
    if "calculate 15 * 7" in prompt:
        return """Thought: I need to calculate 15 multiplied by 7. I should use the calculator tool.
Action: calculator
Action Input: 15 * 7"""
    elif "105" in prompt:
        return """Thought: I have the result of the calculation. I can now provide the final answer.
Final Answer: The result of 15 * 7 is 105."""
    else:
        return "Thought: I will think about this. \nFinal Answer: I am not sure what to do."

# Create an agent and provide it with the tools we defined
agent = ReActAgent(
    name="MathAgent",
    llm_func=mock_llm_react,
    tools=[calc_tool, search_tool],
    max_iterations=5
)

print(f"Agent created with tools: {[t.name for t in agent.tools]}")

When the ReActAgent is initialized, it incorporates the names and descriptions of the provided tools into its internal system prompt. This allows the LLM, on each reasoning step, to see the available tools and decide if one of them can help achieve the user's goal.

The Tool-Using Loop in Action

With the agent equipped with tools, let's trace the full execution loop for a goal like "What is 15 * 7?".

goal = "What is 15 * 7?"
result = agent.run(goal)

# Display the ReAct loop
for i, step in enumerate(result.steps, 1):
    print(f"\n[Step {i}]")
    if step.thought:
        print(f"Thought: {step.thought}")
    if step.action:
        # The agent framework parses 'calculator' as the action
        print(f"Action: {step.action}({step.action_input})")
    if step.observation:
        # The observation is the output of the calculate() function
        print(f"Observation: {step.observation}")

print(f"\nFinal Answer: {result.output}")

This interaction unfolds as follows:

1. Goal: The agent receives the goal: "What is 15 * 7?".
2. Thought: The llm_func receives a prompt containing the goal and the definitions of the calculator and search tools. The LLM reasons that the calculator tool is appropriate and formulates a plan. It outputs its thought: "I need to calculate 15 multiplied by 7. I should use the calculator tool."
3. Action: The LLM then outputs a structured action command: Action: calculator with Action Input: 15 * 7.
4. Execution: The agent framework parses this output. It identifies calculator as the tool to run and "15 * 7" as the input. It then calls our Python function: calculate("15 * 7").
5. Observation: The calculate function executes eval("15 * 7"), which returns 105. The agent captures this return value as the observation for this step.
6. Next Loop: The observation ("Result: 105") is fed back into the LLM in the next prompt. The LLM sees the result and formulates its next thought: "I have the result of the calculation."
7. Final Answer: With the necessary information gathered, the LLM provides the final answer: "The result of 15 * 7 is 105." The agent sees the "Final Answer" tag and terminates the loop, returning the result.

This loop of thought, action, and observation is the fundamental mechanism that allows agents to extend their capabilities far past the inherent knowledge of the LLM itself.

Best Practices for Tool Design

How you design your tools has a significant impact on your agent's performance.

• Write Descriptive Descriptions: The tool's description is your primary way of communicating with the LLM. Write clear, unambiguous descriptions that explain what the tool does, what it's good for, and any important constraints. For example, for a search tool, a good description might be "Searches for real-time information on public websites. Best for recent events, news, and general knowledge questions."
• Prefer Simple, Atomic Tools: It is better to have several simple, single-purpose tools than one complex tool that does many things. An agent can more easily reason about combining search_web and read_file than using a single research_and_summarize_topic tool.
• Define Clear Parameters: Use descriptive names for your parameters and provide clear descriptions for each. If a parameter has specific constraints (e.g., an enum of possible values), include that in the description.
• Handle Errors Gracefully: Your underlying Python function should anticipate and handle potential errors. If a tool fails (e.g., an API call times out or receives invalid input), it should return an informative error message. This message becomes the agent's observation, giving it a chance to recover, retry, or try a different approach.