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

# createTool()

`createTool()` 函式用於定義 Mastra Agent 可執行的自訂 Tool。Tool 能讓 Agent 與外部系統互動、執行計算或存取特定資料，藉此擴充 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` 的第一個參數是經 `inputSchema` 驗證的值。請直接在函式 signature 中解構 schema 欄位，如 `{ location }` 所示。選填的第二個參數包含 execution context。

## 參數

**id** (`string`): Tool 的唯一識別碼。

**description** (`string`): Tool 功能的說明。Agent 會使用此說明判斷何時使用 Tool。

**inputSchema** (`StandardJSONSchemaV1`): Standard JSON Schema，用於定義 Tool execute 函式預期的輸入參數。

**outputSchema** (`StandardJSONSchemaV1`): Standard JSON Schema，用於定義 Tool execute 函式預期的輸出結構。

**strict** (`boolean`): 設為 true 時，Mastra 會在支援的 model adapter 上啟用嚴格 Tool 輸入產生功能，協助支援此功能的 Provider 回傳更符合 Tool schema 的引數。

**toModelOutput** (`(output: TSchemaOut) => unknown`): 選填函式，在 Tool 的 execute 輸出傳回模型前進行轉換。可用來將 text、json 或 content 結構的輸出（包括圖片／檔案等多模態部分）回傳給模型，同時在應用程式碼中保留完整原始輸出。

**transform** (`ToolPayloadTransform`): 選填的目標感知 transform，會在 Tool payload 離開 runtime、進入顯示串流或使用者可見的 transcript 訊息前進行轉換。可為 input、inputDelta、output、error、approval、suspend 與 resume 等階段設定 display 和 transcript transform。

**suspendSchema** (`StandardJSONSchemaV1`): Standard JSON Schema，用於定義傳給 suspend() 的 payload 結構。Tool 暫停執行時會將此 payload 回傳給 client。

**resumeSchema** (`StandardJSONSchemaV1`): Standard JSON Schema，用於定義 Tool 繼續執行時預期的 resumeData 結構。啟用 autoResumeSuspendedTools 時，Agent 會使用此 schema 從使用者訊息擷取資料。

**requireApproval** (`boolean`): 設為 true 時，Tool 在執行前需要明確核准。Agent 會發出 tool-call-approval 區塊並暫停，直到核准或拒絕為止。

**mcp** (`MCPToolProperties`): 透過 Model Context Protocol 公開之 Tool 的 MCP 特定屬性。包含 annotations（例如 title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint 等 Tool 行為提示）與 \_meta（原樣傳給 MCP client 的任意中繼資料）。

**requestContextSchema** (`StandardJSONSchemaV1`): 用於驗證 request context 值的 Standard JSON Schema。提供此值時，系統會在 execute() 執行前驗證 context；若驗證失敗，則回傳錯誤物件。

**providerOptions** (`Record<string, Record<string, unknown>>`): 使用此 Tool 時傳給模型的 Provider 特定選項。Key 是 anthropic 或 openai 等 Provider 名稱，值則是 Provider 特定設定物件。

**inputExamples** (`Array<{ input: Record<string, unknown> }>`): 有效 Tool 輸入的範例，支援此功能的模型 Provider 可將其用作輸入範例。

**background** (`ToolBackgroundConfig`): 此 Tool 的背景任務設定。啟用後，Agent 對話繼續進行時，Tool 可在背景執行。

**execute** (`function`): 包含 Tool 邏輯的函式。一般自訂 Tool 通常會提供 execute，但對於在其他位置執行或調整的 Tool 定義，此型別允許省略。它接受兩個參數：根據 inputSchema 驗證的輸入資料（第一個參數），以及包含 requestContext、abortSignal 與其他執行中繼資料的 execution context 物件（第二個參數）。

**execute.input** (`z.infer<TInput>`): 根據 inputSchema 驗證的輸入資料

**execute.context** (`ToolExecutionContext`): 包含中繼資料的選填 execution context

**execute.context.requestContext** (`RequestContext`): 用於存取共用狀態與相依項目的 Request Context

**execute.context.abortSignal** (`AbortSignal`): 用於中止 Tool 執行的 signal

**execute.context.agent** (`AgentToolExecutionContext`): Agent 特定 context，在 Agent 執行 Tool 時可用。

**execute.context.workflow** (`WorkflowToolExecutionContext`): Workflow 特定 context（state、setState、suspend 等）

**execute.context.mcp** (`MCPToolExecutionContext`): MCP 特定 context（elicitation 等）

**execute.context.observe** (`ToolObserve`): Observability helper，可從 Tool 的 execute 函式內記錄 child span 與結構化 log。此值一律提供；沒有作用中的 tracing context 時，span 會直接執行函式，而 log 不會執行任何操作。

**onInputStart** (`function`): Tool 呼叫的輸入串流開始時叫用的選填 callback。Signature：(options: ToolCallOptions) => void | PromiseLike\<void>。

**onInputDelta** (`function`): 輸入文字串流傳入時，為每個增量區塊叫用的選填 callback。Signature：({ inputTextDelta, ...options }: { inputTextDelta: string } & ToolCallOptions) => void | PromiseLike\<void>。

**onInputAvailable** (`function`): 完整 Tool 輸入可用且已解析時叫用的選填 callback。Signature：({ input, ...options }: { input: TSchemaIn } & ToolCallOptions) => void | PromiseLike\<void>。

**onOutput** (`function`): Tool 成功執行並回傳輸出後叫用的選填 callback。Signature：({ output, toolName, ...options }: { output: TSchemaOut; toolName: string } & Omit\<ToolCallOptions, 'messages'>) => void | PromiseLike\<void>。

`mastra` 與 `mcpMetadata` 等由 runtime 填入的欄位會出現在來源型別中，但由 Mastra 或 MCP adapter 設定。一般使用 `createTool()` 時不需要設定這些欄位。

## 回傳值

`createTool()` 函式會回傳 `Tool` 物件。

**Tool** (`object`): 代表已定義 Tool 的物件，可直接加入 Agent。

## 定義 schema

你可以使用任何支援 [Standard JSON Schema](https://standardschema.dev/json-schema) 的函式庫定義 Tool 的 `inputSchema` 與 `outputSchema`，包括 [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 輸入的範例

若要讓 Mastra 要求支援此功能的模型 Provider 產生完全符合 Tool schema 的引數，請設定 `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 會將 `strict: true` 轉送至支援嚴格 Tool 呼叫的 model adapter。不支援此功能的 adapter 會忽略此選項。

