Tools

withTool

Registers a tool that the agent can use. Tools are external functions or APIs that the agent can invoke to perform actions or retrieve information. This method registers the tool’s metadata (name, description, parameters) and optionally execution logic. The Zod schema is introspected to create human-readable parameter documentation.

PromptSmith Format

withTool<T extends ZodType>(def: ExecutableToolDefinition<T>): this

def

ExecutableToolDefinition<T>

required

Tool definition containing:

name: Unique tool identifier
description: When and how to use the tool
schema: Zod schema for parameters
execute: (optional) Execution function with full type inference

Returns

this

The builder instance for method chaining

Mastra Format

Also accepts tools created with Mastra’s createTool() function, automatically converting them to PromptSmith’s internal format.

withTool(def: MastraToolDefinition): this

def

MastraToolDefinition

required

Tool definition in Mastra format (created with createTool())

Examples

Basic Tool
With Execution
Mastra Tool

builder.withTool({
  name: "get_weather",
  description: "Retrieves current weather for a location. Use when user asks about weather.",
  schema: z.object({
    location: z.string().describe("City name or ZIP code"),
    units: z.enum(["celsius", "fahrenheit"]).optional().describe("Temperature units")
  })
});

builder.withTool({
  name: "get_weather",
  description: "Get current weather",
  schema: z.object({
    location: z.string(),
    units: z.enum(["celsius", "fahrenheit"])
  }),
  execute: async ({ location, units }) => {
    // ✅ TypeScript infers: location is string, units is "celsius" | "fahrenheit"
    const response = await fetch(`https://api.weather.com/${location}?units=${units}`);
    return response.json();
  }
});

import { createTool } from "@mastra/core/tools";

const weatherTool = createTool({
  id: "weather-tool",
  description: "Get weather",
  inputSchema: z.object({ location: z.string() }),
  execute: async ({ context }) => fetchWeather(context.location)
});

builder.withTool(weatherTool); // Automatically converted!

withTools

Registers multiple tools at once. This is a convenience method for adding several tools in a single call, equivalent to calling .withTool() multiple times. Useful when you have a pre-defined collection of tools to register.

withTools(defs: ExecutableToolDefinition[]): this

defs

ExecutableToolDefinition[]

required

An array of tool definitions

Returns

this

The builder instance for method chaining

Example

const myTools = [
  { name: "tool1", description: "First tool", schema: z.object({...}) },
  { 
    name: "tool2", 
    description: "Second tool", 
    schema: z.object({...}), 
    execute: async (...) => {...} 
  }
];

builder.withTools(myTools);

withToolIf

Conditionally registers a tool based on a condition. This method only adds the tool if the condition evaluates to true, making it easier to build prompts with conditional tool availability without breaking the fluent chain.

withToolIf(condition: boolean, def: ExecutableToolDefinition): this

condition

boolean

required

Boolean condition that determines if the tool is added

def

ExecutableToolDefinition

required

Tool definition containing name, description, parameter schema, and optionally an execute function

Returns

this

The builder instance for method chaining

Example

const hasDatabase = config.databaseEnabled;
const hasExternalApi = config.apiKey !== null;

builder
  .withToolIf(hasDatabase, {
    name: "query_db",
    description: "Query the database",
    schema: z.object({ query: z.string() }),
    execute: async ({ query }) => await db.execute(query)
  })
  .withToolIf(hasExternalApi, {
    name: "fetch_external_data",
    description: "Fetch data from external API",
    schema: z.object({ endpoint: z.string() }),
    execute: async ({ endpoint }) => await api.fetch(endpoint)
  });

Core API

Builder Methods

Types

withTool

PromptSmith Format

Mastra Format

Examples

withTools

Example

withToolIf

Example

Build docs developers (and LLMs) love

Core API

Builder Methods

Types

​withTool

​PromptSmith Format

​Mastra Format

​Examples

​withTools

​Example

​withToolIf

​Example

Build docs developers (and LLMs) love

withTool

PromptSmith Format

Mastra Format

Examples

withTools

Example

withToolIf

Example