In Icepick, a tool is a function that performs a specific task and can be called by agents. Tools handle the actual work while agents orchestrate their execution.

Creating a Tool

To create a tool, define the input and output schemas using Zod. Each Zod field should include a description to improve LLM tool selection when used in a toolbox.

import z from "zod";

const MyToolInput = z.object({
  message: z.string().describe("The message to process"),
});

const MyToolOutput = z.object({
  result: z.string().describe("The processed result"),
});

Create the tool using the icepick.tool method:

export const myTool = icepick.tool({
  name: "my-tool",
  description: "Processes messages and returns results",
  inputSchema: MyToolInput,
  outputSchema: MyToolOutput,
  fn: async (input) => {
    // Tool logic here - API calls, data processing, etc.
    return {
      result: `Processed: ${input.message}`,
    };
  },
});

Tools can perform side effects like API calls, database operations, or file system access. Unlike agents, tools are designed to do the actual work and can maintain state as needed.

Running a Tool

Tools can be executed directly using several methods. The most common is run, which executes the tool and waits for completion:

const result = await myTool.run({
  message: "Hello, world!",
});

console.log(result.result); // "Processed: Hello, world!"

For fire-and-forget scenarios, use runNoWait to trigger execution without waiting:

const runRef = await myTool.runNoWait({
  message: "Background task",
});

console.log(`Started run: ${runRef.workflowRunId}`);

Tools can also be scheduled to run at specific times or on recurring schedules:

// Schedule to run at a specific time
const scheduledRun = await myTool.schedule(new Date("2024-12-25T09:00:00Z"), {
  message: "Christmas task",
});

// Schedule with a delay
const delayedRun = await myTool.delay(
  300, // 300 seconds = 5 minutes
  { message: "Delayed task" }
);

// Set up recurring cron schedule
const cronRun = await myTool.cron(
  "daily-cleanup",
  "0 2 * * *", // Every day at 2 AM
  { message: "Daily cleanup task" }
);

Using Tools in Agents

Tools are typically called from within agents using the tool’s run method:

export const myAgent = icepick.agent({
  name: "my-agent",
  inputSchema: z.object({ message: z.string() }),
  outputSchema: z.object({ response: z.string() }),
  fn: async (input, ctx) => {
    const { result } = await myTool.run({
      message: input.message,
    });

    return {
      response: result,
    };
  },
});

This approach allows agents to orchestrate tool execution while maintaining durability and fault tolerance.

Get Started

Concepts

Development

Adding to Your Codebase

Patterns

Deployment

API Reference

CLI Reference

Tools

Creating a Tool

Running a Tool

Using Tools in Agents

​Creating a Tool

​Running a Tool

​Using Tools in Agents

Creating a Tool

Running a Tool

Using Tools in Agents