createTool()

createTool() 関数は、Mastra Agent が実行できるカスタム Tool を定義するために使用します。Tool を使うと、外部システムとの連携、計算の実行、特定データへのアクセスが可能になり、Agent の機能を拡張できます。

使用例

src/mastra/tools/weather-tool.ts

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Get the current weather for a location',
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return {
      location,
      temperatureCelsius: 21,
      conditions: 'sunny',
    }
  },
})

execute の第1パラメーターは、inputSchema で検証済みの値です。{ location } のように、関数シグネチャでスキーマのフィールドを直接分割代入します。省略可能な第2パラメーターには実行コンテキストが渡されます。

パラメーター

id:

string

Tool の一意な識別子。

description:

string

Tool の機能を説明します。Agent はこの説明を基に Tool を使用するタイミングを判断します。

inputSchema?:

StandardJSONSchemaV1

Tool の execute 関数に渡す入力パラメーターを定義する Standard JSON Schema。

outputSchema?:

StandardJSONSchemaV1

Tool の execute 関数が返す出力構造を定義する Standard JSON Schema。

strict?:

boolean

true の場合、対応するモデルアダプターで厳密な Tool 入力生成を有効にします。これにより、対応 Provider が Tool スキーマにより正確に一致する引数を返しやすくなります。

toModelOutput?:

(output: TSchemaOut) => unknown

Tool の execute 出力をモデルへ返す前に変換する省略可能な関数。アプリケーションコードには完全な生の出力を保持したまま、text、json、content 形式の出力（画像やファイルなどのマルチモーダルパートを含む）をモデルへ返すために使用します。

transform?:

ToolPayloadTransform

Tool のペイロードが Runtime から表示ストリームやユーザーに表示される Transcript メッセージへ渡る前に適用する、対象別の省略可能な変換。input、inputDelta、output、error、approval、suspend、resume などのフェーズに対して display と transcript の変換を設定します。

suspendSchema?:

StandardJSONSchemaV1

suspend() に渡すペイロードの構造を定義する Standard JSON Schema。Tool が実行を一時停止すると、このペイロードがクライアントに返されます。

resumeSchema?:

StandardJSONSchemaV1

Tool の再開時に渡される resumeData の構造を定義する Standard JSON Schema。autoResumeSuspendedTools が有効な場合、Agent がユーザーメッセージからデータを抽出するために使用します。

requireApproval?:

boolean

true の場合、Tool の実行前に明示的な承認が必要です。Agent は tool-call-approval チャンクを生成し、承認または拒否されるまで一時停止します。

mcp?:

MCPToolProperties

Model Context Protocol 経由で公開する Tool 向けの MCP 固有プロパティ。annotations（title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint など、Tool の動作に関するヒント）と _meta（MCP クライアントへ渡す任意のメタデータ）を含みます。

requestContextSchema?:

StandardJSONSchemaV1

Request Context の値を検証する Standard JSON Schema。指定した場合、execute() の実行前に Context が検証され、検証に失敗するとエラーオブジェクトが返されます。

providerOptions?:

Record<string, Record<string, unknown>>

この Tool の使用時にモデルへ渡す Provider 固有のオプション。キーは anthropic や openai などの Provider 名で、値は Provider 固有の設定オブジェクトです。

inputExamples?:

Array<{ input: Record<string, unknown> }>

対応するモデル Provider が入力例として使用できる、有効な Tool 入力の例。

background?:

ToolBackgroundConfig

この Tool のバックグラウンドタスク設定。有効にすると、Agent との会話を継続しながら Tool をバックグラウンドで実行できます。

execute?:

function

Tool のロジックを含む関数。通常のカスタム Tool では一般に execute を指定しますが、別の場所で実行または適合される Tool 定義では、型として省略できます。inputSchema に基づいて検証された入力データ（第1パラメーター）と、requestContext、abortSignal などの実行メタデータを含む実行コンテキストオブジェクト（第2パラメーター）を受け取ります。

input:

z.infer<TInput>

inputSchema に基づいて検証された入力データ

context?:

ToolExecutionContext

メタデータを含む省略可能な実行コンテキスト

ToolExecutionContext

requestContext?:

RequestContext

共有状態と依存関係にアクセスするための Request Context

abortSignal?:

AbortSignal

Tool の実行を中止するための Signal

agent?:

AgentToolExecutionContext

Agent が Tool を実行した場合に利用できる、Agent 固有の Context。

string

string

CoreMessage[]

(payload, options?) => Promise<void>

TResume

