A plan step’s
tool_name may also be one of the seven control steps — exit, ask, agent, decide, filter, and map/reduce. They are bare names with no namespace, and they are not tools: the executor evaluates them, so they belong to no registry and cannot be invoked. They are listed and described alongside the catalog anyway, under the (control) source, because writing a step needs their input schemas exactly as much as a tool’s.
Inspecting and invoking
tools test uses the same input model as plans ('{json}', @file, -, --input k=v) and is the fastest way to learn a tool’s real output shape before referencing it in a plan.
tools list and tools show answer for the whole step vocabulary, control steps included (graph tools show ask). tools test does not — a control step has no implementation to call, and asking for one is refused with an explanation rather than an “unknown tool”.
Composition rules
- Plan steps can call anything in the catalog — MCP tools, user tools, other plans (
plan__*), and evenplan_and_execute. Plans are composable by design: build small focused plans and orchestrate them from larger ones. - Cycles are caught, depth is bounded. The pipeline tracks the plan call stack —
a → b → afails immediately with the cycle named, and nesting is capped at 8 levels. - Everything feeds the shape cache — every successful call from any surface records the tool’s observed output shape.
Keeping the catalog sharp
The agent and the planner reason over every tool description in the catalog, so curation improves both cost and routing: allowlist or blocklist per-server tools withinclude_tools/exclude_tools, and patch weak descriptions or missing output schemas with tool_overrides — see filtering and overrides.