Skip to main content
Save a configured tool as a named preset and evolve it across versions. A preset is a versioned, named wrap of a tool. It bakes some of a base tool’s arguments as fixed constants and exposes the rest under a new name. Every preset is versioned — it rides the platform’s versioning spine, so every save appends a version, one version is active, and you can roll back. A preset is always a durable, store-backed record. A preset body is small — a base tool and the fields to bake:
examples/presets/minimal_preset.yaml

​
Create a preset

Name the base tool, a --description (the preset tool’s LLM-facing docstring — required and non-empty on every create path), and the fixed kwargs to bake. The baked keys are removed from the exposed schema; the remaining arguments keep the base tool’s real typed schema. Create writes the durable store row and then registers the live tool.
List presets and read one back:
To check a draft before committing it — the same pre-write validation the create route runs, but without writing — dry-run it with validate:

​
Save a new version

Save a new version when the configuration changes. Omitted fields carry forward from the active version; --extensions '[]' sends the explicit clear sentinel. description is editable per version — pass --description to set new text, or omit it to carry the active one forward (it can never go empty); a rollback restores the older version’s description along with the rest of its body.
Inspect the history and one version:

​
Roll back

Make a prior version active again. Rollback appends a new version pointing at the target body — it never rewrites history.

​
Tag a version

set-version-tags labels an immutable version body — a per-version marker like stable or reviewed — without rebinding the tool. Passing no tags clears them to [].
These per-version tags are the only tags a preset record carries. A preset has no record-level tags, folder, or display name of its own; that organizational metadata — a display label, a folder, user tags, and visibility — lives in the tool-organization overlay, keyed by the preset’s tool name and managed with tai tool-meta, exactly as it is for any other tool.

​
Rename a preset

A preset’s name is its live tool name, so renaming it rebinds the tool — the new name binds before the old is torn down. Rename integrity is enforced atomically at one gate: a rename blocks with a 409 listing every holder of the name until you update them. That list is the full union — the other presets that compose this one (their authored-agent specs name it as a tool) plus every behavioral holder that wires against the name (a schedule firing it, a hook or conversation route targeting it, a tool-extensions entry, a parked interaction’s resume continuation, or a plugin-held reference). Display metadata is not a holder: the tool-organization overlay follows the name across the rename. Preflight with referees, then rename:
The versioning spine is one mechanism, shared by many kinds. Presets, access-control policies, and authored agents all ride it — append-only versions, an active pointer, rollback, per-version tags, and rename over an opaque body.
The full subcommand set — including validate, referees, set-version-tags, and rename:
examples/presets/presets_help.sh

​
See also