---
title: "Tool"
description: "The `Tool` entity."
section: "Reference"
group: "Types"
order: 239
---

## Definition

```ts
interface Tool {
  id: string;
  workspaceId: string | null;
  name: string;
  description: string | null;
  target: "server" | "client";
  functionId: string | null;
  functionVersionId: string | null;
  inputSchemaId: string;
  outputSchemaId: string;
  examples: Array<{ args: Record<string, unknown>; result?: unknown }> | null;
  requiresConfirmation: boolean;
  enabled: boolean;
  system: boolean;
  createdBy: string | null;
  runtimeUserId: string | null;
  deletedAt: string | null;
  retentionTier: "short" | "medium" | "long" | "none" | null;
  createdAt: string;
  updatedAt: string;
}
```

## Fields

| Field                  | Type                                                                  | Notes                                                                                                                                                                                                                                         |
| ---------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                   | `string`                                                              | `readonly` `required`                                                                                                                                                                                                                         |
| `workspaceId`          | `string \| null`                                                      | `required` — Workspace that owns this tool; null for system tools.                                                                                                                                                                            |
| `name`                 | `string`                                                              | `required` — LLM-facing name. The model sees this in its tool list. Independent of the underlying function's name so the same function can be rebadged per agent.                                                                             |
| `description`          | `string \| null`                                                      | `required` — When-to-use hint surfaced to the LLM. The single most impactful field for tool-use accuracy.                                                                                                                                     |
| `target`               | `"server" \| "client"`                                                | `required`                                                                                                                                                                                                                                    |
| `functionId`           | `string \| null`                                                      | `required` — Workspace function this tool wraps. Required when `target` is `server`; null for `client` tools.                                                                                                                                 |
| `functionVersionId`    | `string \| null`                                                      | `required` — Pin to a specific function version. When null, the tool follows the function's `defaultVersionId`. Set this for reproducibility / pinned tool surfaces.                                                                          |
| `inputSchemaId`        | `string`                                                              | `required` — Schema authoritatively defining the tool's input contract — what the LLM sees and what dispatch validates.                                                                                                                       |
| `outputSchemaId`       | `string`                                                              | `required` — Schema authoritatively defining the tool's output contract.                                                                                                                                                                      |
| `examples`             | `Array<{ args: Record<string, unknown>; result?: unknown; }> \| null` | `required` — Optional few-shot examples of (args, result) tuples. Injected into the agent prompt to steer the model's tool calls.                                                                                                             |
| `requiresConfirmation` | `boolean`                                                             | `required` — If true, the agent loop pauses for user approval before dispatching the tool. Use for destructive actions.                                                                                                                       |
| `enabled`              | `boolean`                                                             | `required` — If false, the tool is hidden from the LLM even when bound to an agent. Useful for muting a tool without unbinding it.                                                                                                            |
| `system`               | `boolean`                                                             | `required` — True for built-in system tools that cannot be edited.                                                                                                                                                                            |
| `createdBy`            | `string \| null`                                                      | `required` — User who created the tool; null for system tools.                                                                                                                                                                                |
| `runtimeUserId`        | `string \| null`                                                      | `required` — Override the workspace default service user as the runtime caller when this tool's underlying function is invoked. Null = inherit workspace default. Workspace-admin-only to set; target user must be a member of the workspace. |
| `deletedAt`            | `string \| null`                                                      | `required` — ISO-8601 timestamp of soft-delete; null while active. Cleanup worker hard-deletes once `deletedAt + retentionTier.days` passes.                                                                                                  |
| `retentionTier`        | `"short" \| "medium" \| "long" \| "none" \| null`                     | `required` — Retention tier snapshotted at delete time. Null while active.                                                                                                                                                                    |
| `createdAt`            | `string`                                                              | `readonly` `required` — ISO-8601 timestamp of creation.                                                                                                                                                                                       |
| `updatedAt`            | `string`                                                              | `readonly` `required` — ISO-8601 timestamp of the last update.                                                                                                                                                                                |