> ## Documentation Index > Fetch the complete documentation index at: https://icepick.hatchet.run/llms.txt > Use this file to discover all available pages before exploring further. # icepick.tool > API reference for icepick.tool. The `icepick.tool` method creates a new tool that can be used by agents in Icepick. ## Quick Reference * **Main execution methods**: [`run()`](#run-input%2C-options%3F), [`runAndWait()`](#runandwait-input%2C-options%3F), [`runNoWait()`](#runnowait-input%2C-options%3F) * **Scheduling methods**: [`schedule()`](#schedule-enqueueat%2C-input%2C-options%3F), [`delay()`](#delay-duration%2C-input%2C-options%3F), [`cron()`](#cron-name%2C-expression%2C-input%2C-options%3F) ## Usage Example ```typescript theme={null} import { z } from "zod"; import { icepick } from "@hatchet-dev/icepick"; export const myTool = icepick.tool({ name: "my-tool", description: "Description of what this tool does", inputSchema: z.object({ // TODO: Define your input schema here // Example: input: z.string().describe("The input parameter") }), outputSchema: z.object({ // TODO: Define your output schema here // Example: result: z.string().describe("The tool result") }), fn: async (input) => { try { // TODO: Implement your tool logic here // Example API call: // const response = await fetch(`https://api.example.com/data?param=${input.param}`); // const data = await response.json(); return { // TODO: Return your tool output here // Example: result: data.message }; } catch (error) { return { // TODO: Handle errors appropriately for your tool // Example: result: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` }; } }, }); ``` ## Parameters | Parameter | Type | Required | Description | | ------------------ | -------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | Yes | A unique identifier for the tool. Used for tool registration and selection by agents. | | `description` | `string` | Yes | A human-readable description of what the tool does. Used by language models to decide when to use the tool. | | `inputSchema` | `ZodType` | Yes | Zod schema that defines and validates the input structure for the tool. | | `outputSchema` | `ZodType` | Yes | Zod schema that defines and validates the output structure returned by the tool. | | `fn` | `(input: z.infer, ctx?: Context) => Promise>` | Yes | The main tool function that processes input and returns output. Receives validated input and optional [Context](#context). | | `executionTimeout` | `string` | No | Execution timeout duration for the tool after it starts running. Go duration format (e.g., "1s", "5m", "1h"). Default: "60s" | | `scheduleTimeout` | `string` | No | Schedule timeout for the tool (max duration to allow the tool to wait in the queue). Go duration format. Default: "5m" | | `retries` | `number` | No | Number of retries for the tool. Default: 0 | | `concurrency` | [`Concurrency`](#concurrency-type) \| [`Concurrency[]`](#concurrency-type) | No | Concurrency configuration for the tool. Controls how many concurrent executions are allowed. | | `defaultPriority` | `Priority` | No | The priority for the tool. Values: Priority.LOW (1), Priority.MEDIUM (2), Priority.HIGH (3) | | `onCrons` | `string[]` | No | Cron config for the tool. | | `onEvents` | `string[]` | No | Event config for the tool. | ### Concurrency Type | Property | Type | Required | Description | | --------------- | -------------------------- | -------- | ---------------------------------------------------------------------------------------- | | `expression` | `string` | Yes | The CEL expression to use for concurrency (e.g., "input.key") | | `maxRuns` | `number` | No | The maximum number of concurrent workflow runs. Default: 1 | | `limitStrategy` | `ConcurrencyLimitStrategy` | No | The strategy to use when the concurrency limit is reached. Default: CANCEL\_IN\_PROGRESS | ## Returns The `icepick.tool` method returns a `ToolDeclaration & { name: Name }` object with the following [properties](#properties) and [methods](#methods): ### Properties | Property | Type | Description | | -------------- | ----------------------------- | -------------------------------------------------------- | | `inputSchema` | `InputSchema` | The Zod schema used for input validation | | `outputSchema` | `OutputSchema` | The Zod schema used for output validation | | `description` | `string` | The description of the tool | | `name` | `string` | The unique name identifier for the tool | | `client` | `IHatchetClient \| undefined` | The Hatchet client instance used to execute the workflow | | `definition` | `WorkflowDefinition` | The internal workflow definition | ### Methods #### `run(input, options?)` Executes the tool with the given input and waits for completion. **Parameters:** * `input`: `z.infer` - The input data for the tool * `options?`: [`RunOpts`](#runopts-type) - Optional configuration for this tool run **Returns:** `Promise>` - A promise that resolves with the tool result **Throws:** Error if the tool is not bound to a Hatchet client #### `runAndWait(input, options?)` Alias for [`run()`](#runinput-options). Triggers a tool run and waits for the result. **Parameters:** * `input`: `z.infer` - The input data for the tool * `options?`: [`RunOpts`](#runopts-type) - Optional configuration for this tool run **Returns:** `Promise>` - A promise that resolves with the tool result #### `runNoWait(input, options?)` Triggers the tool execution without waiting for completion. **Parameters:** * `input`: `z.infer` - The input data for the tool * `options?`: [`RunOpts`](#runopts-type) - Optional configuration for this tool run **Returns:** `Promise>>` - A WorkflowRunRef containing the run ID and methods to get results and interact with the run **Throws:** Error if the tool is not bound to a Hatchet client #### `schedule(enqueueAt, input, options?)` Schedules the tool to run at a specific date and time in the future. **Parameters:** * `enqueueAt`: `Date` - The date when the tool should be triggered * `input`: `z.infer` - The input data for the tool * `options?`: [`RunOpts`](#runopts-type) - Optional configuration for this tool run **Returns:** `Promise` - A promise that resolves with the scheduled workflow details **Throws:** Error if the tool is not bound to a Hatchet client #### `delay(duration, input, options?)` Schedules the tool to run after a specified delay. **Parameters:** * `duration`: `number` - The delay in seconds before the tool should run * `input`: `z.infer` - The input data for the tool * `options?`: [`RunOpts`](#runopts-type) - Optional configuration for this tool run **Returns:** `Promise` - A promise that resolves with the scheduled workflow details **Throws:** Error if the tool is not bound to a Hatchet client #### `cron(name, expression, input, options?)` Creates a cron schedule for recurring tool execution. **Parameters:** * `name`: `string` - The name of the cron schedule * `expression`: `string` - The cron expression defining the schedule * `input`: `z.infer` - The input data for the tool * `options?`: [`RunOpts`](#runopts-type) - Optional configuration for this tool run **Returns:** `Promise` - A promise that resolves with the cron workflow details **Throws:** Error if the tool is not bound to a Hatchet client ### RunOpts Type | Property | Type | Required | Description | | -------------------- | ------------------------ | -------- | --------------------------------------------------------------------------------------------------- | | `additionalMetadata` | `Record` | No | Additional metadata to attach to the workflow run | | `priority` | `Priority` | No | The priority for the workflow run. Values: Priority.LOW (1), Priority.MEDIUM (2), Priority.HIGH (3) | ## Context The optional `ctx` parameter in the tool function provides access to the Hatchet workflow execution context. When present, it offers comprehensive capabilities for workflow management, logging, and execution control. ### Core Properties | Property | Type | Description | | --------------------- | --------------------------- | ----------------------------------------------------- | | `input` | `T` | The original input data for the tool | | `workflowRunId()` | `() => string` | Gets the ID of the current workflow run | | `workflowName()` | `() => string` | Gets the name of the current workflow | | `taskName()` | `() => string` | Gets the name of the current running task | | `taskRunId()` | `() => string` | Gets the ID of the current task run | | `workflowId()` | `() => string \| undefined` | Gets the workflow ID | | `workflowVersionId()` | `() => string \| undefined` | Gets the workflow version ID | | `cancelled` | `boolean` | Gets cancellation status | | `controller` | `AbortController` | The abort controller for the current task | | `logger` | `Logger` | Structured logging methods (info, debug, warn, error) | ### Execution Control Methods | Method | Parameters | Returns | Description | | ------------------ | ----------------------- | --------------- | ---------------------------------------------------------- | | `cancel()` | None | `Promise` | Cancels the current task | | `refreshTimeout()` | `incrementBy: Duration` | `Promise` | Refreshes the timeout for the current task | | `retryCount()` | None | `number` | Gets the number of times the current task has been retried | ### Logging & Data Methods | Method | Parameters | Returns | Description | | ---------------------- | ---------------------------- | ------------------------ | ----------------------------------------------------------------------- | | `putStream()` | `data: string \| Uint8Array` | `Promise` | Streams data from the current task run | | `additionalMetadata()` | None | `Record` | Retrieves additional metadata | | `errors()` | None | `Record` | Returns errors from any task runs in the workflow | | `triggers()` | None | `TriggerData` | Gets the dag conditional triggers for the current workflow run | | `filterPayload()` | None | `Record` | Gets the payload from the filter that matched when triggering the event | | `triggeredByEvent()` | None | `boolean` | Determines if the workflow was triggered by an event | | `priority()` | None | `Priority \| undefined` | Gets the priority of the workflow | ## Related * [`icepick.agent`](/api-reference/agent) - Create agents that can use tools * [`icepick.toolbox`](/api-reference/toolbox) - Create collections of tools for agents to use * [Hatchet Documentation](https://docs.hatchet.run) - Learn more about the underlying workflow engine