What is the best way to define tools for AI?
Use JSON Schema for Parameters
Most AI platforms (OpenAI, Anthropic, Google) expect tool definitions in JSON Schema format. Each tool has a name, description, and a parameters object that follows JSON Schema. The parameters object specifies the input arguments, their types, and which are required.
For example, a weather tool might have parameters like location (string, required) and unit (string, optional, enum: ['celsius', 'fahrenheit']). This structure lets the model generate valid arguments.
- Name: unique, lowercase, underscores (e.g., get_weather)
- Description: concise explanation of what the tool does and when to use it
- Parameters: JSON Schema object with type 'object', properties, and required array
- Enums: list allowed values for categorical inputs
- Defaults: specify if an argument is optional
Craft Clear Descriptions
The description is crucial because the model uses it to decide which tool to call. Write it as if explaining to a new developer: state the tool's purpose, when to use it, and any side effects. Avoid jargon and ambiguity.
For parameters, add descriptions too. For instance, 'location: The city and state, e.g., San Francisco, CA'. This reduces errors and improves reliability.
Keep Tools Focused
Each tool should do one thing well. Avoid mega-tools with many optional parameters that try to handle multiple tasks. Instead, create separate tools for distinct actions. This makes it easier for the model to choose correctly and for you to maintain the code.
Also, limit the total number of tools per request. Too many options can confuse the model and increase latency. If you have many tools, consider grouping them or using a routing mechanism.
Common mistakes
- Using vague descriptions like 'does stuff' that don't help the model decide when to call the tool.
- Forgetting to mark required parameters, leading to missing arguments in calls.
- Defining overly complex tools with many optional parameters instead of splitting into simpler tools.