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
{
"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.