Tool nodes

A tool node invokes one registered tool by id with structured args. No AI in the loop. Pure function call, structured input, structured output.

nodes:
  - id: list-unread
    tool: gws.gmail.users.messages.list
    tool_args:
      userId: me
      q: is:unread

Use a tool node when you know the exact API you want to hit. Use an agent node when you want the runtime to figure out which tool(s) to call.

What "tool id" means

Pick from Settings → Tools. Every entry there is the canonical id you write in the YAML. Tools come from connector adapters — when you install gws you get every Gmail/Drive/Calendar/etc. method as a tool. When you install an MCP server via mcporter, you get every tool that server exposes. Same registry; same lookup; same YAML surface.

Common shapes:

Tool id	What it does
gws.gmail.users.messages.list	List Gmail messages
gws.drive.files.list	List Drive files
mcp.notion.search	Search Notion (via mcporter)
pp.espn.scoreboard	Get the ESPN scoreboard (via Printing Press)

The leading segment is the connector id. Settings → Tools groups by it for navigation.

Full surface

- id: search-notion
  tool: mcp.notion.search
  tool_args:
    query: $previous.output.text
    pageSize: 20
  tool_timeout_ms: 30000
  tool_advanced_shell: false

tool_args is forwarded verbatim to the tool — the shape comes from the tool's own schema. Each tool registers a JSON Schema for its args; what you pass must match it. The picker in the workflow editor shows the schema inline.

tool_timeout_ms overrides the tool endpoint's default timeout for this one call.

tool_advanced_shell: true opts a CLI tool into shell mode for this call. It only takes effect when the tool endpoint itself was declared with advancedShell: true — both sides must agree. This is a deliberate two-gate so a runaway agent can't escalate a deterministic CLI tool to shell execution.

Output

The tool's output lands at $nodeId.output:

- id: count
  bash: echo "got $list-unread.output messages"
  depends_on: [list-unread]

What's in output depends on the tool's outputFormat:

• json — JSON-serialized result
• ndjson — newline-delimited JSON (one record per line)
• text — raw text
• binary — base64-encoded bytes

Settings → Tools shows each tool's output format.

Errors

Error	What happened
UnknownToolError: …	The id isn't in the registry. Check Settings → Tools or rerun gws schema / mcporter list.
tool '<id>' failed (cli): exit 2	The underlying CLI exited non-zero. Stderr is in the error message.
tool '<id>' failed (mcp): …	The MCP server returned an error response.
tool '<id>' failed (timeout): exceeded 30000ms	The call ran past tool_timeout_ms (or the endpoint default).

Tool nodes vs agent nodes vs bash nodes

You want	Use
Hit one known API endpoint	tool:
Run a shell command you wrote	bash:
Let an AI decide which tool(s) to call	agent:
Run a script in a specific runtime (bun/uv)	script:

Tool nodes are the registered variant of bash nodes — same determinism, structured args, schema-validated, source-of-truth in the registry instead of in your YAML.

Related

• Agent nodes — AI-driven tool use
• Connectors — how tools get registered