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: cargo test --test tool_schema_inventory_snapshot.
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
related HTTP or CLI surfaces when commands wrap tool or runtime APIs
model-visible tool description

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.

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

cargo test --test tool_schema_inventory_snapshot refresh_tool_schema_inventory_snapshot -- --ignored
cargo test --test tool_schema_inventory_snapshot