Define Your Tools | Just Add AI

The Technique

Modern AI APIs let you define "tools" — functions that the AI can request to call. The AI doesn't execute these functions directly; it tells your code which function to call with which arguments.

Here's the key insight: the AI decides what to call based entirely on your tool definitions. The name, description, and parameter descriptions you write determine whether the AI calls the right tool at the right time with the right arguments.

Anatomy of a Good Tool Definition

Name

Clear, action-oriented function name

Use verbs that describe what the tool does. Keep it concise but unambiguous.

Good: get_weather, send_email, search_products
Bad: helper, do_thing, function1

Description

Detailed explanation of what, when, and why

This is the most important part. Tell the AI exactly what the tool does, when to use it, and what it returns.

Good: "Get current weather conditions for a city. Returns temperature, humidity, and conditions. Use when user asks about weather, temperature, or whether to bring an umbrella."

Bad: "Gets weather"

Parameters

Each parameter with type, description, and constraints

Describe each parameter clearly. Include the expected format, valid values, and examples.

Good: "location: City name with optional country (e.g., 'Tokyo', 'Paris, France')"
Bad: "location: string"

Good vs. Bad Tool Definitions

Vague Definition

{ "name": "search", "description": "Searches things" }

Detailed Definition

{ "name": "search_products", "description": "Search the product catalog. Returns up to 10 products with name, price, availability. Use when user wants to find or compare products." }

The detailed definition tells the AI exactly when to use this tool, what it returns, and how many results to expect. The vague definition could mean anything.

Complete Example

Well-Defined Tool
{
  "name": "create_calendar_event",
  "description": "Create a new event on the user's calendar. Use when the user wants to schedule a meeting, appointment, or reminder. Returns the event ID and confirmation link. Cannot create recurring events — use create_recurring_event for those.",
  "parameters": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "Event title (e.g., 'Team standup', 'Dentist')"
      },
      "start_time": {
        "type": "string",
        "description": "Start time in ISO 8601 (e.g., '2024-03-15T14:00:00')"
      },
      "duration_minutes": {
        "type": "integer",
        "description": "Duration in minutes. Default to 60 if not specified."
      }
    },
    "required": ["title", "start_time"]
  }
}

Notice how the description explains when to use it, what it returns, and when NOT to use it (recurring events). Each parameter includes format examples and default behavior.

The Technique

Write tool definitions as if you're explaining to a smart colleague who's never used your system. Be specific about what it does, when to use it, what format arguments should take, and what it returns.

Tips for Better Definitions

•
Explain when NOT to use it. If you have similar tools, clarify the boundary. "Use get_weather for current conditions, get_forecast for future weather."
•
Include return value info. Tell the AI what the function returns so it knows what to expect.
•
Give format examples. For dates, IDs, or structured strings, show the exact format: "ISO 8601 like '2024-03-15T14:00:00'"
•
Suggest defaults. "Default to 60 minutes if duration not specified."
•
Use enums for fixed choices. If a parameter only accepts certain values, list them as an enum.

Why This Matters

The AI can only be as good as the information you give it. A well-defined tool will be called correctly most of the time. A poorly defined tool leads to wrong calls and frustrated users.

Think of tool definitions as the interface contract between you and the AI. The clearer the contract, the better the collaboration.

The Technique

Anatomy of a Good Tool Definition

Good vs. Bad Tool Definitions

Complete Example

The Technique

Tips for Better Definitions

Why This Matters

Related

Give It Your Toolkit