string

string

WritableStream<any>

workflow?:

WorkflowToolExecutionContext

Workflow 固有の Context（state、setState、suspend など）

mcp?:

MCPToolExecutionContext

MCP 固有の Context（elicitation など）

observe:

ToolObserve

Tool の execute 関数内から子 Span と構造化ログを記録するための可観測性ヘルパー。常に提供されます。トレース Context が有効でない場合、span は関数を直接実行し、log は何もしません。

(name: string, fn: () => Promise<T> | T, attributes?: Record<string, unknown>) => Promise<T>

(level: 'debug' | 'info' | 'warn' | 'error' | 'fatal', message: string, data?: Record<string, unknown>) => void

onInputStart?:

function

Tool 呼び出しの入力ストリーミング開始時に呼び出される省略可能なコールバック。シグネチャ: (options: ToolCallOptions) => void | PromiseLike<void>。

onInputDelta?:

function

ストリーミングされる入力テキストの増分チャンクごとに呼び出される省略可能なコールバック。シグネチャ: ({ inputTextDelta, ...options }: { inputTextDelta: string } & ToolCallOptions) => void | PromiseLike<void>。

onInputAvailable?:

function

Tool の完全な入力が利用可能になり、解析されたときに呼び出される省略可能なコールバック。シグネチャ: ({ input, ...options }: { input: TSchemaIn } & ToolCallOptions) => void | PromiseLike<void>。

onOutput?:

function

Tool が正常に実行され、出力を返した後に呼び出される省略可能なコールバック。シグネチャ: ({ output, toolName, ...options }: { output: TSchemaOut; toolName: string } & Omit<ToolCallOptions, 'messages'>) => void | PromiseLike<void>。

mastra や mcpMetadata など Runtime によって設定されるフィールドはソースの型に含まれますが、Mastra または MCP アダプターによって設定されます。通常の createTool() の使用では設定する必要はありません。

戻り値

createTool() 関数は Tool オブジェクトを返します。

Tool:

object

定義済みの Tool を表す、Agent に追加可能なオブジェクト。

スキーマの定義

Tool の inputSchema と outputSchema は、Standard JSON Schema をサポートする任意のライブラリで定義できます。Zod、Valibot、ArkType などが該当します。

Zod

src/mastra/tools/weather-tool.ts

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Fetches weather for a location',
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return { location, temperatureCelsius: 21, conditions: 'sunny' }
  },
})

Valibot

src/mastra/tools/weather-tool.ts

import { createTool } from '@mastra/core/tools'
import * as v from 'valibot'
import { toStandardJsonSchema } from '@valibot/to-json-schema'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Fetches weather for a location',
  inputSchema: toStandardJsonSchema(
    v.object({
      location: v.string(),
    }),
  ),
  outputSchema: toStandardJsonSchema(
    v.object({
      location: v.string(),
      temperatureCelsius: v.number(),
      conditions: v.string(),
    }),
  ),
  execute: async ({ location }) => {
    return { location, temperatureCelsius: 21, conditions: 'sunny' }
  },
})

ArkType

src/mastra/tools/weather-tool.ts

import { createTool } from '@mastra/core/tools'
import { type } from 'arktype'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Fetches weather for a location',
  inputSchema: type({
    location: 'string',
  }),
  outputSchema: type({
    location: 'string',
    temperatureCelsius: 'number',
    conditions: 'string',
  }),
  execute: async ({ location }) => {
    return { location, temperatureCelsius: 21, conditions: 'sunny' }
  },
})

厳密な Tool 入力を使用する例

対応するモデル Provider に Tool スキーマと完全に一致する Tool 引数を生成させる場合は、strict: true を設定します。

src/mastra/tools/weather-tool.ts

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Get the current weather for a location',
  strict: true,
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return {
      location,
      temperatureCelsius: 21,
      conditions: 'sunny',
    }
  },
})

Mastra は、厳密な Tool 呼び出しに対応するモデルアダプターへ strict: true を転送します。対応していないアダプターでは、このオプションは無視されます。

toModelOutput を使用する例

Tool からアプリへは情報量の多い内部データを返し、モデルへは単純化した値またはマルチモーダルコンテンツを渡す場合に、toModelOutput を使用します。

src/mastra/tools/weather-tool.ts

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Get the current weather for a location',
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
    radarImageUrl: z.string().url(),
  }),
  execute: async ({ location }) => ({
    location,
    temperatureCelsius: 21,
    conditions: 'sunny',
    radarImageUrl: 'https://example.com/radar/seattle.png',
  }),
  toModelOutput: output => {
    return {
      type: 'content',
      value: [
        {
          type: 'text',
          text: `${output.location}: ${output.temperatureCelsius}°C and ${output.conditions}`,
        },
        { type: 'image-url', url: output.radarImageUrl },
      ],
    }
  },
})

Tool は完全な execute の結果をアプリケーションに返し、モデルは変換後の toModelOutput の値を受け取ります。

toModelOutput は次の形式を返せます。

• type: 'text'
• type: 'json'
• text、image-url、image-data、file-url、file-data、file-id、image-file-id、custom などのパートを持つ type: 'content'

transform を使用する例

Runtime の動作には生の入力または出力を保持しながら、表示ストリームや Transcript メッセージには、より小さく安全な形式を渡す場合に transform を使用します。

src/mastra/tools/customer-tool.ts

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const customerTool = createTool({
  id: 'lookup-customer',
  description: 'Looks up a customer',
  inputSchema: z.object({
    customerId: z.string(),
    internalPath: z.string(),
  }),
  outputSchema: z.object({
    displayName: z.string(),
    apiKey: z.string(),
    debugScore: z.number(),
  }),
  execute: async () => {
    return {
      displayName: 'Acme',
      apiKey: 'secret-value',
      debugScore: 0.97,
    }
  },
  transform: {
    display: {
      input: ({ input }) => ({ customerId: input?.customerId }),
      output: ({ output }) => ({ displayName: output?.displayName }),
      error: () => ({ message: 'Customer lookup failed' }),
    },
    transcript: {
      input: ({ input }) => ({ customerId: input?.customerId }),
      output: ({ output }) => ({ displayName: output?.displayName }),
      error: () => ({ message: 'Customer lookup failed' }),
    },
  },
})

Tool は生の inputSchema の値を受け取り、生の execute の結果を返します。Mastra は、ストリーミングされる UI ペイロードに display の変換を、ユーザーに表示される Transcript メッセージに transcript の変換を適用します。

MCP アノテーションを使用する例

MCP（Model Context Protocol）経由で Tool を公開する場合、Tool の動作を説明し、クライアントでの表示方法をカスタマイズするためのアノテーションを追加できます。これらの MCP 固有プロパティは mcp プロパティにまとめられます。

src/mastra/tools/weather-tool.ts

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Get the current weather for a location',
  inputSchema: z.object({
    location: z.string().describe('City name or coordinates'),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  // MCP-specific properties
  mcp: {
    // Annotations for client behavior hints
    annotations: {
      title: 'Weather Lookup', // Human-readable display name
      readOnlyHint: true, // Tool doesn't modify environment
      destructiveHint: false, // Tool doesn't perform destructive updates
      idempotentHint: true, // Same args = same result
      openWorldHint: true, // Interacts with external API
    },
    // Custom metadata for client-specific functionality
    _meta: {
      version: '1.0.0',
      category: 'weather',
    },
  },
  execute: async ({ location }) => {
    return {
      location,
      temperatureCelsius: 21,
      conditions: 'sunny',
    }
  },
})

Tool のライフサイクルフック

Tool は、実行の各段階を監視し、対応できるライフサイクルフックをサポートしています。これらのフックは、ストリーミング中のログ記録、分析、検証、リアルタイム更新に特に役立ちます。

次の例は、すべてのライフサイクルフックを設定した Tool を示しています。

src/mastra/tools/weather-tool.ts

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Get the current weather for a location',
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return {
      location,
      temperatureCelsius: 21,
      conditions: 'sunny',
    }
  },
  onInputStart: ({ toolCallId }) => {
    console.log(`Tool call ${toolCallId} input started`)
  },
  onInputDelta: ({ inputTextDelta, toolCallId }) => {
    console.log(`Tool call ${toolCallId} received input chunk: ${inputTextDelta}`)
  },
  onInputAvailable: ({ input, toolCallId }) => {
    console.log(`Tool call ${toolCallId} received location: ${input.location}`)
  },
  onOutput: ({ output, toolCallId, toolName }) => {
    console.log(`Tool ${toolName} call ${toolCallId} returned conditions: ${output.conditions}`)
  },
})

利用可能なフック

onInputStart

Tool 呼び出しの入力ストリーミングが開始されたとき、入力データを受信する前に呼び出されます。

export const tool = createTool({
  id: 'example-tool',
  description: 'Example tool with hooks',
  onInputStart: ({ toolCallId, messages, abortSignal }) => {
    console.log(`Tool ${toolCallId} input streaming started`)
  },
})

