Tool Flows

A tool flow lets the model run several tool calls inside one short Python-subset script. When one call’s result feeds the next call’s arguments, a normal conversation needs a round trip per call: the model requests a tool, waits for the result, then requests the next tool. A tool flow collapses that sequence into a single tool_flow call. The model writes the script, Polytoken runs it against the tools you approved, and the model gets every result at once.

When to use a tool flow

A tool flow fits work whose sequence the model already knows: read a file, search its contents, fetch a page named in the results, then combine everything. The model decides the logic up front and the script carries it out without further model involvement.

Independent calls that share nothing do not need a flow. The model can batch those in one turn already, and a flow would only add a script between the model and its tools.

Writing a script

A tool_flow call carries the code, a name for the flow, and the list of tools the script may call. Two optional settings tune the run: timeout_seconds (twenty minutes by default) and background.

readme = file_read(path="README.md")
hits = grep(pattern="tool_flow", path="rs")
print(f"found {len(hits)} matches")
{"readme": readme[:200], "matches": hits}

Each requested tool becomes a function in the script. Polytoken uses the registry name when it is a valid Python identifier and otherwise creates a valid, unique alias. Call tools with keyword arguments, use print() for diagnostic output, and leave the value you want returned as the trailing expression. That final expression becomes the flow’s result. The Python subset provides access only through the approved tools: it does not offer direct filesystem, shell, network, or process-spawning APIs.

The result envelope

A finished flow returns a JSON envelope: the script status, the captured print() output, the trailing-expression result, a log of the tool calls the script made, and timing stats. The truncation marker states whether Polytoken shortened any field to fit. Polytoken shortens large output for the conversation and keeps the fuller content in the expanded tool card.

Approval and permissions

A flow receives approval for its exact script and tool set before it starts. An approval covers one script and one tool set; Polytoken never applies it to a later flow with different code or different tools. A deny rule, a protected file, or a .agentblock entry makes the tool call fail as a catchable error inside the script. Denied calls never pause the flow to ask a question, so an approved flow runs to completion without further prompts.

A flow can call only the tools named in its tools list. Eligible built-in tools opt in explicitly: the file reading, file searching, and web fetching tools today. MCP tools are eligible unless daemon.tool_flow.mcp_tools_deny denies them. Shell, planning, subagent, todo, and facet tools are never callable from a flow, and a flow cannot call tool_flow itself. Two more keys under daemon.tool_flow tune a flow’s ceiling: max_timeout_seconds caps the time budget and max_calls caps how many calls one flow may make.

Background flows

Set background: true to run a flow in the background, or press Ctrl+B while it runs in the foreground. Polytoken returns a job handle immediately, named after your flow, and the flow keeps running while you continue the conversation. Use the standard job controls to inspect, retrieve, or cancel the flow, like any other background job.