icepick.toolbox method creates a new toolbox that contains a collection of tools for agents to use with AI-powered selection.
Quick Reference
- Tool selection methods:
pick(),pickAndRun() - Utility methods:
assertExhaustive(),getTools()
Usage Example
Parameters
ToolDeclaration Array
Thetools parameter accepts an array of ToolDeclaration objects created with icepick.tool().
Returns
Theicepick.toolbox method returns a Toolbox<T> object with the following properties and methods:
Properties
Methods
pick(options)
Uses the language model to choose up to maxTools tools from this toolbox that best satisfy the provided prompt. Only tool selection is performed—no execution happens.
Parameters:
options:PickInput- Configuration for tool selection
Promise<Array<{ name: string, input: any }>> - Array containing chosen tool names with generated input arguments
pickAndRun(options)
Convenience method that first runs pick() and then immediately executes the chosen tool(s).
Type Overloads:
- When
maxToolsis omitted or1: ReturnsPromise<ToolResultMap<T>> - When
maxTools> 1: ReturnsPromise<ToolResultMap<T>[]>
options:PickInput- Configuration for tool selection and execution
Promise<ToolResultMap<T> | ToolResultMap<T>[]> - Single tool result or array of results depending on maxTools
assertExhaustive(result)
Helper method to assert that toolbox results are exhaustive for handling in switch statements. Use this in the default case to ensure all tool results are handled.
Parameters:
result:never- The result to assert is exhaustive
never - This method always throws
Throws: Error if the result is not exhaustive, indicating an unhandled tool result
getTools()
Gets the original tool declarations used internally by the pick-tool workflow.
Returns: T - The array of tool declarations provided when creating the toolbox
PickInput Type
ToolResultMap Type
TheToolResultMap<T> is a discriminated union type that provides type-safe access to tool results:
This allows you to use switch statements with full TypeScript type checking:
ToolSet Type
The AI-ready toolset used internally by language models for tool selection:Related
icepick.tool- Create individual tools to add to toolboxesicepick.agent- Create agents that can use toolboxes- Hatchet Documentation - Learn more about the underlying workflow engine

