Model tool schema inventory

This page defines the versioning policy for Holon's model-facing built-in tool surface. The machine-readable inventory is checked in as model-tool-schema-inventory.json.

• Primary source: src/tool/tools/mod.rs builtin_tool_definitions() and the typed Rust argument structs deriving schemars::JsonSchema.
• Generated inventory: holon::tool::model_tool_schema_inventory().
• Drift check: make snapshots-check.
• Current status: pre-1.0 baseline. Treat stable labels as the intended compatibility boundary for the current track, not as a final 1.0 promise.

Inventory contents

Each built-in tool entry records:

• tool name
• capability family
• stability level
• model-facing input schema
• freeform grammar, when the tool accepts non-JSON input
• result envelope family and model rendering contract
• a typed success-result JSON Schema when that stable result surface is in the current coverage set
• related HTTP or CLI surfaces when commands wrap tool or runtime APIs
• model-visible tool description

The version 2 inventory currently covers result schemas for CreateTimer, ListTimers, GetTimer, CancelTimer, Enqueue, CreateAgent, SendAgentMessage, InvokeAgent, ListTasks, TaskStatus, TaskInput, TaskStop, and GenerateImage. Uncovered tools keep their result type name and an explicit null schema; this avoids presenting an inferred or partial shape as a stable contract. Coverage can expand only when the concrete Rust result type derives schemars::JsonSchema.

TaskOutput has been removed from the model tool surface, not merely deprecated. Use TaskStatus, bounded reads of runtime-confirmed command output files, and agent-scoped tail observation; use WaitFor(task_result) for completion and re-entry. The underlying HTTP task-output route and internal result/capture services remain. See the task contract for the boundaries.

Capability families

Each built-in tool belongs to a capability family. The runtime defines six families in src/types.rs (ToolCapabilityFamily):

Family	Description	Example tools
CoreAgent	Core agent operations (state, messaging, memory, work items, scheduling, CLI/config introspection)	SendAgentMessage, MemorySearch, WaitFor, ListWorkItems, AdvisoryDecision
LocalEnvironment	Workspace-local operations	ExecCommand, ApplyPatch, ViewImage, GetWorkspaceState, SwitchWorkspace, CreateWorktree
Web	Public web access	WebFetch, WebSearch
AgentCreation	Agent creation and supervised invocation	CreateAgent, InvokeAgent
AuthorityExpanding	Tools that change workspace authority or destroy registered artifacts	AttachWorkspace, DetachWorkspace, RemoveWorktree
ExternalTrigger	External event ingress	CreateExternalTrigger, CancelExternalTrigger

Stability levels

Level	Meaning
stable	Name, input schema, result envelope family, and documented model rendering are intended to be compatibility-preserving.
experimental	Surface is available but may change while the runtime contract is still settling.
deprecated	Surface remains for compatibility but should not be introduced into new workflows.

Naming policy

Holon-native built-in tool names use PascalCase with action-first names. Use List* for collection reads, Get* for single-resource or snapshot reads, and explicit verbs such as Send*, Stop*, Create*, or Update* for control or mutation. Legacy aliases may remain accepted by the dispatcher during a migration window, but the checked-in inventory advertises the canonical model-facing name.

Versioning policy

The top-level version field versions the inventory format, not every tool schema independently.

• Increment version when the inventory file shape changes in a way that readers must handle differently.
• Do not increment version for ordinary tool additions, removals, input-schema changes, description changes, or stability-label changes; those are contract changes inside the same inventory format and are reviewed through the snapshot diff.
• Preserve the Rust definitions as the source of truth. Intentional changes should update Rust first, then refresh the checked-in inventory.

Refresh workflow

make snapshots-refresh
make snapshots-check