chapter 2

Tool Surface

Tools are the execution boundary: model chooses calls, firmware enforces schema and executes side effects.

Built-In Tools

Group	Tools	Use
GPIO	`gpio_write`, `gpio_read`, `delay`, `i2c_scan`	Pins, timings, sensor bus checks.
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`	Firmware + runtime diagnostics.
User tools	`create_tool`, `list_user_tools`, `delete_user_tool`	Natural-language macro layer.

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.