Agent Script Reference: Tools (Reasoning Actions)

Tools are executable functions that the LLM can choose to call, based on the tool's description and the current context. You define tools in the subagent's reasoning.actions block. Tools can be actions or other utilities.

Tools must wrap an action or a @utils function. Use with to bind parameters and set to assign output values to variables. You can use the available when parameter to deterministically specify when the tool is available.

Tools vs. Actions. Agent Script has two actions blocks:

  • Subagent actions (subagent.actions) — Available to you from logic-based reasoning instructions
  • Reasoning actions (subagent.reasoning.actions) — Available to the LLM to call as needed, and can be referenced in your prompt-based instructions

Since reasoning actions can reference subagents and utilities in addition to regular subagent actions, we sometimes call them "tools" to reflect their broader uses. In Canvas view, this distinction is handled automatically, but it's important to understand when writing Agent Script directly.

The LLM looks at the names and descriptions of all the tools when deciding whether to call a tool. Tools should have meaningful names and descriptions. To provide more context, you can explicitly reference a tool in the reasoning instructions.

For example, these reasoning instructions don't provide additional context about which tool to call.

These reasoning instructions provide more details about when to use the capture_order_info tool.

Use available when to define the conditions that must exist for the LLM to use the tool.

In reasoning actions, you can reference a subagent directly with @subagent.<topic_name> or through a declarative transition (@utils.transition to). Use a direct @subagent.<topic_name> reference to delegate to a subagent, similar to an action or tool call. After the referenced subagent is run, the flow returns to the original subagent. This behavior is different from a declarative transition (@utils.transition to) in that transitions are one way, whereas a direct subagent reference returns to the original caller. If a referenced subagent includes a declarative transition, the flow follows that path until it ends, and then returns to the original subagent.

In this code sample, you can see both methods of calling another subagent.