Skip to main content
The icepick.toolbox method creates a new toolbox that contains a collection of tools for agents to use with AI-powered selection.

Quick Reference

Usage Example

Parameters

ToolDeclaration Array

The tools parameter accepts an array of ToolDeclaration objects created with icepick.tool().

Returns

The icepick.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
Returns: 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 maxTools is omitted or 1: Returns Promise<ToolResultMap<T>>
  • When maxTools > 1: Returns Promise<ToolResultMap<T>[]>
Parameters:
  • options: PickInput - Configuration for tool selection and execution
Returns: 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
Returns: 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

The ToolResultMap<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: