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

# Tools

ファイルベース Agent は、`tools/` ディレクトリの直下にある `.ts` ファイルと `.js` ファイルから Tool を検出します。検出された各ファイルはビルド時に import されます。ファイルは [`createTool()`](https://mastra.zisheng.pro/ja/reference/tools/create-tool) の結果を default export する必要があり、拡張子を除いたファイル名が Model から呼び出せる Tool Key になります。

ファイルベースの規約については、このページを参照してください。Tool の Schema、実行オプション、出力形式の調整、承認オプションについては、[`createTool()` リファレンス](https://mastra.zisheng.pro/ja/reference/tools/create-tool)を参照してください。

## クイックスタート

`tools/` 配下に Tool ごとのファイルを1つずつ配置します。このファイルは `get_weather` として Agent に公開されます。

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

export default createTool({
  id: 'get_weather',
  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' }
  },
})
```

## Tool の整理

Tool ごとに1つのファイルを使用します。Model に実行させる Action に合わせてファイル名を付けてください。

- `get_weather.ts`、`search_docs.ts`、`create_ticket.ts` のような名前を使用します。
- `helper.ts`、`api.ts`、`utils.ts` のような曖昧な名前は避けます。
- テストは `*.test.ts` または `*.spec.ts` として Tool の隣に配置します。これらのファイルは検出時に無視されます。
- 共有 Helper コードは `tools/` の外、または `tools/` 配下でも検出対象の拡張子に一致しないファイルに配置します。

ネストされたディレクトリは Tool として検出されないため、関連する Tool はサブフォルダーではなく、`calendar_create_event.ts` や `calendar_list_events.ts` のように、明確なファイル名 Prefix でグループ化してください。

## Tool のオプション

ファイルベースの規約が制御するのは、Tool の配置場所と登録方法だけです。Tool API は引き続き `createTool()` によって提供されます。

- Model に Tool を呼び出すタイミングを伝えるには、`description` を使用します。
- 構造化された入力と出力には、`inputSchema` と `outputSchema` を使用します。
- `execute` が返す未加工の値とは異なる形式を Model に提示する場合は、`toModelOutput` を使用します。
- Tool の実行前に人間による確認が必要な場合は、`requireApproval` を使用します。

すべてのオプションについては [`createTool()` リファレンス](https://mastra.zisheng.pro/ja/reference/tools/create-tool)を、承認フローについては [Tool の承認](https://mastra.zisheng.pro/ja/docs/harness/agent-controller)を参照してください。

## Runtime の境界

Agent が Tool を呼び出すと、Tool のコードはアプリケーション／Server の Runtime で実行されます。Tool で File System や Shell の分離が必要な場合は、[Workspace](https://mastra.zisheng.pro/ja/reference/file-based-agents/workspace)または Sandbox API を明示的に呼び出してください。

## config との優先順位

検出された Tool は、[`config.ts`](https://mastra.zisheng.pro/ja/reference/file-based-agents/config) 内の `tools` とマージされます。Key が重複した場合は `config.tools` が優先され、警告がログに記録されます。

`config.tools` が関数の場合、関数値の Tool は静的にマージできないため、検出された Tool は警告とともに無視されます。