--- url: 'https://adk.nht.io/api/@nhtio/adk/forge/interfaces/RawTool.md' description: 'Plain input object supplied to [`Tool`](https://adk.nht.io/api/@nhtio/adk/forge/classes/Tool) at construction time.' --- # Interface: RawTool\ Defined in: [lib/classes/tool.ts:66](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L66) Plain input object supplied to [Tool](../classes/Tool.md) at construction time. ## 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 used to wrap this tool's results when the consumer assembles a `ToolCall.results` field. Defaults to [@nhtio/adk!SpooledArtifact](../../spooled_artifact/classes/SpooledArtifact.md) (plain text). Tools producing JSON output should set this to `SpooledJsonArtifact`; tools producing markdown should set it to `SpooledMarkdownArtifact`; consumers can also pass a custom subclass. | ## Properties | Property | Type | Default value | Description | Defined in | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `artifactConstructor?` | `ArtifactConstructorResolver`<`A`> | `undefined` | Zero-arg resolver returning the [@nhtio/adk!SpooledArtifactConstructor](../type-aliases/SpooledArtifactConstructor.md) the consumer should use when wrapping this tool's serialised output into a `ToolCall.results` field. Optional — when omitted, wrap-sites fall back to [@nhtio/adk!SpooledArtifact](../../spooled_artifact/classes/SpooledArtifact.md) (plain text). **Remarks** Recommended call shape: `artifactConstructor: () => SpooledJsonArtifact`. The closure is the indirection that lets `tool.ts` validate this field without eagerly importing `SpooledArtifact` (which would crash the `tool.ts ↔ spooled_artifact.ts ↔ artifact_tool.ts` module-load cycle). At validate time the schema invokes the resolver and verifies its return value is a `SpooledArtifact`-derived constructor — wrong-shape resolvers throw [@nhtio/adk!E\_INVALID\_INITIAL\_TOOL\_VALUE](../../exceptions/variables/E_INVALID_INITIAL_TOOL_VALUE.md). Wrap-sites (storage batteries, scripted executors) read the constructor via `tool.artifactConstructor?.() ?? SpooledArtifact`. | [lib/classes/tool.ts:91](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L91) | | `description` | `string` | `undefined` | Human-readable description passed to the model to explain what the tool does. | [lib/classes/tool.ts:70](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L70) | | `ephemeral?` | `boolean` | `false` | When `true`, marks this tool as owned by a specific [@nhtio/adk!DispatchContext](../../types/interfaces/DispatchContext.md) so that `ToolRegistry.pruneEphemeral()` will drop it at ctx-completion. **Remarks** The flag is advisory at the `Tool` level — registries decide what to do with it. The canonical producer of ephemeral tools is `SpooledArtifact.forgeTools(ctx)`, which sets this to `true` on every artifact-query tool it emits. | [lib/classes/tool.ts:105](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L105) | | `handler` | [`ToolHandler`](../type-aliases/ToolHandler.md) | `undefined` | Execution function. Not exposed as a public property — invoke via `executor()`. | [lib/classes/tool.ts:74](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L74) | | `inputSchema` | `Schema` | `undefined` | @nhtio/validation schema for the tool's input arguments. Annotate with `.description()`, `.note()`, `.example()` etc. to produce rich LLM tool definitions via `.describe()`. | [lib/classes/tool.ts:72](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L72) | | `meta?` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, `unknown`> | `undefined` | Optional arbitrary metadata for this tool (e.g. RBAC scopes, feature flags). Defaults to `{}`. Stored in a [@nhtio/adk!Registry](../../common/classes/Registry.md) for dot-path access. | [lib/classes/tool.ts:93](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L93) | | `name` | `string` | `undefined` | Unique identifier used in LLM tool definitions. Recommend lowercase snake\_case. | [lib/classes/tool.ts:68](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L68) | | `onCollision?` | `"keep"` | `"replace"` | `"throw"` | `'throw'` | Self-declared merge collision policy. Honoured by `ToolRegistry.merge` (NOT by `ToolRegistry.register`) when this tool collides with another of the same name. **Remarks** - `'throw'` (default): defer to the merge-level `options.onCollision`. If that is also `'throw'`, the merge raises `E_TOOL_ALREADY_REGISTERED`. This matches the default behaviour of `ToolRegistry.register`. - `'replace'`: this tool always wins the collision, regardless of the merge-level option. - `'keep'`: this tool always loses to any previously-registered tool of the same name. Forged artifact-query tools set this to `'replace'` so that merging multiple `Subclass.forgeTools(ctx)` outputs (whose base-method tools overlap by name) resolves silently — the descriptors, snapshot, and handler behaviour are interchangeable across subclasses, so replacement is a behavioural no-op. | [lib/classes/tool.ts:144](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L144) | | `trusted?` | `boolean` | `false` | When `true`, declares that this tool's output should be treated as **trusted developer/user intent** rather than as untrusted third-party text when surfaced to the model. **Remarks** LLM batteries read this flag per call when rendering tool-call results. The default untrusted envelope (e.g. `` in the OpenAI Chat Completions battery) is the secure-by-default treatment for arbitrary tool output. A tool whose output is authored by the user or operator (Q\&A tools surfacing user-authored answers, human-in-the-loop approval gates, feedback-collection tools, configuration tools returning developer-authored constants) sets this to `true` so the LLM battery routes the result through its trusted envelope (`` in the OpenAI Chat Completions battery). Trust is a property of the tool's output, not a property of how a particular battery is wired — putting the flag here means the trust signal travels with the tool wherever it is registered, no per-battery string lists, no name-matching to fail-open on typos. | [lib/classes/tool.ts:125](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/tool.ts#L125) |