---
title: Tools API
description: Generated public TypeScript reference for @relkit/tools.
search:
  exclude: true
sidebar:
  icon: braces
---

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineTool](/docs/api/tools#definetool)

For configuration and examples, read [tools](/docs/modules/ai/tools), [organization](/docs/modules/service/organization), [ai](/docs/modules/ai).

For a complete workflow, follow [build an offline agent](/guides/ai/build-an-offline-agent).

## Public imports

- `@relkit/tools` — 55 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                          | Kind  | Import from     | Example                                                                      |
| -------------------------------------------------------------------------------------------- | ----- | --------------- | ---------------------------------------------------------------------------- |
| [assertToolDescriptor](/docs/api/tools#asserttooldescriptor)                                 | Value | `@relkit/tools` | [API example](/docs/api/tools#asserttooldescriptor)                          |
| [assertToolDescriptorEffect](/docs/api/tools#asserttooldescriptoreffect)                     | Value | `@relkit/tools` | [API example](/docs/api/tools#asserttooldescriptoreffect)                    |
| [createToolRuntime](/docs/api/tools#createtoolruntime)                                       | Value | `@relkit/tools` | [API example](/docs/api/tools#createtoolruntime)                             |
| [createToolRuntimeEffect](/docs/api/tools#createtoolruntimeeffect)                           | Value | `@relkit/tools` | [API example](/docs/api/tools#createtoolruntimeeffect)                       |
| [defineTool](/docs/api/tools#definetool)                                                     | Value | `@relkit/tools` | [API example](/docs/api/tools#definetool)                                    |
| [defineToolEffect](/docs/api/tools#definetooleffect)                                         | Value | `@relkit/tools` | [API example](/docs/api/tools#definetooleffect)                              |
| [DefineToolOptions](/docs/api/tools#definetooloptions-interface)                             | Type  | `@relkit/tools` | [API example](/docs/api/tools#definetooloptions-interface)                   |
| [invokeTool](/docs/api/tools#invoketool)                                                     | Value | `@relkit/tools` | [API example](/docs/api/tools#invoketool)                                    |
| [invokeToolEffect](/docs/api/tools#invoketooleffect)                                         | Value | `@relkit/tools` | [API example](/docs/api/tools#invoketooleffect)                              |
| [isToolDescriptor](/docs/api/tools#istooldescriptor)                                         | Value | `@relkit/tools` | [API example](/docs/api/tools#istooldescriptor)                              |
| [isToolDescriptorEffect](/docs/api/tools#istooldescriptoreffect)                             | Value | `@relkit/tools` | [API example](/docs/api/tools#istooldescriptoreffect)                        |
| [isToolRef](/docs/api/tools#istoolref)                                                       | Value | `@relkit/tools` | [API example](/docs/api/tools#istoolref)                                     |
| [isToolRefEffect](/docs/api/tools#istoolrefeffect)                                           | Value | `@relkit/tools` | [API example](/docs/api/tools#istoolrefeffect)                               |
| [observeTool](/docs/api/tools#observetool-1)                                                 | Value | `@relkit/tools` | [API example](/docs/api/tools#observetool-1)                                 |
| [ResolvedToolTarget](/docs/api/tools#resolvedtooltarget-interface)                           | Type  | `@relkit/tools` | [API example](/docs/api/tools#resolvedtooltarget-interface)                  |
| [resolveToolTarget](/docs/api/tools#resolvetooltarget)                                       | Value | `@relkit/tools` | [API example](/docs/api/tools#resolvetooltarget)                             |
| [resolveToolTargetEffect](/docs/api/tools#resolvetooltargeteffect)                           | Value | `@relkit/tools` | [API example](/docs/api/tools#resolvetooltargeteffect)                       |
| [ToolAllowlistEntry](/docs/api/tools#toolallowlistentry-type-alias)                          | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolallowlistentry-type-alias)                 |
| [ToolApproval](/docs/api/tools#toolapproval-type-alias)                                      | Type  | `@relkit/tools` | [Module example](/docs/modules/ai/tools)                                     |
| [ToolApprovalDecision](/docs/api/tools#toolapprovaldecision-type-alias)                      | Type  | `@relkit/tools` | [Module example](/docs/modules/ai/tools)                                     |
| [ToolApprovalDeniedError](/docs/api/functions#functiontoolapprovaldeniederror-class)         | Value | `@relkit/tools` | [API example](/docs/api/functions#functiontoolapprovaldeniederror-class)     |
| [ToolApprovalRequest](/docs/api/tools#toolapprovalrequest-type-alias)                        | Type  | `@relkit/tools` | [Module example](/docs/modules/ai/tools)                                     |
| [ToolApprovalRequiredError](/docs/api/functions#functiontoolapprovalrequirederror-class)     | Value | `@relkit/tools` | [API example](/docs/api/functions#functiontoolapprovalrequirederror-class)   |
| [ToolApprovalResolver](/docs/api/tools#toolapprovalresolver-type-alias)                      | Type  | `@relkit/tools` | [Module example](/docs/modules/ai/tools)                                     |
| [ToolArgumentsFailure](/docs/api/tools#toolargumentsfailure-class)                           | Value | `@relkit/tools` | [API example](/docs/api/tools#toolargumentsfailure-class)                    |
| [ToolArgumentValidationError](/docs/api/functions#functiontoolargumentvalidationerror-class) | Value | `@relkit/tools` | [API example](/docs/api/functions#functiontoolargumentvalidationerror-class) |
| [ToolCancelledFailure](/docs/api/tools#toolcancelledfailure-class)                           | Value | `@relkit/tools` | [API example](/docs/api/tools#toolcancelledfailure-class)                    |
| [ToolDescriptor](/docs/api/tools#tooldescriptor-type-alias)                                  | Type  | `@relkit/tools` | [API example](/docs/api/tools#tooldescriptor-type-alias)                     |
| [ToolEffectOptions](/docs/api/tools#tooleffectoptions-type-alias)                            | Type  | `@relkit/tools` | [API example](/docs/api/tools#tooleffectoptions-type-alias)                  |
| [ToolEngine](/docs/api/tools#toolengine-interface)                                           | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolengine-interface)                          |
| [ToolEngineFailure](/docs/api/tools#toolenginefailure-class)                                 | Value | `@relkit/tools` | [API example](/docs/api/tools#toolenginefailure-class)                       |
| [ToolEngineInvocation](/docs/api/tools#toolengineinvocation-interface)                       | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolengineinvocation-interface)                |
| [ToolEngineLive](/docs/api/tools#toolenginelive)                                             | Value | `@relkit/tools` | [API example](/docs/api/tools#toolenginelive)                                |
| [ToolEngineLiveEffect](/docs/api/tools#toolengineliveeffect)                                 | Value | `@relkit/tools` | [API example](/docs/api/tools#toolengineliveeffect)                          |
| [ToolEngineService](/docs/api/tools#toolengineservice-class)                                 | Value | `@relkit/tools` | [API example](/docs/api/tools#toolengineservice-class)                       |
| [ToolInvocationContext](/docs/api/tools#toolinvocationcontext-interface)                     | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolinvocationcontext-interface)               |
| [ToolInvocationRequest](/docs/api/tools#toolinvocationrequest-interface)                     | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolinvocationrequest-interface)               |
| [ToolInvokeOptions](/docs/api/tools#toolinvokeoptions-type-alias)                            | Type  | `@relkit/tools` | [Module example](/docs/modules/ai/tools)                                     |
| [ToolNotAllowedError](/docs/api/tools#toolnotallowederror-class)                             | Value | `@relkit/tools` | [API example](/docs/api/tools#toolnotallowederror-class)                     |
| [ToolNotAllowedFailure](/docs/api/tools#toolnotallowedfailure-class)                         | Value | `@relkit/tools` | [API example](/docs/api/tools#toolnotallowedfailure-class)                   |
| [ToolOperation](/docs/api/tools#tooloperation-type-alias)                                    | Type  | `@relkit/tools` | [API example](/docs/api/tools#tooloperation-type-alias)                      |
| [ToolOperationCancelledError](/docs/api/functions#functiontooloperationcancellederror-class) | Value | `@relkit/tools` | [API example](/docs/api/functions#functiontooloperationcancellederror-class) |
| [ToolOperationFailure](/docs/api/tools#tooloperationfailure-class)                           | Value | `@relkit/tools` | [API example](/docs/api/tools#tooloperationfailure-class)                    |
| [ToolRef](/docs/api/tools#toolref-interface)                                                 | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolref-interface)                             |
| [ToolRefAny](/docs/api/tools#toolrefany-type-alias)                                          | Type  | `@relkit/tools` | [Module example](/docs/modules/ai/tools)                                     |
| [ToolRuntime](/docs/api/tools#toolruntime-interface)                                         | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolruntime-interface)                         |
| [ToolRuntimeOptions](/docs/api/tools#toolruntimeoptions-interface)                           | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolruntimeoptions-interface)                  |
| [ToolSideEffect](/docs/api/tools#toolsideeffect-type-alias)                                  | Type  | `@relkit/tools` | [Module example](/docs/modules/ai/tools)                                     |
| [ToolSource](/docs/api/tools#toolsource-type-alias)                                          | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolsource-type-alias)                         |
| [ToolTarget](/docs/api/tools#tooltarget-type-alias)                                          | Type  | `@relkit/tools` | [API example](/docs/api/tools#tooltarget-type-alias)                         |
| [ToolTelemetry](/docs/api/tools#tooltelemetry-class)                                         | Value | `@relkit/tools` | [API example](/docs/api/tools#tooltelemetry-class)                           |
| [ToolTelemetryLive](/docs/api/tools#tooltelemetrylive-1)                                     | Value | `@relkit/tools` | [API example](/docs/api/tools#tooltelemetrylive-1)                           |
| [ToolTelemetryService](/docs/api/tools#tooltelemetryservice-interface)                       | Type  | `@relkit/tools` | [Module example](/docs/modules/ai/tools)                                     |
| [ToolUnknownError](/docs/api/tools#toolunknownerror-class)                                   | Value | `@relkit/tools` | [API example](/docs/api/tools#toolunknownerror-class)                        |
| [ToolUnknownFailure](/docs/api/tools#toolunknownfailure-class)                               | Value | `@relkit/tools` | [API example](/docs/api/tools#toolunknownfailure-class)                      |

## `define-tool-predicates.ts`

### assertToolDescriptor

Asserts a tool descriptor.

**Throws**

TypeError when the value is not a tool descriptor.

**Example**

```ts
assertToolDescriptor(value);
```

**Signature**

```ts
declare const assertToolDescriptor: (value: unknown) => asserts value is ToolDescriptor<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-predicates.ts#L78)

### assertToolDescriptorEffect

Asserts a tool descriptor through Effect.

**Example**

```ts
Effect.runSync(assertToolDescriptorEffect(tool));
```

**Signature**

```ts
declare const assertToolDescriptorEffect: (
  value: unknown,
) => Effect.Effect<ToolDescriptor<string>, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-predicates.ts#L54)

### isToolDescriptor

Checks a descriptor.

**Example**

```ts
if (isToolDescriptor(value)) await value.invoke({});
```

**Signature**

```ts
declare const isToolDescriptor: (value: unknown) => value is ToolDescriptor<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-predicates.ts#L45)

### isToolDescriptorEffect

Checks a descriptor through Effect.

**Example**

```ts
Effect.runSync(isToolDescriptorEffect(tool));
```

**Signature**

```ts
declare const isToolDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-predicates.ts#L19)

### isToolRef

Checks a tool reference.

**Example**

```ts
isToolRef({ ref: { kind: "tool", id: "orders.lookup" } });
```

**Signature**

```ts
declare const isToolRef: (value: unknown) => value is ToolRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-predicates.ts#L102)

### isToolRefEffect

Checks a tool reference through Effect.

**Example**

```ts
Effect.runSync(isToolRefEffect({ ref: { kind: "tool", id: "orders.lookup" } }));
```

**Signature**

```ts
declare const isToolRefEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-predicates.ts#L87)

## `define-tool-validation.ts`

### copyFunctionTarget

Copies a validated function target.

**Throws**

TypeError when the target is malformed.

**Example**

```ts
copyFunctionTarget(target);
```

**Signature**

```ts
declare const copyFunctionTarget: <Target extends FunctionRefAny>(
  target: Target,
) => FunctionToolTarget<Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L75)

### copyFunctionTargetEffect

Copies and freezes a function target through Effect.

**Example**

```ts
Effect.runSync(copyFunctionTargetEffect(target));
```

**Signature**

```ts
declare const copyFunctionTargetEffect: <Target extends FunctionRefAny>(
  target: Target,
) => Effect.Effect<FunctionToolTarget<Target>, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L36)

### hasOwn

**Signature**

```ts
declare const hasOwn: (value: object, key: PropertyKey) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L15)

### hasOwnEffect

**Signature**

```ts
declare const hasOwnEffect: (
  value: object,
  key: PropertyKey,
) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L16)

### isFunctionTarget

**Signature**

```ts
declare const isFunctionTarget: (
  value: unknown,
) => value is import("@relkit/functions").FunctionRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L17)

### isFunctionTargetEffect

**Signature**

```ts
declare const isFunctionTargetEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L18)

### isNonEmptyString

**Signature**

```ts
declare const isNonEmptyString: (value: unknown) => value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L19)

### isNonEmptyStringEffect

**Signature**

```ts
declare const isNonEmptyStringEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L20)

### isPositiveInteger

**Signature**

```ts
declare const isPositiveInteger: (value: unknown) => value is number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L21)

### isPositiveIntegerEffect

**Signature**

```ts
declare const isPositiveIntegerEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L22)

### isRecord

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<PropertyKey, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L23)

### isRecordEffect

**Signature**

```ts
declare const isRecordEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L24)

### isToolApproval

**Signature**

```ts
declare const isToolApproval: (
  value: unknown,
) => value is import("./define-tool.types.js").ToolApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L25)

### isToolApprovalEffect

**Signature**

```ts
declare const isToolApprovalEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L26)

### isToolSideEffect

**Signature**

```ts
declare const isToolSideEffect: (
  value: unknown,
) => value is import("./define-tool.types.js").ToolSideEffect;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L27)

### isToolSideEffectEffect

**Signature**

```ts
declare const isToolSideEffectEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L28)

### positiveInteger

Asserts a safe positive integer.

**Throws**

TypeError when the value is invalid.

**Example**

```ts
positiveInteger(5, "timeoutMs");
```

**Signature**

```ts
declare const positiveInteger: (value: unknown, name: string) => asserts value is number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L180)

### positiveIntegerEffect

Requires a safe positive integer through Effect.

**Example**

```ts
Effect.runSync(positiveIntegerEffect(5, "timeoutMs"));
```

**Signature**

```ts
declare const positiveIntegerEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<number, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L162)

### requiredText

Requires nonempty trimmed text.

**Throws**

TypeError when the value is empty.

**Example**

```ts
requiredText(" read ", "description");
```

**Signature**

```ts
declare const requiredText: (value: unknown, name: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L152)

### requiredTextEffect

Requires nonempty trimmed text through Effect.

**Example**

```ts
Effect.runSync(requiredTextEffect(" read ", "description"));
```

**Signature**

```ts
declare const requiredTextEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<string, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L137)

### validateApproval

Validates a tool approval policy.

**Throws**

TypeError when the policy is unknown.

**Example**

```ts
validateApproval("never");
```

**Signature**

```ts
declare const validateApproval: (value: unknown) => ToolApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L127)

### validateApprovalEffect

Validates a tool approval policy through Effect.

**Example**

```ts
Effect.runSync(validateApprovalEffect("never"));
```

**Signature**

```ts
declare const validateApprovalEffect: (
  value: unknown,
) => Effect.Effect<FunctionToolApproval, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L111)

### validateSideEffect

Validates a tool side-effect policy.

**Throws**

TypeError when the policy is unknown.

**Example**

```ts
validateSideEffect("read");
```

**Signature**

```ts
declare const validateSideEffect: (value: unknown) => ToolSideEffect;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L102)

### validateSideEffectEffect

Validates a tool side-effect policy through Effect.

**Example**

```ts
Effect.runSync(validateSideEffectEffect("read"));
```

**Signature**

```ts
declare const validateSideEffectEffect: (
  value: unknown,
) => Effect.Effect<FunctionToolSideEffect, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L86)

## `define-tool.ts`

### defineTool

Defines a frozen, handler-free tool view over one function.

**Throws**

TypeError for malformed target, metadata, or ID.

**Example**

```ts
import { defineFunction } from "@relkit/functions";
import { z } from "@relkit/schema";
import { defineTool } from "@relkit/tools";
const lookup = defineFunction({
  id: "orders.lookup",
  input: z.string(),
  output: z.string(),
  handler: (id) => id,
});
const tool = defineTool({
  id: "orders.lookup-tool",
  target: lookup,
  description: "Read order",
  sideEffect: "read",
  approval: "never",
});
```

**Signature**

```ts
declare const defineTool: <const Id extends string, const Target extends FunctionRefAny>(
  options: DefineToolOptions<Id, Target>,
) => ToolDescriptor<Id, Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L137)

Since v0.1.0

### "./define-tool.types.js" (namespace export)

Re-exports all named exports from the "./define-tool.types.js" module.

**Signature**

```ts
export * from "./define-tool.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L29)

### ToolApprovalDeniedError

**Signature**

```ts
declare const ToolApprovalDeniedError: typeof FunctionToolApprovalDeniedError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L39)

### ToolApprovalRequiredError

**Signature**

```ts
declare const ToolApprovalRequiredError: typeof FunctionToolApprovalRequiredError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L40)

### ToolArgumentValidationError

**Signature**

```ts
declare const ToolArgumentValidationError: typeof FunctionToolArgumentValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L41)

### ToolOperationCancelledError

**Signature**

```ts
declare const ToolOperationCancelledError: typeof FunctionToolOperationCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L42)

### assertToolDescriptor

**Signature**

```ts
declare const assertToolDescriptor: (value: unknown) => asserts value is ToolDescriptor<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L31)

### assertToolDescriptorEffect

**Signature**

```ts
declare const assertToolDescriptorEffect: (
  value: unknown,
) => Effect.Effect<ToolDescriptor<string>, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L32)

### defineToolEffect

Defines a frozen, handler-free tool view through Effect.

**Example**

```ts
Effect.runSync(
  defineToolEffect({
    id: "orders.lookup",
    target,
    description: "Read order",
    sideEffect: "read",
    approval: "never",
  }),
);
```

**Signature**

```ts
declare const defineToolEffect: <const Id extends string, const Target extends FunctionRefAny>(
  options: DefineToolOptions<Id, Target>,
) => Effect.Effect<ToolDescriptor<Id, Target>, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L50)

### isToolDescriptor

**Signature**

```ts
declare const isToolDescriptor: (value: unknown) => value is ToolDescriptor<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L33)

### isToolDescriptorEffect

**Signature**

```ts
declare const isToolDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L34)

### isToolRef

**Signature**

```ts
declare const isToolRef: (value: unknown) => value is ToolRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L35)

### isToolRefEffect

**Signature**

```ts
declare const isToolRefEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L36)

## `define-tool.types.ts`

### DefineToolOptions (interface)

Authoring options for a handler-free tool view.

**Example**

```ts
const options: DefineToolOptions<"orders.lookup", typeof target> = {
  id: "orders.lookup",
  target,
  description: "Read an order",
  sideEffect: "read",
  approval: "never",
};
```

**Signature**

```ts
export interface DefineToolOptions<
  Id extends string,
  Target extends FunctionRefAny,
> extends FunctionToolMetadata {
  readonly id?: Id;
  readonly target: Target;
  readonly onBefore?: import("@relkit/functions").FunctionToolHook<
    import("@relkit/schema").InferInput<Target["input"]>
  >;
  readonly onAfter?: import("@relkit/functions").FunctionToolHook<
    import("@relkit/schema").InferOutput<Target["output"]>
  >;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L51)

### ToolApproval (type alias)

Approval policy inherited from a function tool.

**Signature**

```ts
type ToolApproval = FunctionToolApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L17)

### ToolApprovalDecision (type alias)

Decision returned by a tool approval resolver.

**Signature**

```ts
type ToolApprovalDecision = FunctionToolApprovalDecision;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L19)

### ToolApprovalRequest (type alias)

Request passed to a tool approval resolver.

**Signature**

```ts
type ToolApprovalRequest = FunctionToolApprovalRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L21)

### ToolApprovalResolver (type alias)

Resolver for tool approval requests.

**Signature**

```ts
type ToolApprovalResolver = FunctionToolApprovalResolver;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L23)

### ToolDescriptor (type alias)

Frozen, handler-free tool descriptor.

**Example**

```ts
const descriptor: ToolDescriptor<"orders.lookup.tool"> = defineTool(options);
```

**Signature**

```ts
type ToolDescriptor<
  Id extends string,
  Target extends FunctionRefAny = FunctionRefAny,
> = FunctionToolDescriptor<Id, Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L43)

### ToolInvokeOptions (type alias)

Options for invoking the function view of a tool.

**Signature**

```ts
type ToolInvokeOptions = FunctionToolInvokeOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L25)

### ToolRef (interface)

Stable reference to a tool descriptor.

**Example**

```ts
const ref: ToolRef<"orders.lookup"> = { ref: { kind: "tool", id: "orders.lookup" } };
```

**Signature**

```ts
export interface ToolRef<Id extends string = string> {
  readonly ref: { readonly kind: "tool"; readonly id: Id };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L30)

### ToolRefAny (type alias)

Any stable tool reference.

**Signature**

```ts
type ToolRefAny = ToolRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L35)

### ToolSideEffect (type alias)

Effect policy inherited from a function tool.

**Signature**

```ts
type ToolSideEffect = FunctionToolSideEffect;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L15)

### ToolTarget (type alias)

Validated function target copied into a tool.

**Example**

```ts
const copied: ToolTarget<typeof target> = copyFunctionTarget(target);
```

**Signature**

```ts
type ToolTarget<Target extends FunctionRefAny> = FunctionToolTarget<Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L39)

## `index.ts`

### "./define-tool.js" (namespace export)

Re-exports all named exports from the "./define-tool.js" module.

**Signature**

```ts
export * from "./define-tool.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/index.ts#L1)

### "./runtime.js" (namespace export)

Re-exports all named exports from the "./runtime.js" module.

**Signature**

```ts
export * from "./runtime.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/index.ts#L2)

### ToolOperation

**Signature**

```ts
declare const ToolOperation: ToolOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/index.ts#L9)

### ToolOperationFailure

**Signature**

```ts
declare const ToolOperationFailure: typeof ToolOperationFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/index.ts#L4)

### ToolTelemetry

**Signature**

```ts
declare const ToolTelemetry: typeof ToolTelemetry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/index.ts#L5)

### ToolTelemetryLive

**Signature**

```ts
declare const ToolTelemetryLive: Layer<ToolTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/index.ts#L6)

### ToolTelemetryService

**Signature**

```ts
declare const ToolTelemetryService: ToolTelemetryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/index.ts#L9)

### observeTool

**Signature**

```ts
declare const observeTool: <A, E, R>(
  operation: ToolOperation,
  effect: Effect<A, E, R>,
) => Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/index.ts#L7)

## `runtime-engine.ts`

### ToolEngineLive

Provides a common engine to an Effect invocation.

**Throws**

Unexpected construction defects.

**Example**

```ts
ToolEngineLive({ invoke: async ({ input }) => input });
```

**Signature**

```ts
declare const ToolEngineLive: (engine: ToolEngine) => Layer.Layer<ToolEngineService, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-engine.ts#L30)

### ToolEngineLiveEffect

Constructs a composable engine Layer through Effect.

**Example**

```ts
Effect.runSync(ToolEngineLiveEffect(engine));
```

**Signature**

```ts
declare const ToolEngineLiveEffect: (
  engine: ToolEngine,
) => Effect.Effect<Layer.Layer<ToolEngineService, never, never>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-engine.ts#L17)

### ToolEngineService (class)

Replaceable engine used by Effect tool invocation.

**Example**

```ts
Effect.provide(invokeToolEffect(request), ToolEngineLive(engine));
```

**Signature**

```ts
declare class ToolEngineService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-engine.ts#L8)

## `runtime-errors.ts`

### ToolArgumentValidationError

**Signature**

```ts
declare const ToolArgumentValidationError: typeof ToolArgumentValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L71)

### ToolArgumentsFailure (class)

Tagged Effect failure for malformed JSON or schema validation.

**Example**

```ts
Effect.catchTag(invokeToolEffect(request), "ToolArgumentsFailure", () => Effect.void);
```

**Signature**

```ts
declare class ToolArgumentsFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L50)

### ToolCancelledFailure (class)

Tagged Effect failure for cancellation before engine dispatch.

**Example**

```ts
Effect.catchTag(invokeToolEffect(request), "ToolCancelledFailure", () => Effect.void);
```

**Signature**

```ts
declare class ToolCancelledFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L58)

### ToolEngineFailure (class)

Tagged Effect failure from the common engine boundary.

**Example**

```ts
Effect.catchTag(invokeToolEffect(request), "ToolEngineFailure", () => Effect.void);
```

**Signature**

```ts
declare class ToolEngineFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L66)

### ToolNotAllowedError (class)

Compatibility error for a registered tool excluded by policy.

**Example**

```ts
throw new ToolNotAllowedError("orders.delete");
```

**Signature**

```ts
declare class ToolNotAllowedError { constructor(readonly toolId: string) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L22)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_TOOL_NOT_ALLOWED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L23)

### ToolNotAllowedFailure (class)

Tagged Effect failure for a tool excluded by the allowlist.

**Example**

```ts
Effect.catchTag(invokeToolEffect(request), "ToolNotAllowedFailure", () => Effect.void);
```

**Signature**

```ts
declare class ToolNotAllowedFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L42)

### ToolOperationCancelledError

**Signature**

```ts
declare const ToolOperationCancelledError: typeof ToolOperationCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L71)

### ToolUnknownError (class)

Compatibility error for a tool ID absent from the registered source.

**Example**

```ts
throw new ToolUnknownError("orders.missing");
```

**Signature**

```ts
declare class ToolUnknownError { constructor(readonly toolId: string) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L10)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_TOOL_UNKNOWN"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L11)

### ToolUnknownFailure (class)

Tagged Effect failure for an unknown registered tool.

**Example**

```ts
Effect.catchTag(invokeToolEffect(request), "ToolUnknownFailure", () => Effect.void);
```

**Signature**

```ts
declare class ToolUnknownFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L34)

## `runtime-input.ts`

### parseToolArgumentsEffect

Parses a model-returned argument value through Effect.

**Example**

```ts
Effect.runSync(parseToolArgumentsEffect('{"id":1}'));
```

**Signature**

```ts
declare const parseToolArgumentsEffect: (
  value: unknown,
) => Effect.Effect<unknown, ToolArgumentsFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-input.ts#L11)

### validateToolArgumentsEffect

Validates tool input through the inherited standard schema.

**Example**

```ts
await Effect.runPromise(validateToolArgumentsEffect(schema, { id: 1 }));
```

**Signature**

```ts
declare const validateToolArgumentsEffect: (
  schema: StandardSchemaV1<unknown, unknown>,
  value: unknown,
) => Effect.Effect<void, ToolArgumentsFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-input.ts#L32)

## `runtime-resolution.ts`

### findToolEffect

Finds a canonical descriptor in any supported collection.

**Example**

```ts
Effect.runSync(findToolEffect([tool], tool.id));
```

**Signature**

```ts
declare const findToolEffect: (
  source: ToolSource,
  id: string,
) => Effect.Effect<any, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-resolution.ts#L61)

### isToolAllowedEffect

Checks a tool's canonical ID against an allowlist.

**Example**

```ts
Effect.runSync(isToolAllowedEffect(tool.id, [tool.id]));
```

**Signature**

```ts
declare const isToolAllowedEffect: (
  id: string,
  allowlist: ReadonlyArray<ToolAllowlistEntry>,
) => Effect.Effect<boolean, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-resolution.ts#L89)

### resolveToolTarget

Resolves a tool's function ID and inherited schemas.

**Throws**

TypeError when the descriptor is invalid.

**Example**

```ts
resolveToolTarget(tool);
```

**Signature**

```ts
declare const resolveToolTarget: (tool: ToolDescriptor<string>) => ResolvedToolTarget;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-resolution.ts#L51)

### resolveToolTargetEffect

Resolves a tool's function ID and inherited schemas through Effect.

**Example**

```ts
Effect.runSync(resolveToolTargetEffect(tool));
```

**Signature**

```ts
declare const resolveToolTargetEffect: (tool: ToolDescriptor<string>) => Effect.Effect<
  Readonly<{
    errors?: ReadonlyArray<ErrorDescriptorAny>;
    functionId: string;
    input: StandardSchemaV1<unknown, unknown>;
    output: StandardSchemaV1<unknown, unknown>;
  }>,
  ToolOperationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-resolution.ts#L14)

## `runtime.ts`

### "./runtime.types.js" (namespace export)

Re-exports all named exports from the "./runtime.types.js" module.

**Signature**

```ts
export * from "./runtime.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L34)

### ToolArgumentValidationError

**Signature**

```ts
declare const ToolArgumentValidationError: typeof FunctionToolArgumentValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L36)

### ToolArgumentsFailure

**Signature**

```ts
declare const ToolArgumentsFailure: typeof ToolArgumentsFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L43)

### ToolCancelledFailure

**Signature**

```ts
declare const ToolCancelledFailure: typeof ToolCancelledFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L42)

### ToolEngineFailure

**Signature**

```ts
declare const ToolEngineFailure: typeof ToolEngineFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L44)

### ToolEngineLive

**Signature**

```ts
declare const ToolEngineLive: (engine: ToolEngine) => Layer<ToolEngineService, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L46)

### ToolEngineLiveEffect

**Signature**

```ts
declare const ToolEngineLiveEffect: (
  engine: ToolEngine,
) => Effect.Effect<Layer<ToolEngineService, never, never>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L46)

### ToolEngineService

**Signature**

```ts
declare const ToolEngineService: typeof ToolEngineService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L46)

### ToolNotAllowedError

**Signature**

```ts
declare const ToolNotAllowedError: typeof ToolNotAllowedError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L39)

### ToolNotAllowedFailure

**Signature**

```ts
declare const ToolNotAllowedFailure: typeof ToolNotAllowedFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L41)

### ToolOperationCancelledError

**Signature**

```ts
declare const ToolOperationCancelledError: typeof ToolOperationCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L37)

### ToolUnknownError

**Signature**

```ts
declare const ToolUnknownError: typeof ToolUnknownError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L38)

### ToolUnknownFailure

**Signature**

```ts
declare const ToolUnknownFailure: typeof ToolUnknownFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L40)

### createToolRuntime

Creates a reusable Promise runtime.

**Throws**

Unexpected defects from runtime construction.

**Example**

```ts
const runtime = createToolRuntime({ tools: [tool], engine });
```

**Signature**

```ts
declare const createToolRuntime: (options: ToolRuntimeOptions) => ToolRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L179)

### createToolRuntimeEffect

Creates a reusable compatibility runtime through Effect.
The allowlist is copied at creation; the caller retains ownership of tools and engine.

**Example**

```ts
Effect.runSync(createToolRuntimeEffect({ tools: [tool], engine }));
```

**Signature**

```ts
declare const createToolRuntimeEffect: (
  options: ToolRuntimeOptions,
) => Effect.Effect<ToolRuntime, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L152)

### invokeTool

Invokes one allowlisted tool through the common engine.

**Throws**

ToolUnknownError, ToolNotAllowedError, argument errors, or engine rejection.

**Example**

```ts
await invokeTool({ tools: [tool], engine, toolId: "orders.lookup", arguments: {} });
```

**Signature**

```ts
declare const invokeTool: (options: ToolRuntimeOptions & ToolEffectOptions) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L142)

### invokeToolEffect

Invokes an allowlisted tool with a replaceable Effect engine service.
Validation finishes before engine dispatch. Cancellation before dispatch
prevents the engine from starting. Interruption and caller cancellation reach
the engine through its invocation signal.

**Example**

```ts
await Effect.runPromise(
  Effect.provide(
    invokeToolEffect({ tools: [tool], toolId: "orders.lookup", arguments: {} }),
    ToolEngineLive(engine),
  ),
);
```

**Signature**

```ts
declare const invokeToolEffect: (
  options: ToolEffectOptions,
) => Effect.Effect<
  unknown,
  | ToolOperationFailure
  | ToolArgumentsFailure
  | ToolUnknownFailure
  | ToolNotAllowedFailure
  | ToolCancelledFailure
  | ToolEngineFailure,
  ToolEngineService
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L57)

### resolveToolTarget

**Signature**

```ts
declare const resolveToolTarget: (tool: ToolDescriptor<string>) => ResolvedToolTarget;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L47)

### resolveToolTargetEffect

**Signature**

```ts
declare const resolveToolTargetEffect: (tool: ToolDescriptor<string>) => Effect.Effect<
  Readonly<{
    errors?: ReadonlyArray<ErrorDescriptorAny>;
    functionId: string;
    input: StandardSchemaV1<unknown, unknown>;
    output: StandardSchemaV1<unknown, unknown>;
  }>,
  ToolOperationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L47)

## `runtime.types.ts`

### ResolvedToolTarget (interface)

Function target and schemas resolved from a tool.

**Example**

```ts
const target: ResolvedToolTarget = resolveToolTarget(tool);
```

**Signature**

```ts
export interface ResolvedToolTarget {
  readonly functionId: string;
  readonly input: StandardSchemaV1;
  readonly output: StandardSchemaV1;
  readonly errors?: readonly ErrorDescriptorAny[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L102)

### ToolAllowlistEntry (type alias)

One allowed tool ID or reference.

**Example**

```ts
const allowed: ToolAllowlistEntry = "orders.lookup.tool";
```

**Signature**

```ts
type ToolAllowlistEntry = string | ToolRefAny | ToolRefAny["ref"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L46)

### ToolEffectOptions (type alias)

Effect invocation input; the engine arrives from ToolEngineService.

**Example**

```ts
const request: ToolEffectOptions = { tools: [tool], toolId: tool.id, arguments: {} };
```

**Signature**

```ts
type ToolEffectOptions = Omit<ToolRuntimeOptions, "engine"> & ToolInvocationRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L60)

### ToolEngine (interface)

Small engine seam that keeps tools independent of the engine package.

**Example**

```ts
const engine: ToolEngine = { invoke: async (request) => request.input };
```

**Signature**

```ts
export interface ToolEngine {
  /** Invoke a validated target through the common engine.
   * @param options - Target schemas, input, and inherited invocation context.
   * @returns The function output or an engine rejection.
   * @example await engine.invoke(invocation);
   */
  readonly invoke: (options: ToolEngineInvocation) => Promise<unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L27)

### ToolEngineInvocation (interface)

Invocation forwarded to the common function engine.

**Example**

```ts
const invocation: ToolEngineInvocation = {
  functionId: "orders.lookup",
  input: {},
  source: "tool",
  inputSchema,
  outputSchema,
};
```

**Signature**

```ts
export interface ToolEngineInvocation {
  readonly functionId: string;
  readonly input: unknown;
  readonly source: "tool";
  readonly inputSchema: StandardSchemaV1;
  readonly outputSchema: StandardSchemaV1;
  readonly errors?: readonly ErrorDescriptorAny[];
  readonly timeoutMs?: number;
  readonly signal?: AbortSignal;
  readonly hooks?: unknown;
  readonly toolHooks?: unknown;
  readonly progressSink?: ProgressSink;
  readonly parent?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L9)

### ToolInvocationContext (interface)

Optional cancellation context for a runtime call.

**Example**

```ts
const context: ToolInvocationContext = { signal: controller.signal };
```

**Signature**

```ts
export interface ToolInvocationContext {
  readonly signal?: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L77)

### ToolInvocationRequest (interface)

Input for one engine-backed tool invocation.

**Example**

```ts
const request: ToolInvocationRequest = { toolId: "orders.lookup", arguments: {} };
```

**Signature**

```ts
export interface ToolInvocationRequest {
  readonly toolId: string;
  /** Parsed JSON or model-returned JSON text. */
  readonly arguments: unknown;
  readonly signal?: AbortSignal;
  readonly hooks?: unknown;
  readonly parent?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L65)

### ToolRuntime (interface)

Reusable Promise compatibility runtime.

**Example**

```ts
await runtime.invoke("orders.lookup", { id: "a" });
```

**Signature**

```ts
export interface ToolRuntime {
  /** Invoke one registered tool.
   * @param toolId - Canonical tool ID.
   * @param arguments_ - Parsed input or JSON text.
   * @param options - Optional cancellation context.
   * @returns Engine output or a rejected compatibility error.
   * @example await runtime.invoke("orders.lookup.tool", { id: "one" });
   */
  readonly invoke: (
    toolId: string,
    arguments_: unknown,
    options?: ToolInvocationContext,
  ) => Promise<unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L84)

### ToolRuntimeOptions (interface)

Runtime dependencies and optional allowlist.

**Example**

```ts
const options: ToolRuntimeOptions = { tools: [tool], engine };
```

**Signature**

```ts
export interface ToolRuntimeOptions {
  readonly tools: ToolSource;
  readonly engine: ToolEngine;
  readonly allowedTools?: readonly ToolAllowlistEntry[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L51)

### ToolSource (type alias)

Supported tool collections.

**Example**

```ts
const tools: ToolSource = [tool];
```

**Signature**

```ts
type ToolSource =
  | readonly ToolDescriptor<string>[]
  | ReadonlyMap<string, ToolDescriptor<string>>
  | Readonly<Record<string, ToolDescriptor<string>>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L39)

## `tool-observability.ts`

### ToolOperation

**Signature**

```ts
declare const ToolOperation: ToolOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L11)

### ToolOperationFailure (class)

Expected tool input or authoring failure with the original adapter error.

**Example**

```ts
Effect.catchTag(defineToolEffect(options), "ToolOperationFailure", () => Effect.void);
```

**Signature**

```ts
declare class ToolOperationFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L16)

### ToolTelemetry (class)

Replaceable telemetry boundary for all tool operations.

**Example**

```ts
Effect.provide(defineToolEffect(options), ToolTelemetryLive);
```

**Signature**

```ts
declare class ToolTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L24)

### ToolTelemetryLive

Live Effect metric and span observer.

**Example**

```ts
Effect.runSync(Effect.provide(Effect.void, ToolTelemetryLive));
```

**Signature**

```ts
declare const ToolTelemetryLive: Layer.Layer<ToolTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L37)

### ToolTelemetryService

**Signature**

```ts
declare const ToolTelemetryService: ToolTelemetryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L11)

### observeTool

Adds bounded operation telemetry while preserving the original channels.

**Example**

```ts
observeTool("is-ref", Effect.succeed(true));
```

**Signature**

```ts
declare const observeTool: <A, E, R>(
  operation: ToolOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L45)

### runToolPromise

Runs a Promise compatibility adapter and restores its original error.

**Throws**

The original input error or an unexpected defect.

**Example**

```ts
await runToolPromise(Effect.succeed(1));
```

**Signature**

```ts
declare const runToolPromise: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L96)

### runToolSync

Runs a synchronous compatibility adapter and restores its original error.

**Throws**

The original input error or an unexpected defect.

**Example**

```ts
runToolSync(Effect.succeed(1));
```

**Signature**

```ts
declare const runToolSync: <A, E>(effect: Effect.Effect<A, E>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L82)

### toolAttempt

Evaluates a step within an already observed operation.

**Example**

```ts
yield * toolAttempt("define", () => descriptor);
```

**Signature**

```ts
declare const toolAttempt: <A>(
  operation: ToolOperation,
  evaluate: () => A,
) => Effect.Effect<A, ToolOperationFailure>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L142)

### toolTry

Captures a marked validation error from a synchronous calculation.

**Example**

```ts
Effect.runSync(toolTry("required-text", () => "ok"));
```

**Signature**

```ts
declare const toolTry: <A>(
  operation: ToolOperation,
  evaluate: () => A,
) => Effect.Effect<A, ToolOperationFailure>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L129)

## `tool-observability.types.ts`

### ToolOperation (type alias)

Fixed names for tool operations; values must never contain user input.

**Example**

```ts
const operation: ToolOperation = "invoke";
```

**Signature**

```ts
type ToolOperation =
  | "define"
  | "is-descriptor"
  | "assert-descriptor"
  | "is-ref"
  | "copy-target"
  | "validate-side-effect"
  | "validate-approval"
  | "is-side-effect"
  | "is-approval"
  | "required-text"
  | "positive-integer"
  | "is-positive-integer"
  | "is-function-target"
  | "is-non-empty-string"
  | "is-record"
  | "has-own"
  | "resolve-target"
  | "engine-layer"
  | "invoke"
  | "create-runtime";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.types.ts#L6)

### ToolTelemetryService (interface)

Replaceable observer used to verify spans and metrics in tests.

**Signature**

```ts
export interface ToolTelemetryService {
  /** Observe an operation without changing its channels.
   * @param operation - Stable, bounded operation name.
   * @param effect - Work to observe.
   * @returns The same success and failure channels.
   * @example telemetry.observe("is-ref", Effect.succeed(true));
   */
  readonly observe: <A, E, R>(
    operation: ToolOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.types.ts#L29)

## `tool-predicates.ts`

### hasOwn

Checks an own property.

**Example**

```ts
hasOwn({ id: 1 }, "id");
```

**Signature**

```ts
declare const hasOwn: (value: object, key: PropertyKey) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L136)

### hasOwnEffect

Checks an own property through Effect.

**Example**

```ts
Effect.runSync(hasOwnEffect({ id: 1 }, "id"));
```

**Signature**

```ts
declare const hasOwnEffect: (
  value: object,
  key: PropertyKey,
) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L123)

### isFunctionTarget

Checks a function target.

**Example**

```ts
isFunctionTarget(target);
```

**Signature**

```ts
declare const isFunctionTarget: (
  value: unknown,
) => value is import("@relkit/functions").FunctionRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L167)

### isFunctionTargetEffect

Checks a function target through Effect.

**Example**

```ts
Effect.runSync(isFunctionTargetEffect(target));
```

**Signature**

```ts
declare const isFunctionTargetEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L145)

### isNonEmptyString

Checks a nonempty string.

**Example**

```ts
isNonEmptyString("hello");
```

**Signature**

```ts
declare const isNonEmptyString: (value: unknown) => value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L92)

### isNonEmptyStringEffect

Checks a nonempty string through Effect.

**Example**

```ts
Effect.runSync(isNonEmptyStringEffect("hello"));
```

**Signature**

```ts
declare const isNonEmptyStringEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L80)

### isPositiveInteger

Checks a safe positive integer.

**Example**

```ts
isPositiveInteger(2);
```

**Signature**

```ts
declare const isPositiveInteger: (value: unknown) => value is number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L71)

### isPositiveIntegerEffect

Checks a safe positive integer through Effect.

**Example**

```ts
Effect.runSync(isPositiveIntegerEffect(2));
```

**Signature**

```ts
declare const isPositiveIntegerEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L59)

### isRecord

Checks a plain non-array object.

**Example**

```ts
isRecord({ id: 1 });
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<PropertyKey, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L113)

### isRecordEffect

Checks a plain non-array object through Effect.

**Example**

```ts
Effect.runSync(isRecordEffect({ id: 1 }));
```

**Signature**

```ts
declare const isRecordEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L101)

### isToolApproval

Checks a tool approval policy.

**Example**

```ts
isToolApproval("never");
```

**Signature**

```ts
declare const isToolApproval: (
  value: unknown,
) => value is import("./define-tool.types.js").ToolApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L48)

### isToolApprovalEffect

Checks a tool approval policy through Effect.

**Example**

```ts
Effect.runSync(isToolApprovalEffect("never"));
```

**Signature**

```ts
declare const isToolApprovalEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L36)

### isToolSideEffect

Checks a tool side-effect policy.

**Example**

```ts
isToolSideEffect("read");
```

**Signature**

```ts
declare const isToolSideEffect: (
  value: unknown,
) => value is import("./define-tool.types.js").ToolSideEffect;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L25)

### isToolSideEffectEffect

Checks a tool side-effect policy through Effect.

**Example**

```ts
Effect.runSync(isToolSideEffectEffect("read"));
```

**Signature**

```ts
declare const isToolSideEffectEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L11)