Documentation Index
Fetch the complete documentation index at: https://mintlify.com/mastra-ai/mastra/llms.txt
Use this file to discover all available pages before exploring further.
Overview
A toolset is a collection of related tools that can be registered together with an agent or workflow. Toolsets help organize tools by domain or functionality.Type Definition
type ToolsInput = Record<
string,
ToolAction<any, any, any, any, any> | VercelTool | VercelToolV5 | ProviderDefinedTool
>
type ToolsetsInput = Record<string, ToolsInput>
Creating Toolsets
Toolsets are simply objects that map tool names to tool instances:import { createTool } from '@mastra/core/tools';
import { z } from 'zod';
const weatherTools = {
getCurrentWeather: createTool({
id: 'get-current-weather',
description: 'Get the current weather for a location',
inputSchema: z.object({
location: z.string(),
units: z.enum(['celsius', 'fahrenheit']).optional()
}),
execute: async ({ location, units = 'celsius' }) => {
// Fetch weather data
return {
temperature: 72,
conditions: 'sunny',
units
};
}
}),
getForecast: createTool({
id: 'get-forecast',
description: 'Get the weather forecast for a location',
inputSchema: z.object({
location: z.string(),
days: z.number().min(1).max(10).default(5)
}),
execute: async ({ location, days }) => {
// Fetch forecast data
return {
forecast: [
{ day: 'Monday', high: 75, low: 62 },
{ day: 'Tuesday', high: 73, low: 60 }
]
};
}
})
};
const calculationTools = {
add: createTool({
id: 'add',
description: 'Add two numbers',
inputSchema: z.object({
a: z.number(),
b: z.number()
}),
execute: async ({ a, b }) => ({ result: a + b })
}),
multiply: createTool({
id: 'multiply',
description: 'Multiply two numbers',
inputSchema: z.object({
a: z.number(),
b: z.number()
}),
execute: async ({ a, b }) => ({ result: a * b })
})
};
Using Toolsets with Agents
Static Toolsets
import { Agent } from '@mastra/core/agent';
const agent = new Agent({
id: 'assistant',
name: 'Assistant',
instructions: 'You are a helpful assistant with access to weather and calculation tools',
model: 'openai/gpt-5',
tools: {
...weatherTools,
...calculationTools
}
});
Dynamic Toolsets
You can also provide toolsets dynamically at execution time:const response = await agent.generate('What is the weather?', {
toolsets: {
weather: weatherTools,
calculations: calculationTools
}
});
Organizing Toolsets
By Domain
const toolsets = {
database: {
query: queryTool,
insert: insertTool,
update: updateTool
},
api: {
fetch: fetchTool,
post: postTool
},
file: {
read: readFileTool,
write: writeFileTool,
delete: deleteFileTool
}
};
By Service
const toolsets = {
github: {
createIssue: createIssueTool,
listRepos: listReposTool,
createPR: createPRTool
},
slack: {
sendMessage: sendMessageTool,
listChannels: listChannelsTool
},
email: {
send: sendEmailTool,
list: listEmailsTool
}
};
Integration Tools
Mastra provides pre-built integration toolsets for popular services:import { createGithubIntegration } from '@mastra/github';
import { createSlackIntegration } from '@mastra/slack';
const github = createGithubIntegration({
apiKey: process.env.GITHUB_TOKEN
});
const slack = createSlackIntegration({
apiKey: process.env.SLACK_TOKEN
});
const agent = new Agent({
id: 'dev-assistant',
name: 'Developer Assistant',
instructions: 'You help developers with GitHub and Slack',
model: 'openai/gpt-5',
tools: {
...github.tools,
...slack.tools
}
});
Conditional Tools
You can provide tools conditionally based on request context:const agent = new Agent({
id: 'assistant',
name: 'Assistant',
instructions: 'You are a helpful assistant',
model: 'openai/gpt-5',
tools: ({ requestContext }) => {
const userRole = requestContext.get('userRole');
const baseTools = {
search: searchTool,
calculate: calculateTool
};
if (userRole === 'admin') {
return {
...baseTools,
...adminTools
};
}
return baseTools;
}
});
Example: Complete Toolset
import { createTool } from '@mastra/core/tools';
import { Agent } from '@mastra/core/agent';
import { z } from 'zod';
// Define a complete weather toolset
const weatherToolset = {
getCurrentWeather: createTool({
id: 'get-current-weather',
description: 'Get current weather for a location',
inputSchema: z.object({
location: z.string().describe('City name or zip code'),
units: z.enum(['celsius', 'fahrenheit']).default('celsius')
}),
outputSchema: z.object({
temperature: z.number(),
conditions: z.string(),
humidity: z.number(),
windSpeed: z.number()
}),
execute: async ({ location, units }) => {
// API call to weather service
return {
temperature: 72,
conditions: 'Partly cloudy',
humidity: 65,
windSpeed: 8
};
}
}),
getForecast: createTool({
id: 'get-forecast',
description: 'Get multi-day weather forecast',
inputSchema: z.object({
location: z.string(),
days: z.number().min(1).max(10).default(5)
}),
execute: async ({ location, days }) => {
// API call to forecast service
return {
location,
days,
forecast: [
// forecast data
]
};
}
}),
getWeatherAlerts: createTool({
id: 'get-weather-alerts',
description: 'Get active weather alerts for a location',
inputSchema: z.object({
location: z.string()
}),
execute: async ({ location }) => {
return {
alerts: [
// alert data
]
};
}
})
};
// Use the toolset with an agent
const weatherAgent = new Agent({
id: 'weather-agent',
name: 'Weather Agent',
instructions: 'You provide weather information using available weather tools',
model: 'openai/gpt-5',
tools: weatherToolset
});
// Use the agent
const response = await weatherAgent.generate(
'What is the weather in New York and are there any alerts?'
);