Class: ArtifactTool

A @nhtio/adk!Tool subclass whose handler return value is wrapped directly in a @nhtio/adk!Tokenizable (not a @nhtio/adk!SpooledArtifact) when it lands on ToolCall.results.

Remarks

ArtifactTool is the canonical producer for forged artifact-query tools — the tools SpooledArtifact.forgeTools(ctx) emits so the model can head, tail, grep, json_get, md_headings (etc.) an artifact that is already in ctx.turnToolCalls.

The difference from @nhtio/adk!Tool is structural, not stylistic:

• A normal Tool's handler returns bytes the ADK wraps in a fresh SpooledArtifact. The artifact lands in ToolCall.results, joins ctx.turnToolCalls, and is itself a first-class queryable artifact in the turn.
• An ArtifactTool's handler returns a string that is already the model-visible answer to a query against an existing artifact. The ADK wraps it in a Tokenizable rather than a SpooledArtifact; nothing new is queryable on its own. Subsequent forgeTools(ctx) calls exclude ToolCalls produced by an ArtifactTool from the callId enum (via the ToolCall.fromArtifactTool marker) — this is the structural fix that breaks the otherwise-recursive grep-on-the-grep-result loop.

Consumers who want to build their own artifact-query tools (e.g. for a domain-specific spooled subclass not shipped by the ADK) should extend or instantiate this class.

Extends

• Tool

Constructors

Constructor

new ArtifactTool(raw: RawArtifactTool): ArtifactTool;

Parameters

Parameter	Type	Description
raw	RawArtifactTool	Raw tool input validated against ArtifactTool.schema.

Returns

ArtifactTool

Throws

@nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE when raw does not satisfy ArtifactTool.schema (most commonly, when artifactConstructor is supplied — it is explicitly forbidden on this class) or when the base @nhtio/adk!Tool constructor rejects the input for any reason.

Overrides

Tool.constructor

Properties

Property	Modifier	Type	Description	Overrides	Inherited from
artifactConstructor	readonly	| ArtifactConstructorResolver<SpooledArtifact> | undefined	-	-	Tool.artifactConstructor
description	readonly	string	-	-	Tool.description
ephemeral	readonly	boolean	-	-	Tool.ephemeral
inputSchema	readonly	Schema	-	-	Tool.inputSchema
meta	readonly	Registry	-	-	Tool.meta
name	readonly	string	-	-	Tool.name
onCollision	readonly	"keep" | "replace" | "throw"	-	-	Tool.onCollision
trusted	readonly	boolean	-	-	Tool.trusted
schema	static	ObjectSchema<RawTool<SpooledArtifact>>	Validator schema that accepts a RawArtifactTool object. Remarks Differs from @nhtio/adk!Tool.schema by forbidding artifactConstructor — wrapping is exactly the thing this class opts out of. Typed identically to @nhtio/adk!Tool.schema so the subclass relationship class ArtifactTool extends Tool remains structurally sound; the runtime validation rules still differ as declared by rawArtifactToolSchema.	Tool.schema	-

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.

Inherited from

Tool.describe

---

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.

Inherited from

Tool.executor

---

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.

Inherited from

Tool.validate

---

isArtifactTool()

static isArtifactTool(value: unknown): value is ArtifactTool;

Returns true if value is an ArtifactTool instance.

Parameters

Parameter	Type	Description
value	unknown	The value to test.

Returns

value is ArtifactTool

true when value is an ArtifactTool instance.

Remarks

Uses @nhtio/adk!isInstanceOf for cross-realm safety — instanceof would fail for instances created in a different module copy or VM context.

---

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.

Inherited from

Tool.isTool