Workflow.tool()

The .tool() method adds a tool as a declarative step. The tool's own input and output schemas apply, so the previous step's output must satisfy the tool's input schema. Use .map() to transform the data if they don't match.

Unlike wrapping a tool with createStep(), .tool() records a declarative entry in the workflow graph. This makes the workflow portable: the same graph can be serialized and persisted as a dynamic workflow.

Usage example

workflow.tool(testTool).commit()

Parameters

toolOrId:

Tool | string

A tool instance, or the ID of a tool registered on the Mastra instance. When passing an ID, the tool is resolved from the registry at execution time.

options?:

{ retries?: number, scorers?: DynamicArgument<MastraScorers>, metadata?: StepMetadata }

Step-level retry count, scorers, and metadata for the tool step.

stepOptions?:

{ id?: string }

The step's call-site ID within the workflow. Defaults to the tool's ID. Set this when the same tool appears more than once in one workflow.

Returns

workflow:

Workflow

The workflow instance for method chaining

Referencing a tool by ID

Pass a string to reference a registered tool without importing it. The tool must be registered on the Mastra instance when the workflow runs:

workflow.tool('lookup-customer', { retries: 2 }).commit()

Persisting tool steps

Workflows built with .tool() serialize to the same declarative entries that dynamic workflows use. Only retries and metadata round-trip through storage. A function-valued scorers option throws an error when the workflow is stored.

Related

• Agents and Tools
• Dynamic workflows
• Workflow.agent()