Tool Use Fundamentals | LIZIU AI Agents

Why Tools Matter

Why Tool Use Matters

The Problem: LLMs can only generate text -- they cannot browse the web, query databases, execute code, or interact with external systems on their own.

The Solution: Tools bridge the gap between language understanding and real-world action, giving agents the ability to fetch data, compute results, and modify external state.

Real Impact: Tool use transforms LLMs from knowledge retrieval systems into action-taking agents that can accomplish real tasks.

Real-World Analogy

Think of tools as a craftsperson's workshop:

Tool Schema = The label on each tool explaining what it does
Parameters = The settings and adjustments on each tool
Execution = Actually using the tool to shape the material
Results = The output or measurement the tool provides
Error Handling = Knowing when a tool breaks and grabbing another

What Tools Enable

Information Retrieval

Search engines, databases, APIs -- tools let agents access up-to-date information beyond training data.

Computation

Code execution, calculators, data analysis -- tools handle precise computations LLMs cannot do reliably.

External Actions

Sending emails, creating files, updating databases -- tools let agents change the state of the world.

Verification

Checking facts, validating outputs, running tests -- tools provide ground truth for agent reasoning.

Tool Definition

tool_schema.py

# Define a tool using JSON Schema format
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather for a location.",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City name, e.g. San Francisco"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"]
                }
            },
            "required": ["location"]
        }
    }
}]

Output (Tool Schema)

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {"type": "string"},
      "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
    },
    "required": ["location"]
  }
}

Key Takeaway: Tool definitions use JSON Schema to describe parameters. The description field is critical -- it's what the LLM reads to decide when and how to use each tool. Vague descriptions lead to incorrect tool selection.

Tool Execution Flow

Handling Tool Results

tool_execution.py

import json

def execute_tool(tool_call, available_tools):
    func_name = tool_call.function.name
    args = json.loads(tool_call.function.arguments)

    if func_name in available_tools:
        try:
            result = available_tools[func_name](**args)
            return {
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": json.dumps(result)
            }
        except Exception as e:
            return {
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": f"Error: {str(e)}"
            }

Output

Tool call: get_weather({"location": "Paris"})
Tool result: {"temperature": 20, "condition": "sunny", "humidity": 45}
Model response: It's currently 20C and sunny in Paris with 45% humidity.

Common Mistake

Wrong: Returning raw exceptions as tool results: "Error: KeyError: 'temperature'"

Why it fails: The model cannot interpret Python stack traces meaningfully. It may hallucinate a fix or get stuck retrying the same broken call.

Instead: Return structured error messages: {"error": "Location not found. Try a major city name like 'Paris' or 'Tokyo'."}

Deep Dive: Tool Selection Strategies

When an agent has many tools available (10+), the model may struggle to select the right one. Strategies to improve selection: (1) Group related tools under a single "toolkit" with a router, (2) Use tool descriptions that clearly state when NOT to use the tool, (3) Provide few-shot examples of correct tool selection in the system prompt, (4) Implement a two-stage approach where a classifier first narrows down the relevant tools before the agent reasons about them.

Building Custom Tools

Tool Type	Description	Example
API Wrapper	Wraps an external REST API	Weather, stock prices
Database Query	Runs SQL or NoSQL queries	Customer lookup
Code Executor	Runs Python/JS in sandbox	Calculations, transforms
File Operations	Read, write, modify files	Report generation
Communication	Send messages/notifications	Email, Slack, webhooks

Key Takeaway: Tools bridge the gap between LLM knowledge (static, training data) and real-world actions (dynamic, current). Design tools with clear input schemas, helpful descriptions, and structured error responses.

Quick Reference

Best Practice	Description	Why
Clear descriptions	Write detailed tool docs	LLM uses description to decide when to call
Typed parameters	Use JSON Schema types	Reduces invalid parameter errors
Error messages	Return helpful errors	Agent can self-correct
Idempotency	Safe to call multiple times	Agent may retry on failure
Scoped access	Limit what tools can do	Prevents unintended side effects