--- url: 'https://adk.nht.io/api/@nhtio/adk/forge/classes/ArtifactTool.md' description: >- A {@link @nhtio/adk!Tool} subclass whose handler return value is wrapped directly in a {@link @nhtio/adk!Tokenizable} (not a {@link @nhtio/adk!SpooledArtifact}) when it lands on `ToolCall.results`. --- # Class: ArtifactTool Defined in: [lib/classes/artifact\_tool.ts:134](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/artifact_tool.ts#L134) A [@nhtio/adk!Tool](Tool.md) subclass whose handler return value is wrapped directly in a [@nhtio/adk!Tokenizable](../../common/classes/Tokenizable.md) (not a [@nhtio/adk!SpooledArtifact](../../spooled_artifact/classes/SpooledArtifact.md)) 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](Tool.md) 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 `ToolCall`s 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`](Tool.md) ## Constructors ### Constructor ```ts new ArtifactTool(raw: RawArtifactTool): ArtifactTool; ``` Defined in: [lib/classes/artifact\_tool.ts:168](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/artifact_tool.ts#L168) #### Parameters | Parameter | Type | Description | | --------- | ----------------------------------------------------- | ------------------------------------------------------------------------- | | `raw` | [`RawArtifactTool`](../interfaces/RawArtifactTool.md) | Raw tool input validated against [ArtifactTool.schema](#property-schema). | #### Returns `ArtifactTool` #### Throws [@nhtio/adk!E\_INVALID\_INITIAL\_TOOL\_VALUE](../../exceptions/variables/E_INVALID_INITIAL_TOOL_VALUE.md) when `raw` does not satisfy [ArtifactTool.schema](#property-schema) (most commonly, when `artifactConstructor` is supplied — it is explicitly forbidden on this class) or when the base [@nhtio/adk!Tool](Tool.md) constructor rejects the input for any reason. #### Overrides [`Tool`](Tool.md).[`constructor`](Tool.md#constructor) ## Properties | Property | Modifier | Type | Description | Overrides | Inherited from | Defined in | | --------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `artifactConstructor` | `readonly` | | `ArtifactConstructorResolver`<[`SpooledArtifact`](../../spooled_artifact/classes/SpooledArtifact.md)> | `undefined` | - | - | [`Tool`](Tool.md).[`artifactConstructor`](Tool.md#property-artifactconstructor) | [lib/classes/tool.ts:232](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L232) | | `description` | `readonly` | `string` | - | - | [`Tool`](Tool.md).[`description`](Tool.md#property-description) | [lib/classes/tool.ts:230](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L230) | | `ephemeral` | `readonly` | `boolean` | - | - | [`Tool`](Tool.md).[`ephemeral`](Tool.md#property-ephemeral) | [lib/classes/tool.ts:234](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L234) | | `inputSchema` | `readonly` | `Schema` | - | - | [`Tool`](Tool.md).[`inputSchema`](Tool.md#property-inputschema) | [lib/classes/tool.ts:231](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L231) | | `meta` | `readonly` | [`Registry`](../../common/classes/Registry.md) | - | - | [`Tool`](Tool.md).[`meta`](Tool.md#property-meta) | [lib/classes/tool.ts:233](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L233) | | `name` | `readonly` | `string` | - | - | [`Tool`](Tool.md).[`name`](Tool.md#property-name) | [lib/classes/tool.ts:229](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L229) | | `onCollision` | `readonly` | `"keep"` | `"replace"` | `"throw"` | - | - | [`Tool`](Tool.md).[`onCollision`](Tool.md#property-oncollision) | [lib/classes/tool.ts:236](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L236) | | `trusted` | `readonly` | `boolean` | - | - | [`Tool`](Tool.md).[`trusted`](Tool.md#property-trusted) | [lib/classes/tool.ts:235](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L235) | | `schema` | `static` | `ObjectSchema`<[`RawTool`](../interfaces/RawTool.md)<[`SpooledArtifact`](../../spooled_artifact/classes/SpooledArtifact.md)>> | Validator schema that accepts a [RawArtifactTool](../interfaces/RawArtifactTool.md) object. **Remarks** Differs from [@nhtio/adk!Tool.schema](Tool.md#property-schema) by forbidding `artifactConstructor` — wrapping is exactly the thing this class opts out of. Typed identically to [@nhtio/adk!Tool.schema](Tool.md#property-schema) so the subclass relationship `class ArtifactTool extends Tool` remains structurally sound; the runtime validation rules still differ as declared by `rawArtifactToolSchema`. | [`Tool`](Tool.md).[`schema`](Tool.md#property-schema) | - | [lib/classes/artifact\_tool.ts:144](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/artifact_tool.ts#L144) | ## Methods ### describe() ```ts describe(): { description: string; inputSchema: Description; name: string; }; ``` Defined in: [lib/classes/tool.ts:422](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L422) Returns a fully serialisable snapshot of this tool's definition. #### Returns ```ts { 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](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L422) | | `inputSchema` | `Description` | [lib/classes/tool.ts:422](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L422) | | `name` | `string` | [lib/classes/tool.ts:422](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L422) | #### 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`](Tool.md).[`describe`](Tool.md#describe) *** ### executor() ```ts executor(ctx: DispatchContext): (args: unknown) => Promise< | string | Uint8Array | Media | Media[]>; ``` Defined in: [lib/classes/tool.ts:367](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L367) Returns a bound executor function for this tool against the given turn context. #### Parameters | Parameter | Type | Description | | --------- | -------------------------------------------------------------- | ------------------------------------------------------------- | | `ctx` | [`DispatchContext`](../../types/interfaces/DispatchContext.md) | The active turn context. Provides emit functions and turn ID. | #### Returns An async function `(args) => Promise`. (`args`: `unknown`) => `Promise`< | `string` | `Uint8Array`<`ArrayBufferLike`> | [`Media`](../../common/classes/Media.md) | [`Media`](../../common/classes/Media.md)\[]> #### 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](Tool.md#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](../../exceptions/variables/E_TOOL_DOWNSTREAM_ERROR.md) before re-throwing. The handler returns serialised bytes (`string | Uint8Array`) — persistence is the consumer's concern. Use [Tool.artifactConstructor](Tool.md#property-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`](Tool.md).[`executor`](Tool.md#executor) *** ### validate() ```ts validate(args: unknown): Promise; ``` Defined in: [lib/classes/tool.ts:337](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L337) 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](../../exceptions/variables/E_INVALID_TOOL_ARGS.md) — this indicates a programming error in the tool call loop, not a downstream failure. #### Throws [@nhtio/adk!E\_INVALID\_TOOL\_ARGS](../../exceptions/variables/E_INVALID_TOOL_ARGS.md) when `args` does not satisfy the input schema. #### Inherited from [`Tool`](Tool.md).[`validate`](Tool.md#validate) *** ### isArtifactTool() ```ts static isArtifactTool(value: unknown): value is ArtifactTool; ``` Defined in: [lib/classes/artifact\_tool.ts:156](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/artifact_tool.ts#L156) 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](../../guards/functions/isInstanceOf.md) for cross-realm safety — `instanceof` would fail for instances created in a different module copy or VM context. *** ### isTool() ```ts static isTool(value: unknown): value is Tool; ``` Defined in: [lib/classes/tool.ts:225](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L225) Returns `true` if `value` is a [Tool](Tool.md) instance. #### Parameters | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to test. | #### Returns `value is Tool` `true` when `value` is a [Tool](Tool.md) instance. #### Inherited from [`Tool`](Tool.md).[`isTool`](Tool.md#istool)