Creating a Basic Tool: A Calculator Example

To truly make our LLM agents versatile, we need to give them ways to interact with the world beyond just processing text. Imagine asking an agent for the current weather, the result of a math problem, or to look up a fact online. The LLM itself, while excellent at understanding language and generating responses, isn't inherently designed to perform these actions directly or accurately. This is where "tools" come into play.

A tool, in the context of an LLM agent, is essentially a specific capability or function that the agent can use to perform tasks or retrieve information that it cannot do on its own. Think of it like giving a human assistant access to a calculator, a search engine, or a calendar. The assistant (the LLM agent) is smart, but these tools give it superpowers.

Let's make this more concrete by designing and implementing a very simple tool: a calculator. LLMs can often perform simple arithmetic embedded in text, but for reliable and precise calculations, especially as part of a larger task, a dedicated calculator tool is far better. They might "hallucinate" or make errors with math, as their strength lies in pattern recognition in language, not formal computation.

Designing Our Calculator Tool

Before we write any code, let's think about what our calculator tool needs to do and how the agent might use it. A good tool definition is clear and unambiguous.

1. Purpose: The tool should perform basic arithmetic operations: addition, subtraction, multiplication, and division.
2. Inputs: To perform a calculation, the tool will need:
   • A first number (let's call it operand1).
   • A second number (operand2).
   • The operation to perform (e.g., 'add', 'subtract', 'multiply', 'divide'). We'll represent this as a string.
3. Output: The tool should return:
   • The numerical result of the calculation.
   • Or, if something goes wrong (like trying to divide by zero or providing an unknown operation), an error message.

This design helps us define a clear "contract" for our tool. The agent will learn (or be told) that to use the calculator, it needs to provide these specific inputs in a certain format, and it can expect a numerical result or an error message in return.

Implementing a Basic Calculator in Python

Now, let's create a simple Python function that acts as our calculator tool. For a beginner-level course, we'll keep this straightforward.

def simple_calculator(operand1, operand2, operation):
    """
    Performs basic arithmetic operations.
    Supported operations: 'add', 'subtract', 'multiply', 'divide'.
    """
    allowed_operations = ['add', 'subtract', 'multiply', 'divide']

    if not isinstance(operand1, (int, float)) or not isinstance(operand2, (int, float)):
        return "Error: Both operands must be numbers."

    if operation not in allowed_operations:
        return f"Error: Unknown operation '{operation}'. Supported operations are: {', '.join(allowed_operations)}."

    if operation == 'add':
        return operand1 + operand2
    elif operation == 'subtract':
        return operand1 - operand2
    elif operation == 'multiply':
        return operand1 * operand2
    elif operation == 'divide':
        if operand2 == 0:
            return "Error: Cannot divide by zero."
        return operand1 / operand2

Let's break down this Python code:

• We define a function simple_calculator that takes three arguments: operand1, operand2, and operation.
• We first check if operand1 and operand2 are actually numbers (integers or floating-point numbers). If not, we return an informative error message. This kind of input validation is important for making tools reliable.
• We then check if the operation string is one of the ones we support ('add', 'subtract', 'multiply', 'divide'). If it's an unrecognized operation, we return another error message.
• Next, we use if/elif statements to perform the correct calculation based on the operation string.
• For division, we include a specific check to prevent a "division by zero" error, which would crash many programs. Instead, we return a helpful error message.
• If all inputs are valid and the operation is supported, the function returns the calculated result.

You can test this function directly in Python:

result1 = simple_calculator(10, 5, 'add')
print(f"10 + 5 = {result1}") # Output: 10 + 5 = 15

result2 = simple_calculator(10, 0, 'divide')
print(f"10 / 0 = {result2}") # Output: 10 / 0 = Error: Cannot divide by zero.

result3 = simple_calculator(10, 'hello', 'multiply')
print(f"10 * 'hello' = {result3}") # Output: 10 * 'hello' = Error: Both operands must be numbers.

This simple function is now a "tool" that our agent could potentially use.

How the Agent "Sees" the Tool

It's important to understand that the LLM agent doesn't directly read or execute the Python code of simple_calculator. Instead, the agent is typically provided with a description of the tool. This description tells the agent:

• Tool Name: A unique identifier, e.g., CalculatorTool.
• Tool Description: A human-readable explanation of what the tool does, e.g., "Performs basic arithmetic operations like addition, subtraction, multiplication, and division on two numbers."
• Input Parameters:
  • operand1: The first number for the calculation. (Type: number)
  • operand2: The second number for the calculation. (Type: number)
  • operation: The arithmetic operation to perform. (Type: string, e.g., 'add', 'subtract', 'multiply', 'divide')
• Output:
  • The numerical result of the calculation. (Type: number)
  • Or, an error message if the calculation cannot be performed. (Type: string)

This structured description is what the agent's underlying LLM uses to understand how to use the tool and what to expect from it. When the agent decides it needs to calculate something, it will try to format its request to match these input parameters. We'll explore how agents decide to use tools and how we format these descriptions more formally in later sections.

The following diagram illustrates the components involved in defining a tool for an agent:

The diagram shows that a tool is defined by its metadata (name, purpose), input requirements, output specifications, and the actual underlying implementation (like our Python function). The agent primarily interacts with the descriptive parts to understand how to use the tool.

Why a Calculator is a Good Starting Point

The calculator example is useful because:

1. Clear Need: It addresses a common task where LLMs alone can be unreliable. LLMs are good at understanding mathematical questions but not always at performing the calculations accurately.
2. Simple Interface: The inputs (two numbers, one operation) and output (one number or an error) are easy to define and understand.
3. Deterministic Output: For given inputs, a calculator tool provides a predictable, correct answer (or a predictable error). This reliability is what agents need from tools.
4. Illustrates External Capability: It perfectly demonstrates how an agent can offload a specific type of task to a more specialized component.

By creating this simple_calculator function, we've taken the first step in equipping our agent with an external capability. In the upcoming sections, we'll learn how to make the agent aware of such tools, how it decides which tool to use for a given problem, and how it actually invokes the tool and uses its output. This calculator is a building block for more complex and capable agents.