Skip to main content

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 stored workflow.

Usage example
Direct link to Usage example

workflow.tool(testTool).commit();

Parameters
Direct link to 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
Direct link to Returns

workflow:

Workflow
The workflow instance for method chaining

Referencing a tool by ID
Direct link to 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
Direct link to Persisting tool steps

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

On this page