Chapter 3: Tool Design (The Contract)

In the previous chapter, Agent Skill (Progressive Disclosure), we taught our agent how to find the right instruction manual (Skill) from a massive library.

Now that the agent has the manual, it needs to actually do something. It needs to check the weather, query a database, or send an email. In the world of AI, we call these capabilities Tools.

The Problem: The Fuzzy Pilot vs. The Rigid Plane

There is a fundamental clash in AI development:

1. The AI (The Pilot): Thinks in "fuzzy" logic, probability, and natural language. It is creative but imprecise.
2. The Code (The Plane): Requires "rigid" logic, exact syntax, and specific data types. It crashes if you miss a single semicolon.

Tool Design is the art of building the dashboard that connects the Pilot to the Plane.

If you give the pilot a button labeled "Do Stuff," they will be confused. They might press it at the wrong time. If the button breaks, and a red light just flashes "ERROR," the pilot won't know how to fix it.

A good tool is a Contract. It guarantees: "If you give me specifically this input, I promise to do that action."

Use Case: The Weather Bot

Let's build a tool for a weather agent. We want the agent to tell us if we need an umbrella.

Principle 1: The Description is the Prompt

Many developers write tool descriptions for themselves.

• Bad Description: "Returns weather data."

This is terrible for an AI. It doesn't tell the AI when to use it or what creates a valid input. The description is actually a prompt that tells the AI how to behave.

• Good Description: "Retrieves current temperature and precipitation. Use this when the user asks about weather, umbrellas, or what to wear."

Principle 2: The Consolidation Principle

Imagine you need to check the weather.

• Approach A (Fragmented): You have three tools: get_latitude(), get_longitude(), and fetch_weather_by_coords().
• Approach B (Consolidated): You have one tool: get_weather(city_name).

The Consolidation Principle: If a human engineer would find it annoying to call three functions to do one simple task, the agent will too.

Agents have a limited "attention budget." Every time they have to use a tool, they risk getting distracted or hallucinating. Group related steps into a single, robust tool.

Building the Tool Contract

Let's look at how we define a tool in Python. We treat the tool definition as a dictionary that we feed to the LLM.

Step 1: Defining the Inputs (The Schema)

We must be strict about what we accept. We use a concept called a Schema (often defined using JSON or libraries like Pydantic/Zod).

weather_tool_definition = {
    "name": "get_weather",
    "description": "Get current weather for a specific city.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City and State, e.g., 'Austin, TX'"
            },
            "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"]
            }
        },
        "required": ["location"]
    }
}

Explanation: This acts as the "Dashboard Label." It tells the agent exactly what switches (parameters) exist. Notice the enum—we restrict the AI to only two specific choices for units.

Step 2: The Execution Logic

This is the rigid code that runs when the AI pulls the lever.

def execute_weather_tool(location, unit="fahrenheit"):
    """The actual Python function the agent triggers."""
    # In a real app, this calls a Weather API
    if location.lower() == "london":
        return "Rainy, 55 degrees"
    else:
        return "Sunny, 75 degrees"

Principle 3: Error Messages as Recovery Instructions

What happens if the Agent tries to use the tool incorrectly?

• Agent Input: get_weather(location="The Big Apple")
• Bad Error: 404 Not Found. (The agent doesn't know what to do).
• Good Error: Error: Location 'The Big Apple' not recognized. Please provide a standard City format like 'New York, NY'.

If we design error messages to be instructive, the Agent can self-correct. It reads the error, thinks "Oops," and tries again with "New York, NY".

Internal Implementation: The Tool Loop

How does the fuzzy brain actually "click" the rigid button? It happens in a loop.

1. User asks a question.
2. Agent decides it needs a tool and generates a structured "Call".
3. System executes the Python code.
4. System feeds the result back to the Agent.
5. Agent reads the result and answers the user.

The Code: Parsing the Intent

Here is a simplified view of how we handle the Agent's request to use a tool.

import json

def handle_tool_call(tool_call_json):
    """Parses the AI's string response into a function call."""
    
    # 1. Parse the fuzzy string into a rigid Dictionary
    data = json.loads(tool_call_json)
    tool_name = data.get("name")
    params = data.get("arguments")
    
    # 2. Route to the correct function
    if tool_name == "get_weather":
        return execute_weather_tool(**params)
        
    return "Error: Tool not found."

Explanation: The AI gives us a JSON string. We convert that string into Python variables. If the string is malformed (e.g., missing a quote), json.loads will fail. A robust system catches that failure and sends a "Fix your JSON" error message back to the AI.

Optimizing Response Formats

The final part of the contract is the Return Value. Remember Chapter 1: Context Engineering? We have a limited context window.

If get_weather returns a 5,000-line JSON blob with historical barometric pressure, we are filling the workbench with junk.

Design your tools to return concise summaries.

• Bad Return: Raw API dump (20kb of text).
• Good Return: {"condition": "Rain", "temp": 55, "unit": "F"}

Summary

In this chapter, you learned:

1. Tools are Contracts: They bridge the gap between fuzzy intent and rigid execution.
2. Descriptions are Prompts: Describe when and why to use a tool, not just what it does.
3. Consolidation: One smart tool is better than five dumb ones.
4. Actionable Errors: Error messages should teach the agent how to fix the mistake.

Now we have a context (Workbench), a manual (Skills), and a dashboard (Tools). But simply calling a tool isn't enough. The agent needs to think about the result. It needs to look at the weather, realize it's cold, and then decide to check for coat prices.

We call this process Interleaved Thinking.

Next Chapter: Interleaved Thinking

Generated by Code IQ