Tool Setup

Learn how to create and configure tools for your DAIN service

Overview

Tools are the core building blocks of DAIN services. Each tool represents a specific capability that AI agents can use to perform actions. When an agent connects to your service, it can access and utilize these tools based on their descriptions and defined input/output schemas.

Creating a Tool

A tool is defined using the ToolConfig type and consists of several key components:

const exampleTool: ToolConfig = {
  id: "unique-tool-id",
  name: "Human Readable Name",
  description: "Detailed description of what the tool does",
  input: z.object({
    // Input parameters schema
  }),
  output: z.object({
    // Output data schema
  }),
  pricing: { pricePerUse: 0, currency: "USD" },
  handler: async (inputs, agentInfo) => {
    // Tool logic
  }
};

Essential Components

  1. Identification

    id: "get-weather",        // Unique identifier for the tool
name: "Get Weather",      // Display name

  2. Description The description is crucial as it guides the AI agent on when and how to use the tool. It should be clear and specific:

    description: "Fetches current weather conditions for a given location. Returns temperature,
             wind speed, and precipitation probability. Use this when you need real-time
             weather information for a specific city or coordinates."

  3. Input/Output Schema Use Zod to define exact input and output structures:

    input: z.object({
  latitude: z.number().describe("Latitude coordinate"),
  longitude: z.number().describe("Longitude coordinate"),
  units: z.enum(["metric", "imperial"]).optional()
}).describe("Weather request parameters"),

output: z.object({
  temperature: z.number(),
  windSpeed: z.number(),
  precipitation: z.number()
}).describe("Current weather conditions")

  4. Pricing Define the cost per use:

    pricing: {
  pricePerUse: 0.01,
  currency: "USD"
}

Handler Implementation

The tool's handler function processes requests and returns results. Learn more about implementing handler logic in the Handler Logic section.

Response Structure

Tools can return data along with UI components for visual presentation. See the Handler Returns section for details on structuring responses.

Examples

Web Search Tool

const searchWebConfig: ToolConfig = {
  id: "search-web",
  name: "Search Web",
  description: "Searches the web and returns the top 5 most relevant results with their titles, URLs, and descriptions. Use this when you need to find current information about any topic.",
  input: z.object({
    query: z.string().describe("Search query term or phrase")
  }),
  output: z.object({
    results: z.array(z.object({
      title: z.string(),
      url: z.string(),
      description: z.string()
    }))
  }),
  handler: async ({ query }, agentInfo) => {
    // Handler implementation
  }
};

Stock Price Tool

const getStockPriceConfig: ToolConfig = {
  id: "get-stock-price",
  name: "Get Stock Price",
  description: "Fetches real-time stock price and daily statistics for any stock ticker symbol. Returns current price, daily high/low, volume, and price change percentage. Use this for getting up-to-date stock market information.",
  input: z.object({
    ticker: z.string().describe("Stock ticker symbol (e.g., AAPL)")
  }),
  output: z.object({
    price: z.number(),
    change: z.number(),
    volume: z.number()
  }),
  handler: async ({ ticker }, agentInfo) => {
    // Handler implementation
  }
};

Weather Forecast Tool

const getWeatherConfig: ToolConfig = {
  id: "get-weather",
  name: "Get Weather",
  description: "Provides current weather conditions and 5-day forecast for any location. Input can be city name or coordinates. Returns temperature, humidity, wind speed, and precipitation probability.",
  input: z.object({
    location: z.string().describe("City name or coordinates"),
    units: z.enum(["celsius", "fahrenheit"]).optional()
  }),
  output: z.object({
    current: z.object({
      temp: z.number(),
      humidity: z.number()
    }),
    forecast: z.array(z.object({
      date: z.string(),
      temp: z.number()
    }))
  }),
  handler: async ({ location, units }, agentInfo) => {
    // Handler implementation
  }
};

Note:

Remember that tool descriptions are crucial for AI agents to understand when and how to use each tool. Write descriptions that are clear, specific, and include all necessary context about the tool's purpose and capabilities.