Class: Tool<A>

Defined in: lib/classes/tool.ts:209

A tool definition that serves as the single source of truth for a callable tool: its name, description, input schema, execution handler, and the @nhtio/adk!SpooledArtifact subclass that wraps its serialised output.

Remarks

The inputSchema is a @nhtio/validation schema. It is used at runtime to validate incoming arguments before the handler is called, and its .describe() output provides all the metadata needed to build a provider-specific LLM tool definition — annotate the schema with .description(), .note(), .example() etc. once, and that information is available in both contexts without duplication.

The handler is private — invoke it only through executor(ctx) which validates args, fires observability events (with a stable callId derived from the tool name and arguments), and wraps handler errors in @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR. The handler returns serialised bytes (string | Uint8Array); persistence is the consumer's responsibility.

artifactConstructor is the @nhtio/adk!SpooledArtifact subclass the consumer should use when wrapping the handler's output into a ToolCall.results field. The author declares it once on the tool instance; the consumer reads it when assembling persisted records.

Extended by

• ArtifactTool

Type Parameters

Type Parameter	Default type	Description
A extends SpooledArtifact	SpooledArtifact	The @nhtio/adk!SpooledArtifact subtype this tool's results should be wrapped in. Defaults to @nhtio/adk!SpooledArtifact.

Constructors

Constructor

new Tool<A>(raw: RawTool<A>): Tool<A>;

Defined in: lib/classes/tool.ts:252

Parameters

Parameter	Type	Description
raw	RawTool<A>	The raw tool input validated against rawToolSchema.

Returns

Tool<A>

Throws

@nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE when raw does not satisfy the schema.

Properties

Property	Modifier	Type	Default value	Description	Defined in
artifactConstructor	readonly	ArtifactConstructorResolver<A> | undefined	undefined	-	lib/classes/tool.ts:232
description	readonly	string	undefined	-	lib/classes/tool.ts:230
ephemeral	readonly	boolean	undefined	-	lib/classes/tool.ts:234
inputSchema	readonly	Schema	undefined	-	lib/classes/tool.ts:231
meta	readonly	Registry	undefined	-	lib/classes/tool.ts:233
name	readonly	string	undefined	-	lib/classes/tool.ts:229
onCollision	readonly	"keep" | "replace" | "throw"	undefined	-	lib/classes/tool.ts:236
trusted	readonly	boolean	undefined	-	lib/classes/tool.ts:235
schema	static	ObjectSchema<RawTool<SpooledArtifact>>	rawToolSchema	Validator schema that accepts a RawTool object. Remarks Reusable fragment for any schema that needs to validate or nest a tool entry (e.g. TurnRunnerConfig.tools).	lib/classes/tool.ts:217

Methods

describe()

describe(): {
  description: string;
  inputSchema: Description;
  name: string;
};

Defined in: lib/classes/tool.ts:422

Returns a fully serialisable snapshot of this tool's definition.

Returns

{
  description: string;
  inputSchema: Description;
  name: string;
}

{ name, description, inputSchema } where inputSchema is the schema description.

Name	Type	Defined in
description	string	lib/classes/tool.ts:422
inputSchema	Description	lib/classes/tool.ts:422
name	string	lib/classes/tool.ts:422

Remarks

The inputSchema property is the result of calling .describe() on the raw schema — a plain object carrying all the annotation metadata (descriptions, notes, examples, types) without any validator functions. Use this to build provider-specific LLM tool definitions.

---

executor()

executor(ctx: DispatchContext): (args: unknown) => Promise<
  | string
  | Uint8Array<ArrayBufferLike>
  | Media
| Media[]>;

Defined in: lib/classes/tool.ts:367

Returns a bound executor function for this tool against the given turn context.

Parameters

Parameter	Type	Description
ctx	DispatchContext	The active turn context. Provides emit functions and turn ID.

Returns

An async function (args) => Promise<string | Uint8Array>.

(args: unknown) => Promise< | string | Uint8Array<ArrayBufferLike> | Media | Media[]>

Remarks

The executor: (1) computes a stable callId as sha256(canonicalStringify({tool, args})) over the raw, pre-validation args, (2) validates args via Tool.validate, (3) emits toolExecutionStart on the context (with the computed callId), (4) calls the handler, (5) emits toolExecutionEnd (with the same callId), (6) wraps any handler error in @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR before re-throwing.

The handler returns serialised bytes (string | Uint8Array) — persistence is the consumer's concern. Use Tool.artifactConstructor when wrapping the bytes into a ToolCall.results field.

Pattern mirrors Middleware.runner() — call once per turn, reuse the returned function.

---

validate()

validate(args: unknown): Promise<unknown>;

Defined in: lib/classes/tool.ts:337

Validates args against the tool's input schema asynchronously.

Parameters

Parameter	Type	Description
args	unknown	The arguments to validate.

Returns

Promise<unknown>

The validated (and coerced) arguments.

Remarks

Async to support schemas with external validators (e.g. database lookups, API calls). A validation failure throws @nhtio/adk!E_INVALID_TOOL_ARGS — this indicates a programming error in the tool call loop, not a downstream failure.

Throws

@nhtio/adk!E_INVALID_TOOL_ARGS when args does not satisfy the input schema.

---

isTool()

static isTool(value: unknown): value is Tool<SpooledArtifact>;

Defined in: lib/classes/tool.ts:225

Returns true if value is a Tool instance.

Parameters

Parameter	Type	Description
value	unknown	The value to test.

Returns

value is Tool<SpooledArtifact>

true when value is a Tool instance.