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

# createTool()

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

## 使用例

```typescript
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パラメーター）を受け取ります。

**execute.input** (`z.infer<TInput>`): inputSchema に基づいて検証された入力データ

**execute.context** (`ToolExecutionContext`): メタデータを含む省略可能な実行コンテキスト

**execute.context.requestContext** (`RequestContext`): 共有状態と依存関係にアクセスするための Request Context

**execute.context.abortSignal** (`AbortSignal`): Tool の実行を中止するための Signal

**execute.context.agent** (`AgentToolExecutionContext`): Agent が Tool を実行した場合に利用できる、Agent 固有の Context。

**execute.context.workflow** (`WorkflowToolExecutionContext`): Workflow 固有の Context（state、setState、suspend など）

**execute.context.mcp** (`MCPToolExecutionContext`): MCP 固有の Context（elicitation など）

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

**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](https://standardschema.dev/json-schema) をサポートする任意のライブラリで定義できます。[Zod](https://zod.dev/)、[Valibot](https://valibot.dev/)、[ArkType](https://arktype.io/) などが該当します。

**Zod**:

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

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

```typescript
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` を設定します。

```typescript
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` を使用します。

```typescript
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` を使用します。

```typescript
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` プロパティにまとめられます。

```typescript
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 を示しています。

```typescript
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 呼び出しの入力ストリーミングが開始されたとき、入力データを受信する前に呼び出されます。

```typescript
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 の解析に役立ちます。

```typescript
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` に対して検証されたときに呼び出されます。

```typescript
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 が正常に実行され、出力を返した後に呼び出されます。結果のログ記録、後続処理のトリガー、分析に役立ちます。

```typescript
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` が含まれます。

```typescript
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 仕様](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#tool-annotations)に準拠し、MCP 経由で Tool が一覧表示されるときにそのまま渡されます。

## 関連情報

- [MCP の概要](https://mastra.zisheng.pro/ja/docs/mcp/overview)
- [Agent での Tool の使用](https://mastra.zisheng.pro/ja/docs/agents/using-tools)
- [Agent の承認](https://mastra.zisheng.pro/ja/docs/agents/agent-approval)
- [Tool のストリーミング](https://mastra.zisheng.pro/ja/docs/agents/using-tools)
- [Request Context](https://mastra.zisheng.pro/ja/docs/server/request-context)