zclaw Docs | Build Your Own Tool

Mental Model

A user tool stores a short action string. Later, when the model calls that tool, zclaw returns the action text and the model executes it with built-in tools.

1) create_tool(name, description, action)
2) Tool is saved in NVS
3) Model calls tool by name
4) Firmware returns: "Execute this action now: ..."
5) Model performs gpio/memory/cron calls

No dynamic code loading. You are shaping behavior through promptable intent.

Creation Contract

Field	Rule	Notes
`name`	Alphanumeric + underscore only	No spaces or punctuation.
`description`	Short and explicit	Used by model selection logic.
`action`	Concrete imperative text	Should map cleanly to built-in tools.
capacity	Up to 8 user tools	Delete stale tools to free slots.

Authoring Workflow

Pick one job with clear start/end conditions.
Name it by intent: water_plants, prep_night_mode, check_lab_sensor.
Write action text as ordered steps the model can execute.
Create the tool in chat and immediately invoke it with a test prompt.
Adjust wording if the model takes unexpected paths.

Concrete Examples

You: Create a tool named "water_plants".
Description: Water plant zone A.
Action: Set GPIO 5 high, wait 30000 milliseconds, then set GPIO 5 low.

You: Run water_plants
Agent: (calls tool) -> executes gpio_write + delay + gpio_write

You: Create tool "night_shutdown" to prepare lab for night.
Action: Turn GPIO 7 low, remember u_last_shutdown=completed, and set a once schedule in 600 minutes to run morning_startup.

Memory-Driven Tool Creation

Tool creation gets stronger when zclaw already knows your hardware map from memory.

You: Remember that GPIO 5 controls the office lighting.
Agent: Stored as memory key (for example: u_office_lighting_pin=5)

Later...

You: Build a tool to control the lights.
Agent: Creates a tool using the remembered lighting pin instead of asking you to restate wiring.

Pattern: teach wiring once with memory, then create higher-level tools in plain language.

Validation Checklist

Does the action text reference only supported built-in capabilities?
Are durations explicit in milliseconds/minutes (avoid vague words like "later")?
Does it avoid unsafe GPIO pins per your board policy? (The agent will generally prevent this anyway.)
Can the outcome be observed via gpio_read, memory_get, or cron_list?

Versioning and Retirement

Treat tool names like API contracts. If behavior changes meaningfully, create a new name and migrate callers.

# Discover current tools
list_user_tools

# Remove stale tool
delete_user_tool(name="night_shutdown_v1")

Pattern: append a version suffix only when compatibility breaks (_v2, _v3).

Failure Modes To Watch

Overly broad actions that invite hallucinated extra steps.
Tool names that overlap semantically and confuse model choice.
Implicit assumptions about hardware state (pin mode, sensor presence, wiring).
Long multi-domain macros that should be split into smaller tools.