ObjectStackTool schema — AI Protocol property reference
Tool schemas of the ObjectStack AI Protocol: Tool — each property with its type, default and a TypeScript example.
Source: packages/spec/src/ai/tool.zod.ts
TypeScript Usage
import { ToolSchema } from '@objectstack/spec/ai';
import type { Tool } from '@objectstack/spec/ai';
// Validate data
const result = ToolSchema.parse(data);Tool
AI tool definition. [READ-ONLY PROJECTION — not an execution entry point] Authoring a tool as metadata does NOT make it runnable: this schema has no implementation/handler field and no framework executor loads a metadata-authored tool. The runtime executes a separately-registered AIToolDefinition (cloud @objectstack/service-ai); tool metadata is a one-way projection for Studio/discovery. Do not expect a hand-authored tool to run in the open edition.
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 |
| parameters | Record<string, any> | ✅ | JSON Schema for tool parameters |
| outputSchema | Record<string, any> | optional | [EXPERIMENTAL — not enforced] JSON Schema for tool output; nothing reads it on a tool record — declare it as ai.outputSchema on the action, where the cloud AI runtime validates the action result against it. |
| objectName | string | optional | Target object name (snake_case) |
| protection | { lock: Enum<'none' | 'no-overlay' | 'no-delete' | 'full'>; reason: string; docsUrl?: string } | 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. |
Nested Shape: Tool.protection
| Property | Type | Required | Description |
|---|---|---|---|
| lock | Enum<'none' | 'no-overlay' | 'no-delete' | 'full'> | ✅ | Lock policy — none | no-overlay | no-delete | full. |
| reason | string | ✅ | User-visible reason shown when the lock blocks an action. |
| docsUrl | string | optional | Optional URL the Studio banner links to for more context. |