Defining tool schemas and descriptions in Agentic AI

Introduction

Defining tool schemas and descriptions helps AI agents understand what tools they can use and how to use them correctly.

When building an AI agent that needs to interact with multiple tools or APIs.

When you want the AI to know what inputs a tool requires and what outputs it produces.

When you want to make your AI system more organized and easier to maintain.

When you want to improve the AI's ability to choose the right tool for a task.

When you want to provide clear documentation for tools used by AI agents.

Syntax

Agentic AI

tool_schema = {
    "name": "tool_name",
    "description": "What the tool does",
    "parameters": {
        "param1": "description of param1",
        "param2": "description of param2"
    }
}

The schema is usually a dictionary or JSON object describing the tool.

Descriptions should be clear and simple so the AI can understand the tool's purpose.

Examples

This schema describes a calculator tool with operation type and numbers as inputs.

Agentic AI

tool_schema = {
    "name": "calculator",
    "description": "Performs basic math operations",
    "parameters": {
        "operation": "Type of math operation like add or subtract",
        "numbers": "List of numbers to calculate"
    }
}

This schema defines a weather API tool with location and units parameters.

Agentic AI

tool_schema = {
    "name": "weather_api",
    "description": "Fetches current weather data",
    "parameters": {
        "location": "City or coordinates for weather data",
        "units": "Measurement units like metric or imperial"
    }
}

Sample Model

This program defines a function to create tool schemas and uses it to define a text summarizer tool schema. It then prints the schema.

Agentic AI

def define_tool_schema(name, description, parameters):
    return {
        "name": name,
        "description": description,
        "parameters": parameters
    }

# Define a tool schema for a text summarizer
text_summarizer_schema = define_tool_schema(
    "text_summarizer",
    "Summarizes long text into short key points",
    {
        "text": "The input text to summarize",
        "max_length": "Maximum length of the summary"
    }
)

print(text_summarizer_schema)

Important Notes

Always keep tool descriptions simple and clear for better AI understanding.

Include all necessary parameters so the AI knows what inputs to provide.

Use consistent naming to avoid confusion when multiple tools are used.

Summary

Tool schemas describe what a tool does and what inputs it needs.

Clear descriptions help AI agents use tools correctly.

Defining schemas makes AI systems easier to build and maintain.