Michael Brenndoerfer | Data & AI, Private Equity, Technology

Michael Brenndoerfer

Designing Simple Tool Interfaces › Key Design Principles

Michael BrenndoerferJune 25, 20252 min read

AI Agent HandbookAll chapters

Part 5 of 15Tool Use - Extending the Agent's Abilities

Chapter 13Designing Simple Tool Interfaces › Key Design Principles

Reading section 6 of 12 · Key Design Principles · 2 minSection 6 of 12 · 2 min

Section 6 of 12 · 2 min read

Designing Simple Tool Interfaces › Key Design PrinciplesOne section · Sections in this chapter6 / 12 ↓

Sections in this chapter12

As you design tool interfaces for your agents, keep these principles in mind:

Make Tools FocusedLink Copied

Each tool should do one thing well. Instead of a giant do_everything function, create specific tools:

✅ Good: get_weather(city), get_forecast(city, days), get_air_quality(city)
❌ Bad: get_weather_data(city, type, days, include_air_quality, include_pollen)

Focused tools are easier for the agent to understand and use correctly.

Use Clear, Descriptive NamesLink Copied

Tool names should clearly indicate what they do:

✅ Good: send_email, search_documents, calculate_mortgage
❌ Bad: do_thing, helper, process

The agent uses tool names as part of its decision-making process. Clear names help it choose the right tool.

Provide Examples in DescriptionsLink Copied

When describing parameters, include examples:

In[2]:

Code

"city": {
    "type": "string",
    "description": "City name (e.g., 'Tokyo', 'New York', 'London')"
}

Examples help the agent understand the expected format and extract the right information from user queries.

Return Structured DataLink Copied

Tools should return data in a consistent, structured format:

In[4]:

Code

## Good: Structured dictionary
return {
    "temperature": 72,
    "conditions": "partly cloudy",
    "humidity": 65
}

## Bad: Unstructured string
return "It's 72 degrees and partly cloudy with humidity at 65%"

Structured data gives the agent flexibility in how it presents the information. It can emphasize different aspects based on what the user asked.

Handle Errors GracefullyLink Copied

Tools should return meaningful error information when something goes wrong:

In[8]:

Code

def get_weather(city: str) -> dict:
    """Get current weather for a city."""
    try:
        # Call weather API
        result = weather_api.get(city)
        return {
            "success": True,
            "data": result
        }
    except CityNotFound:
        return {
            "success": False,
            "error": f"City '{city}' not found"
        }
    except APIError as e:
        return {
            "success": False,
            "error": "Weather service temporarily unavailable"
        }

This allows the agent to provide helpful error messages to the user instead of crashing or giving confusing responses.