zclaw - Field Guide | Tool Surface

Built-In Tools

Group	Tools	Use
GPIO	`gpio_write`, `gpio_read`, `gpio_read_all`, `delay`, `i2c_scan`	Pins, timings, sensor bus checks (including one-call full GPIO state reads).
Memory	`memory_set`, `memory_get`, `memory_list`, `memory_delete`	Persistent user state (`u_*` keys).
Schedules	`cron_set`, `cron_list`, `cron_delete`	Periodic, daily, and one-shot jobs.
Clock	`get_time`, `set_timezone`, `get_timezone`	Timezone-aware schedule behavior.
System	`get_version`, `get_health`, `get_diagnostics`	Firmware version plus quick/scoped runtime diagnostics.
User tools	`create_tool`, `list_user_tools`, `delete_user_tool`	Natural-language macro layer.

Runtime Diagnostics

get_diagnostics extends get_health with scoped checks and optional verbose output.

scope: quick (default) for one-line status.
scope: runtime for uptime + boot/version context.
scope: memory for free/min/largest heap and fragmentation hint.
scope: rates for request counters.
scope: time for sync + timezone.
scope: all for a multi-line summary across categories.
verbose: true includes expanded details.

{"scope":"memory","verbose":true}

Natural-language prompts like “run diagnostics” or “show full diagnostics” should trigger this tool.

Telegram Control Commands

Command	Behavior
`/start`	Shows local command help without calling the LLM.
`/help`	Alias of `/start`; returns local command help without calling the LLM.
`/settings`	Shows local bot status (including paused/active intake state).
`/diag [scope] [verbose]`	Runs local diagnostics without an LLM call (available even when intake is paused).
`/stop`	Pauses inbound message processing (used to stop spam loops).
`/resume`	Re-enables inbound message processing after `/stop`.

Schedule Grammar

cron_set accepts three schedule types:

Type	Required Inputs	Behavior
`periodic`	`interval_minutes`, `action`	Repeats every N minutes.
`daily`	`hour`, `minute`, `action`	Runs at local device time daily.
`once`	`delay_minutes`, `action`	Runs once after N minutes, then auto-removes itself.

{"type":"once","delay_minutes":20,"action":"check garage sensor"}

Scheduler resolution is minute-based. A one-shot fires on the next due cron scan.

User Tool Model

User-defined tools do not compile code. They store short action text that the model later translates into built-in tool calls.

You: Create tool "water_plants" to turn GPIO 5 on for 30 seconds then off
Agent internals:
1) create_tool(name="water_plants", action="Turn GPIO 5 on, wait 30 seconds, turn off")
2) Later invocation returns action text
3) Model executes via gpio_write + delay + gpio_write

Operational Boundaries

GPIO is constrained by configured safety policy.
Memory keys for user values must use u_ prefix.
Schedule action payload is bounded by CRON_MAX_ACTION_LEN.