---
url: 'https://adk.nht.io/api/@nhtio/adk/forge/classes/Tool.md'
description: >-
A tool definition that serves as the single source of truth for a callable
tool: its name, description, input schema, execution handler, and the {@link
@nhtio/adk!SpooledArtifact} subclass that wraps its serialised output.
---
# Class: Tool\
Defined in: [lib/classes/tool.ts:209](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L209)
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](../../spooled_artifact/classes/SpooledArtifact.md) 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](../../exceptions/variables/E_TOOL_DOWNSTREAM_ERROR.md). The handler returns serialised bytes
(`string | Uint8Array`); persistence is the consumer's responsibility.
`artifactConstructor` is the [@nhtio/adk!SpooledArtifact](../../spooled_artifact/classes/SpooledArtifact.md) 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`](ArtifactTool.md)
## Type Parameters
| Type Parameter | Default type | Description |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `A` *extends* [`SpooledArtifact`](../../spooled_artifact/classes/SpooledArtifact.md) | [`SpooledArtifact`](../../spooled_artifact/classes/SpooledArtifact.md) | The [@nhtio/adk!SpooledArtifact](../../spooled_artifact/classes/SpooledArtifact.md) subtype this tool's results should be wrapped in. Defaults to [@nhtio/adk!SpooledArtifact](../../spooled_artifact/classes/SpooledArtifact.md). |
## Constructors
### Constructor
```ts
new Tool(raw: RawTool): Tool;
```
Defined in: [lib/classes/tool.ts:252](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L252)
#### Parameters
| Parameter | Type | Description |
| --------- | -------------------------------------------- | ----------------------------------------------------- |
| `raw` | [`RawTool`](../interfaces/RawTool.md)<`A`> | The raw tool input validated against `rawToolSchema`. |
#### Returns
`Tool`<`A`>
#### Throws
[@nhtio/adk!E\_INVALID\_INITIAL\_TOOL\_VALUE](../../exceptions/variables/E_INVALID_INITIAL_TOOL_VALUE.md) 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](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L232) |
| `description` | `readonly` | `string` | `undefined` | - | [lib/classes/tool.ts:230](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L230) |
| `ephemeral` | `readonly` | `boolean` | `undefined` | - | [lib/classes/tool.ts:234](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L234) |
| `inputSchema` | `readonly` | `Schema` | `undefined` | - | [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) | `undefined` | - | [lib/classes/tool.ts:233](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L233) |
| `name` | `readonly` | `string` | `undefined` | - | [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"` | `undefined` | - | [lib/classes/tool.ts:236](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L236) |
| `trusted` | `readonly` | `boolean` | `undefined` | - | [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)>> | `rawToolSchema` | Validator schema that accepts a [RawTool](../interfaces/RawTool.md) 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](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L217) |
## 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.
***
### 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](#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](#property-artifactconstructor) when wrapping the bytes into a
`ToolCall.results` field.
Pattern mirrors `Middleware.runner()` — call once per turn, reuse the returned function.
***
### 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.
***
### 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 instance.
#### Parameters
| Parameter | Type | Description |
| --------- | --------- | ------------------ |
| `value` | `unknown` | The value to test. |
#### Returns
`value is Tool`
`true` when `value` is a Tool instance.