@mastra/core/dist/docs/references/reference-workflows-workflow-methods-tool.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# 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](https://mastra.ai/docs/workflows/stored-workflows).

## Usage example

```typescript
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:

```typescript
workflow.tool("lookup-customer", { retries: 2 }).commit();
```

## Persisting tool steps

Workflows built with `.tool()` serialize to the same declarative entries that [stored workflows](https://mastra.ai/docs/workflows/stored-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](https://mastra.ai/docs/workflows/agents-and-tools)
- [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows)
- [Workflow.agent()](https://mastra.ai/reference/workflows/workflow-methods/agent)