## 使用 `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'`
- `type: 'content'`，並包含 `text`、`image-url`、`image-data`、`file-url`、`file-data`、`file-id`、`image-file-id` 或 `custom` 等部分

## 使用 `transform` 的範例

若 Tool 應保留原始輸入或輸出供 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 payload 套用 `display` transform，並對使用者可見的 transcript 訊息套用 `transcript` transform。

## 使用 MCP annotation 的範例

透過 MCP（Model Context Protocol）公開 Tool 時，你可以加入 annotation 來說明 Tool 行為，並自訂 client 顯示 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 lifecycle hook

Tool 支援 lifecycle hook，讓你監控 Tool 執行的不同階段並做出回應。這些 hook 特別適合用於 logging、分析、驗證與串流期間的即時更新。

下列範例示範設定所有 lifecycle hook 的 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}`)
  },
})
```

### 可用的 hook

#### `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
  },
})
```

### Hook 執行順序

一般串流 Tool 呼叫會依下列順序叫用 hook：

1. **onInputStart**：輸入串流開始
2. **onInputDelta**：區塊抵達時叫用多次
3. **onInputAvailable**：解析並驗證完整輸入
4. 執行 Tool 的 **execute** 函式
5. **onOutput**：Tool 已成功完成

### Hook 參數

Hook callback 會收到下列由來源型別支援的參數結構：

- `onInputStart`：接收 `ToolCallOptions`，包括 `toolCallId`、`messages` 與 `abortSignal` 等欄位。
- `onInputDelta`：接收 `{ inputTextDelta: string } & ToolCallOptions`。
- `onInputAvailable`：接收 `{ input: TSchemaIn } & ToolCallOptions`，其中 `input` 的型別來自 `inputSchema`。
- `onOutput`：接收 `{ output: TSchemaOut; toolName: string } & Omit<ToolCallOptions, 'messages'>`，其中 `output` 的型別來自 `outputSchema`。此 hook 不會接收 `messages`。

### 錯誤處理

系統會自動攔截並記錄 hook 錯誤，但不會阻止 Tool 繼續執行。若 hook 擲回錯誤，系統會將其記錄到主控台，但 Tool 呼叫不會失敗。

## MCP Tool annotation

透過 Model Context Protocol（MCP）公開 Tool 時，你可以提供描述 Tool 行為的 annotation。這些 annotation 可協助 OpenAI Apps SDK 等 MCP client 了解如何呈現與處理 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 只會執行附加式更新。此提示可協助 client 判斷是否應要求確認。預設為 true。

**idempotentHint** (`boolean`): 若為 true，使用相同引數重複呼叫 Tool 不會對環境產生額外影響。此提示表示等冪行為。預設為 false。

**openWorldHint** (`boolean`): 若為 true，此 Tool 可能與外部實體的「開放世界」（例如網頁搜尋、外部 API）互動。若為 false，Tool 的作用域封閉且已完整定義。預設為 true。

這些 annotation 遵循 [MCP 規範](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#tool-annotations)，並會在透過 MCP 列出 Tool 時原樣傳遞。

## 相關內容

- [MCP 概覽](https://mastra.zisheng.pro/zh-TW/docs/mcp/overview)
- [搭配 Agent 使用 Tool](https://mastra.zisheng.pro/zh-TW/docs/agents/using-tools)
- [Agent 核准](https://mastra.zisheng.pro/zh-TW/docs/agents/agent-approval)
- [Tool 串流](https://mastra.zisheng.pro/zh-TW/docs/agents/using-tools)
- [Request Context](https://mastra.zisheng.pro/zh-TW/docs/server/request-context)