Class: Tool<A>

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>;

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
artifactConstructor	readonly	ArtifactConstructorResolver<A> | undefined	undefined	-
description	readonly	string	undefined	-
ephemeral	readonly	boolean	undefined	-
inputSchema	readonly	Schema	undefined	-
meta	readonly	Registry	undefined	-
name	readonly	string	undefined	-
onCollision	readonly	"keep" | "replace" | "throw"	undefined	-
trusted	readonly	boolean	undefined	-
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).

Methods

describe()

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

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
description	string
inputSchema	Description
name	string

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[]>;

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>;

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>;

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.