Creating Tools

Tools are functions that AI agents can use to perform specific tasks, interact with external APIs, process data, or access external resources. They extend agent capabilities beyond simple text generation.

Overview

Tools in AgentPress are built using the AI SDK’s tool system with Zod schema validation. Each tool defines:

A clear description of what it does
An input schema defining required and optional parameters
An execute function that performs the actual work
Return data that can be displayed via UI components

File Structure

Tools are created in /packages/custom/src/tools/ and automatically discovered by the tool registry:


packages/custom/src/tools/
├── getWeather.ts           # Simple weather tool
├── scrape.ts              # Web scraping tool
├── getStockValue.ts       # Stock data tool
├── sendMessage.ts         # Message sending tool
└── some_folder/           # Organized tools in subdirectories
    ├── some_tool.ts

Basic Tool Structure

Here’s the anatomy of a basic tool:


import { tool } from "ai";
import * as z from "zod";
 
export const myTool = tool({
  description: "Clear, concise description of what this tool does",
  inputSchema: z.object({
    requiredParam: z
      .string()
      .describe("Description of required parameter"),
    optionalParam: z
      .number()
      .optional()
      .describe("Description of optional parameter"),
  }),
  execute: async ({ requiredParam, optionalParam = 0 }) => {
    try {
      // Your tool logic here
      const result = await performSomeOperation(requiredParam, optionalParam);
      
      return {
        success: true,
        data: result,
        timestamp: new Date().toISOString(),
      };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : "Unknown error",
        timestamp: new Date().toISOString(),
      };
    }
  },
});

Real-World Example: Weather Tool

Here’s the complete weather tool from the codebase:


import { tool } from "ai";
import * as z from "zod";
 
export const getWeather = tool({
  description: "Get the weather in a location",
  inputSchema: z.object({
    location: z
      .string()
      .describe(
        "The state or city to get the weather for. Should be the full name of the location. For example, instead of CA, it should be California, etc.",
      ),
  }),
  execute: async ({ location }) => ({
    location,
    temperature: Math.floor(Math.random() * 100),
  }),
});

Best Practices

Clear Descriptions: Write clear, actionable descriptions for tools and parameters
Input Validation: Use Zod schemas with appropriate validations and descriptions
Error Handling: Always handle errors gracefully with meaningful messages
Security: Sanitize inputs, validate data, and use environment variables for secrets
Performance: Implement caching and parallel processing where appropriate
Testing: Write unit and integration tests for your tools
Documentation: Keep your tool descriptions up to date and accurate
Naming: Use descriptive names for tools and parameters
Organization: Group related tools in subdirectories
Return Structure: Maintain consistent return data structures

Your tools will now be automatically discovered and available to agents configured to use them!