From fce7b113baeb26b2b882bc2186214c00a8119668 Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Tue, 15 Sep 2026 11:40:48 -0600 Subject: [PATCH] docs: todo__ tools are unavailable in llm nodes (validation error); use agent nodes with auto_continue children for driven work --- Graph-Agents.md | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/Graph-Agents.md b/Graph-Agents.md index 1aec127..d6f645c 100644 --- a/Graph-Agents.md +++ b/Graph-Agents.md @@ -702,16 +702,27 @@ list; an unknown entry is a startup error. Coyote's built-in function families are not all governed by the `tools:` whitelist the same way: -- **`user__*` and `todo__*` require explicit opt-in.** Inside an `llm` node - these interactive/turn-control builtins are only offered to the model if - the node's `tools:` list names them (e.g. `tools: [user__select]`). A node - that doesn't list them never sees them. This is deliberate: graph nodes - usually run headless, and a structured-output node calling `user__select` - ("Ready to finalize?") suspends the node as an escalation instead of - producing its output. The graph validator warns when a node with an - `output_schema` explicitly opts into `user__*` tools. Approval gates are - unaffected — use a [`approval` node](#approval) for human sign-off, not an - `llm` node with user tools. +- **`user__*` requires explicit opt-in.** Inside an `llm` node the + interactive builtins are only offered to the model if the node's `tools:` + list names them (e.g. `tools: [user__select]`). A node that doesn't list + them never sees them. This is deliberate: graph nodes usually run headless, + and a structured-output node calling `user__select` ("Ready to finalize?") + suspends the node as an escalation instead of producing its output. The + graph validator warns when a node with an `output_schema` explicitly opts + into `user__*` tools. Approval gates are unaffected — use a + [`approval` node](#approval) for human sign-off, not an `llm` node with + user tools. +- **`todo__*` is unavailable in `llm` nodes entirely**. Listing a todo tool + in a node's `tools:` is a validation **error**. The todo system drives chat + turn loops (`auto_continue`): the usage prompt, the incomplete-item check + at turn end, and the continuation nudge all live at the agent turn + boundary. An `llm` node has no turn boundary. Its continuation is owned + by the node's tool-call loop, `max_iterations`, and graph edges. So a + node-local todo list would never be driven to completion and its writes + would leak into agent/session state. For driven multi-step work inside a + graph, use an [`agent` node](#agent) whose agent sets + `auto_continue: true`: spawned children get a fresh todo list and are + pushed to completion normally. - **`agent__*`, `memory__*`, `job__*`, `skill__*`, and RAG builtins stay implicitly available** (subject to their usual gates: `can_spawn_agents` for spawning, the skill policy for skills, and so on) regardless of the