Tools

A tool is a capability, not a component. It has no place on the canvas, no position, no lifecycle of its own — it is a property of an agent, the way a hand is a property of a person.

That's why tools behave differently from everything else in the palette: you never drag one.

Assigning a tool#

Two clicks.

1. Click a tool in the palette. The row turns orange, a banner appears at the top of the canvas reading "Assigning read_file — click an agent", and every agent on the canvas grows an orange ring.
2. Click a ringed agent. A badge chip with the tool's name appears under the node's header.

The tool stays armed after it lands, so you can hand the same capability to several agents without going back to the palette. Clicking a node that isn't an agent won't assign anything — it just selects that node as usual — and clicking empty canvas disarms.

To stop: press Escape (works from anywhere), click the Esc button in the banner, click empty canvas, or click the same palette row again.

To take a tool away: hover the badge chip on the node — or use the Tools section of the Inspector, where the chips are always visible — and click the small trash icon.

⚑ What a tool is allowed to do#

Read this before you give an agent delete or run_command.

What does stand between an agent and your machine:

The project boundary. Every file path is resolved against the open project's root and refused if it points outside — ../ climbs, absolute paths elsewhere, all rejected. Note this is a check on the path, not on where the path ultimately leads: a symlink inside your project that points somewhere else is still followed when a file is read or written. The two tools that walk directories, list_dir and search_files, don't follow symlinks at all.

A command allowlist. run_command can only start one of these:

git · node · npm · npx · pnpm · yarn · cargo · rustc · python · python3 · pip · pip3 · tsc

No shell is involved, so pipes, redirects and shell expansion don't work — arguments are passed literally. Its working directory must also be inside the project.

Time and size limits. Commands time out (60 seconds by default, 10 minutes maximum) and their output is capped.

Until an approval gate lands, treat a flow's tool badges the way you'd treat a script you're about to run: read them before you press Run, especially on a flow someone else wrote.

You need a project open#

If any agent in a flow carries any tool badge, the run refuses to start without an open project:

"this flow's agents declare tools but no project is open — open the project the tools should run in, then run again"

A flow with no tool badges at all runs fine with nothing open — it just can't touch anything.

Tools always execute in the active project's folder, whichever agent called them.

The twenty tools#

The palette shows one flat Tools group. They fall into five families.

Files (11)#

Tool	What it does
read_file	Read a file, with line ranges and smart truncation
read_files	Read several files at once
create_file	Create a file
create_files	Create up to two files in one call
create_dirs	Create directories, mkdir -p style
edit_file	Replace, insert or delete inside an existing file
delete	Delete files or directories — also purges them from the index
copy_path	Copy files and directories
move_path	Move or rename
search_files	Find files by name or glob
list_dir	List what's in a directory

Code (4)#

Tool	What it does
code_search	Full-text search across the whole index, ranked by relevance
code_grep	Regex or exact-string search — and matches are tagged with the function or class they sit inside
symbols	Find where something is defined
references	Find everything that calls, imports or uses a symbol

These four are why an agent here needs far less hand-holding than one working with plain search.

code_search, symbols and references read the project's index, so they only see what has been indexed — code_search fails outright if there's no index. code_grep is the exception: it reads the files on disk, so it finds things that were never indexed, and consults the index only to name the symbol each match sits inside. Where it can't place a match, it simply reports it untagged.

Diagnostics (1)#

check_errors runs your project's real type-checker — tsc for TypeScript and JavaScript, cargo check for Rust — and returns structured errors with file, line and message. It reads from disk, so it reflects edits the agent has just made. This is the tool that lets an agent verify its own work.

Shell (1)#

run_command — the allowlist above.

Notebook (3)#

notebook_write, notebook_search and notebook_recent give an agent a per-project memory that outlives a run: notes it can write and later search semantically.

When a badge has no hand#

If a saved flow names a tool this build can't provide, the run is refused by name rather than quietly running without it:

"Agent node … declares tool(s) this run cannot provide: … Available: …"

That's deliberate. An agent that believes it has a tool it doesn't will invent the tool's output instead of admitting it's missing.

What the agent sees#

Each tool carries a description written for the model, not for you — it's what tells the agent when to reach for code_grep rather than code_search. You never see those strings in the composer; the palette shows only the tool's name.