Skip to main content

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?'
);

Build docs developers (and LLMs) love