@orkestrel/tool

The tool runtime for the @orkestrel line: a Tool binding an advertised JSON Schema definition to its handler, a ToolManager registry that advertises those definitions and executes calls with per-call error isolation, and the correlated ToolCall and ToolResult pair that travels between a caller and the registry.

Build a tool with the createTool function, register it in a registry from the createToolManager function, hand definitions() to whatever chooses the call, and pass the call you get back to execute. Nothing here is model-specific — an agent loop, an MCP bridge, and plain application code are all callers.

Install

npm install @orkestrel/tool

Example

import { createTool, createToolManager } from '@orkestrel/tool'

const tools = createToolManager()
tools.add(
	createTool({
		name: 'add',
		description: 'Add two numeric values and return their sum.',
		parameters: {
			type: 'object',
			properties: {
				left: { type: 'number' },
				right: { type: 'number' },
			},
			required: ['left', 'right'],
		},
		execute: (args) => Number(args.left) + Number(args.right),
	}),
)

tools.definitions() // hand these to whatever chooses the call

const result = await tools.execute({
	id: 'call-1',
	name: 'add',
	arguments: { left: 2, right: 3 },
})
if (result.success) {
	result.value // 5
} else {
	result.error // the failure message
}

Handlers may be synchronous or asynchronous. An unknown name or a thrown handler becomes an error result instead of escaping, and a batch runs concurrently, stays isolated per call, and answers in input order.

Ready-made tools ship in @orkestrel/toolbox.

See the tool guide for the complete surface and behavior.

Requirements

• Node.js 22.12 or newer
• ESM and CommonJS consumers

License

MIT © Orkestrel — see LICENSE.