Class: Tool<A>

Defined in: src/lib/classes/tool.ts:212

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: src/lib/classes/tool.ts:263

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	Resolver for the artifact constructor used to wrap the handler's output, if any.	src/lib/classes/tool.ts:239
description	readonly	string	undefined	Human/model-facing description of what the tool does.	src/lib/classes/tool.ts:235
ephemeral	readonly	boolean	undefined	When true, the tool's results are not persisted to history (transient/one-shot).	src/lib/classes/tool.ts:243
inputSchema	readonly	Schema	undefined	Validation schema for the tool's arguments; also drives the generated parameter definition.	src/lib/classes/tool.ts:237
meta	readonly	Registry	undefined	Arbitrary per-tool metadata registry, passed through to the handler.	src/lib/classes/tool.ts:241
name	readonly	string	undefined	The tool's unique name, as exposed to the model in the tool definition.	src/lib/classes/tool.ts:233
onCollision	readonly	"keep" | "replace" | "throw"	undefined	How registration resolves a name clash in a ToolRegistry: throw, replace, or keep the existing.	src/lib/classes/tool.ts:247
trusted	readonly	boolean	undefined	When true, the tool's output is treated as trusted content by the LLM battery's envelopes.	src/lib/classes/tool.ts:245
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).	src/lib/classes/tool.ts:220

Methods

[ENCODE_METHOD]()

ENCODE_METHOD: unknown;

Defined in: src/lib/classes/tool.ts:460

Serialise this Tool into an @nhtio/encoder snapshot.

Returns

unknown

A RawTool-shaped snapshot (with inputSchema as an encoded string).

Remarks

Three halves with different serialisation strategies:

• Plain config (name, description, meta, flags) — emitted verbatim.
• inputSchema — delegated to @nhtio/validation's encode(), which captures the full schema description plus its library version into a compact string; decode rebuilds the live Schema.
• handler / artifactConstructor — emitted as functions. The encoder's FunctionSerializer serialises them by source text (fn.toString()). This is the sharp edge: a handler that closes over ctx, service clients, or config loses those bindings on decode — only the source survives, and the captured variables read back as undefined. A .bind()-ed or native handler cannot be serialised at all and the encoder throws. Tools are rarely serialised in practice; when they are, write handlers that reconstruct their dependencies inside the body rather than closing over them.

---

describe()

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

Defined in: src/lib/classes/tool.ts:433

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	src/lib/classes/tool.ts:433
inputSchema	Description	src/lib/classes/tool.ts:433
name	string	src/lib/classes/tool.ts:433

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: src/lib/classes/tool.ts:378

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: src/lib/classes/tool.ts:348

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.

---

[DECODE_METHOD]()

static DECODE_METHOD: Tool;

Defined in: src/lib/classes/tool.ts:485

Reconstruct a Tool from a Tool.[ENCODE_METHOD] snapshot.

Parameters

Parameter	Type	Description
data	unknown	The snapshot produced by Tool.[ENCODE_METHOD].

Returns

Tool

A fully-validated Tool.

Remarks

Rebuilds the live Schema via @nhtio/validation's decode(), then re-validates through the constructor. The rehydrated handler carries only its source text — see Tool.[ENCODE_METHOD] for the closure caveat.

---

isTool()

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

Defined in: src/lib/classes/tool.ts:228

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.