Tool

The `Tool` entity.

Definition

TypeScript

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.