---
title: Tool
description: Tool protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Tool Category

Classifies the tool by its operational domain.

<Callout type="info">
**Source:** `packages/spec/src/ai/tool.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { Tool, ToolCategory } from '@objectstack/spec/ai';
import type { Tool, ToolCategory } from '@objectstack/spec/ai';

// Validate data
const result = Tool.parse(data);
```

---

## Tool

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Tool unique identifier (snake_case) |
| **label** | `string` | ✅ | Tool display name |
| **description** | `string` | ✅ | Tool description for LLM function calling |
| **category** | `Enum<'data' \| 'action' \| 'flow' \| 'integration' \| 'vector_search' \| 'analytics' \| 'utility'>` | optional | Tool category for grouping and filtering |
| **parameters** | `Record<string, any>` | ✅ | JSON Schema for tool parameters |
| **outputSchema** | `Record<string, any>` | optional | JSON Schema for tool output |
| **objectName** | `string` | optional | Target object name (snake_case) |
| **requiresConfirmation** | `boolean` | ✅ | Require user confirmation before execution |
| **permissions** | `string[]` | optional | Required permissions or roles |
| **active** | `boolean` | ✅ | Whether the tool is enabled |
| **builtIn** | `boolean` | ✅ | Platform built-in tool flag |
| **protection** | `Object` | optional | Package author protection block — lock policy for this tool. |
| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact | package | env-forced). |
| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package | org | env-forced). |
| **_packageId** | `string` | optional | Owning package machine id. |
| **_packageVersion** | `string` | optional | Owning package version. |
| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |


---

## ToolCategory

Tool operational category

### Allowed Values

* `data`
* `action`
* `flow`
* `integration`
* `vector_search`
* `analytics`
* `utility`


---