onInputDelta

ストリーミングされる入力テキストの増分チャンクごとに呼び出されます。リアルタイムの進行状況の表示や、部分的な JSON の解析に役立ちます。

export const tool = createTool({
  id: 'example-tool',
  description: 'Example tool with hooks',
  onInputDelta: ({ inputTextDelta, toolCallId, messages, abortSignal }) => {
    console.log(`Received input chunk: ${inputTextDelta}`)
  },
})

onInputAvailable

Tool の完全な入力が利用可能になり、解析され、inputSchema に対して検証されたときに呼び出されます。

export const tool = createTool({
  id: 'example-tool',
  description: 'Example tool with hooks',
  inputSchema: z.object({
    location: z.string(),
  }),
  onInputAvailable: ({ input, toolCallId, messages, abortSignal }) => {
    console.log(`Tool received complete input:`, input)
    // input is fully typed based on inputSchema
  },
})

onOutput

Tool が正常に実行され、出力を返した後に呼び出されます。結果のログ記録、後続処理のトリガー、分析に役立ちます。

export const tool = createTool({
  id: 'example-tool',
  description: 'Example tool with hooks',
  outputSchema: z.object({
    result: z.string(),
  }),
  execute: async input => {
    return { result: 'Success' }
  },
  onOutput: ({ output, toolCallId, toolName, abortSignal }) => {
    console.log(`${toolName} execution completed:`, output)
    // output is fully typed based on outputSchema
  },
})

フックの実行順序

一般的な Tool のストリーミング呼び出しでは、フックは次の順序で呼び出されます。

1. onInputStart: 入力ストリーミングを開始
2. onInputDelta: チャンクを受信するたびに複数回呼び出し
3. onInputAvailable: 完全な入力を解析、検証
4. Tool の execute 関数を実行
5. onOutput: Tool が正常に完了

フックのパラメーター

フックのコールバックは、ソースで定義された次の形式のパラメーターを受け取ります。

• onInputStart: toolCallId、messages、abortSignal などのフィールドを含む ToolCallOptions を受け取ります。
• onInputDelta: { inputTextDelta: string } & ToolCallOptions を受け取ります。
• onInputAvailable: { input: TSchemaIn } & ToolCallOptions を受け取ります。input の型は inputSchema から決まります。
• onOutput: { output: TSchemaOut; toolName: string } & Omit<ToolCallOptions, 'messages'> を受け取ります。output の型は outputSchema から決まります。このフックは messages を受け取りません。

エラー処理

フックのエラーは自動的に捕捉、記録され、Tool の実行は継続します。フックがエラーをスローした場合、コンソールに記録されますが、Tool 呼び出しが失敗することはありません。

MCP Tool のアノテーション

Model Context Protocol（MCP）経由で Tool を公開する場合、Tool の動作を説明するアノテーションを指定できます。これらのアノテーションにより、OpenAI Apps SDK などの MCP クライアントは Tool の表示方法と処理方法を判断できます。

MCP 固有のプロパティは mcp プロパティにまとめられ、annotations と _meta が含まれます。

mcp: {
  annotations: { /* behavior hints */ },
  _meta: { /* custom metadata */ },
}

ToolAnnotations のプロパティ

title?:

string

人が読みやすい Tool のタイトル。UI コンポーネントでの表示に使用します。

readOnlyHint?:

boolean

true の場合、Tool は環境を変更しません。このヒントは、Tool がデータを読み取るだけで副作用がないことを示します。デフォルトは false です。

destructiveHint?:

boolean

true の場合、Tool は環境に破壊的な更新を行う可能性があります。false の場合、Tool は追加的な更新だけを行います。このヒントにより、クライアントは確認を必須にすべきか判断できます。デフォルトは true です。

idempotentHint?:

boolean

true の場合、同じ引数で Tool を繰り返し呼び出しても、環境に追加の影響はありません。このヒントは冪等な動作であることを示します。デフォルトは false です。

openWorldHint?:

boolean

true の場合、この Tool は外部エンティティの「オープンワールド」（Web 検索、外部 API など）とやり取りする可能性があります。false の場合、Tool の対象領域は閉じており、完全に定義されています。デフォルトは true です。

これらのアノテーションは MCP 仕様に準拠し、MCP 経由で Tool が一覧表示されるときにそのまま渡されます。

関連情報

• MCP の概要
• Agent での Tool の使用
• Agent の承認
• Tool のストリーミング
• Request Context