Agent Tool Builder

ツールは AI エージェントが世界と相互作用する手段です。よく設計されたツールは、正常に機能するエージェントと幻覚を見たり、静かに失敗したり、必要な 10 倍以上のトークンを消費するエージェントの違いです。

このスキルはスキーマからエラーハンドリングまで、ツール設計をカバーしています。JSON Schema のベストプラクティス、LLM に実際に役立つ説明の書き方、検証、および AI ツールの共通言語となりつつある MCP 標準について扱います。

重要な洞察：ツール説明はツール実装よりも重要です。LLM はあなたのコードを見ません - スキーマと説明のみを見ます。

Principles

• 説明の品質 > 実装の品質（LLM の精度向上）
• 20 未満のツールを目指す - 多すぎると混乱を招く
• すべてのツールに明示的なエラーハンドリングが必要 - 静かな失敗はエージェントを毒する
• 文字列を返す、オブジェクトではなく - LLM はテキストを処理する
• 実行前に検証ゲートを設ける - 拒否、修正、またはエスカレーション、決して静かに失敗しない
• ツールを LLM でテストする、単にユニットテストではなく

Capabilities

• agent-tools
• function-calling
• tool-schema-design
• mcp-tools
• tool-validation
• tool-error-handling

Scope

• multi-agent-coordination → multi-agent-orchestration
• agent-memory → agent-memory-systems
• api-design → api-designer
• llm-prompting → prompt-engineering

Tooling

Standards

• JSON Schema - 使用時期：すべてのツール定義 注釈：ツールスキーマの普遍的な形式
• MCP (Model Context Protocol) - 使用時期：再利用可能なクロスプラットフォームツールの構築 注釈：Anthropic のオープン標準、広く採用されている

Frameworks

• Anthropic SDK - 使用時期：Claude ベースのエージェント 注釈：ベータツールランナーはほとんどの複雑性を処理する
• OpenAI Functions - 使用時期：OpenAI ベースのエージェント 注釈：スキーマの確実なコンプライアンスのため strict モードを使用
• Vercel AI SDK - 使用時期：マルチプロバイダーツール処理 注釈：プロバイダー間の違いを抽象化
• LangChain Tools - 使用時期：LangChain ベースのエージェント 注釈：MCP ツールを LangChain フォーマットに変換

Patterns

Tool Schema Design

ツール用の明確で曖昧でない JSON Schema を作成する

使用時期：エージェント用の新しいツールを定義するときは

TOOL SCHEMA BEST PRACTICES:

1. 詳細な説明（最も重要）

悪い例 - 曖昧すぎる：
{
  "name": "get_stock_price",
  "description": "Gets stock price",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {"type": "string"}
    }
  }
}

良い例 - 包括的：
{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker
    symbol. The ticker symbol must be a valid symbol for a publicly
    traded company on a major US stock exchange like NYSE or NASDAQ.
    Returns the latest trade price in USD. Use when the user asks
    about current or recent stock prices. Does NOT provide historical
    data, company info, or predictions.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

2. パラメータの説明

すべてのパラメータには以下が必要です：
- それが何か
- 期待されるフォーマット
- 例の値
- エッジケース/制限事項

{
  "location": {
    "type": "string",
    "description": "City and state/country. Format: 'City, State' for US
      (e.g., 'San Francisco, CA') or 'City, Country' for international
      (e.g., 'Tokyo, Japan'). Do not use ZIP codes or coordinates."
  },
  "unit": {
    "type": "string",
    "enum": ["celsius", "fahrenheit"],
    "description": "Temperature unit. Defaults to user's locale if not
      specified. Use 'fahrenheit' for US users, 'celsius' for others."
  }
}

3. 可能な限り Enum を使用する

Enum は LLM を有効な値に制限します：

"priority": {
  "type": "string",
  "enum": ["low", "medium", "high", "critical"],
  "description": "Task priority level"
}

"action": {
  "type": "string",
  "enum": ["create", "read", "update", "delete"],
  "description": "The CRUD operation to perform"
}

4. 必須 vs オプション

何が必須であるかを明確にしてください：

{
  "type": "object",
  "properties": {
    "query": {...},      // 必須
    "limit": {...},      // デフォルト付きオプション
    "offset": {...}      // オプション
  },
  "required": ["query"],
  "additionalProperties": false  // Strict モード
}

Tool with Input Examples

LLM ツール使用法を導くために例を使用する

使用時期：ネストされたオブジェクトまたはフォーマットに敏感な入力を持つ複雑なツール

TOOL USE EXAMPLES (Anthropic Beta Feature):

例は Claude に具体的なパターンを示し、スキーマでは表現できません。
複雑な操作の精度は 72% から 90% に向上します。

{
  "name": "create_calendar_event",
  "description": "Creates a calendar event with optional attendees and reminders",
  "input_schema": {
    "type": "object",
    "properties": {
      "title": {"type": "string", "description": "Event title"},
      "start_time": {
        "type": "string",
        "description": "ISO 8601 datetime, e.g. 2024-03-15T14:00:00Z"
      },
      "duration_minutes": {"type": "integer", "description": "Event duration"},
      "attendees": {
        "type": "array",
        "items": {"type": "string"},
        "description": "Email addresses of attendees"
      }
    },
    "required": ["title", "start_time", "duration_minutes"]
  },
  "input_examples": [
    {
      "title": "Team Standup",
      "start_time": "2024-03-15T09:00:00Z",
      "duration_minutes": 30,
      "attendees": ["alice@company.com", "bob@company.com"]
    },
    {
      "title": "Quick Chat",
      "start_time": "2024-03-15T14:00:00Z",
      "duration_minutes": 15
    },
    {
      "title": "Project Review",
      "start_time": "2024-03-15T16:00:00-05:00",
      "duration_minutes": 60,
      "attendees": ["team@company.com"]
    }
  ]
}

# EXAMPLE DESIGN PRINCIPLES:
# - Use realistic data, not placeholders
# - Show minimal, partial, and full specification patterns
# - Keep concise: 1-5 examples per tool
# - Focus on ambiguous cases

Tool Error Handling

LLM が回復するのに役立つエラーを返す

使用時期：失敗する可能性のあるすべてのツール

ERROR HANDLING BEST PRACTICES:

情報提供的なエラーを返す

悪い例：
{"error": "Failed"}
{"error": true}

良い例：
{
  "error": true,
  "error_type": "not_found",
  "message": "Location 'Atlantis' not found in weather database.
    Please provide a real city name like 'San Francisco, CA'.",
  "suggestions": ["San Francisco, CA", "Los Angeles, CA"]
}

Anthropic Tool Result with Error

{
  "type": "tool_result",
  "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
  "content": "Error: Location 'Atlantis' not found in weather database.
    Please provide a real city name like 'San Francisco, CA'.",
  "is_error": true
}

処理するエラーカテゴリ

1. Input Validation Errors
   - Missing required parameters
   - Invalid format
   - Out of range values

2. External Service Errors
   - API unavailable
   - Rate limited
   - Timeout

3. Business Logic Errors
   - Resource not found
   - Permission denied
   - Conflict/duplicate

4. Internal Errors
   - Unexpected exceptions
   - Data corruption

実装パターン

from dataclasses import dataclass
from typing import Union

@dataclass
class ToolResult:
    success: bool
    content: str
    error_type: str = None
    suggestions: list[str] = None

    def to_response(self) -> dict:
        if self.success:
            return {"content": self.content}
        return {
            "content": f"Error ({self.error_type}): {self.content}",
            "is_error": True
        }

def get_weather(location: str) -> ToolResult:
    # Validate input
    if not location or len(location) < 2:
        return ToolResult(
            success=False,
            content="Location must be at least 2 characters",
            error_type="validation_error"
        )

    try:
        data = weather_api.fetch(location)
        return ToolResult(
            success=True,
            content=f"Temperature: {data.temp}°F, Conditions: {data.conditions}"
        )
    except LocationNotFound:
        return ToolResult(
            success=False,
            content=f"Location '{location}' not found",
            error_type="not_found",
            suggestions=weather_api.suggest_locations(location)
        )
    except RateLimitError:
        return ToolResult(
            success=False,
            content="Weather service rate limit exceeded. Try again in 60 seconds.",
            error_type="rate_limit"
        )
    except Exception as e:
        return ToolResult(
            success=False,
            content=f"Unexpected error: {str(e)}",
            error_type="internal_error"
        )

MCP Tool Pattern

Model Context Protocol を使用したツールの構築

使用時期：再利用可能なクロスプラットフォームツールの作成

MCP TOOL IMPLEMENTATION:

MCP (Model Context Protocol) は Anthropic のオープン標準で、
AI エージェントを外部システムに接続します。一度構築すれば、どこでも使用できます。

Basic MCP Server (TypeScript)

import { Server } from "@modelcontextprotocol/sdk/server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";

const server = new Server({
  name: "weather-server",
  version: "1.0.0"
});

// Define tools
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "get_weather",
      description: "Get current weather for a location. Returns
        temperature, conditions, and humidity. Use for weather
        queries about specific cities.",
      inputSchema: {
        type: "object",
        properties: {
          location: {
            type: "string",
            description: "City and state, e.g. 'San Francisco, CA'"
          },
          unit: {
            type: "string",
            enum: ["celsius", "fahrenheit"],
            default: "fahrenheit"
          }
        },
        required: ["location"]
      }
    }
  ]
}));

// Handle tool calls
server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_weather") {
    try {
      const weather = await fetchWeather(args.location, args.unit);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(weather)
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error: ${error.message}`
          }
        ],
        isError: true
      };
    }
  }

  throw new Error(`Unknown tool: ${name}`);
});

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);

MCP Benefits

- Universal compatibility across LLM providers
- Reusable tool libraries
- Streaming and SSE transport support
- Built-in observability
- Tool access controls

Tool Runner Pattern

自動処理のために SDK ツールランナーを使用する

使用時期：手動管理なしにツールループを構築するとき

TOOL RUNNER (Anthropic SDK Beta):

ツールランナーはツール呼び出しループを自動的に処理します：
- Claude がツールを呼び出すときに実行
- 会話状態を管理
- エラー再試行を処理
- ストリーミングサポートを提供

Python Example

import anthropic
from anthropic import beta_tool

client = anthropic.Anthropic()

@beta_tool
def get_weather(location: str, unit: str = "fahrenheit") -> str:
    '''Get the current weather in a given location.

    Args:
        location: The city and state, e.g. San Francisco, CA
        unit: Temperature unit, either 'celsius' or 'fahrenheit'
    '''
    # Implementation
    return json.dumps({"temperature": "72°F", "conditions": "Sunny"})

@beta_tool
def search_web(query: str) -> str:
    '''Search the web for information.

    Args:
        query: The search query
    '''
    # Implementation
    return json.dumps({"results": [...]})

# Tool runner handles the loop
runner = client.beta.messages.tool_runner(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=[get_weather, search_web],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"}
    ]
)

# Process each message
for message in runner:
    print(message.content[0].text)

# Or just get final result
final = runner.until_done()

TypeScript with Zod

import { Anthropic } from '@anthropic-ai/sdk';
import { betaZodTool } from '@anthropic-ai/sdk/helpers/beta/zod';
import { z } from 'zod';

const anthropic = new Anthropic();

const getWeatherTool = betaZodTool({
  name: 'get_weather',
  description: 'Get the current weather in a given location',
  inputSchema: z.object({
    location: z.string().describe('City and state, e.g. San Francisco, CA'),
    unit: z.enum(['celsius', 'fahrenheit']).default('fahrenheit')
  }),
  run: async (input) => {
    // Type-safe input!
    return JSON.stringify({temperature: '72°F'});
  }
});

const runner = anthropic.beta.messages.toolRunner({
  model: 'claude-sonnet-4-5',
  max_tokens: 1024,
  tools: [getWeatherTool],
  messages: [{ role: 'user', content: "What's the weather in Paris?" }]
});

for await (const message of runner) {
  console.log(message.content[0].text);
}

Parallel Tool Execution

複数のツールを同時に実行する

使用時期：並列で実行できる独立したツール呼び出しのとき

PARALLEL TOOL EXECUTION:

デフォルトでは、Claude は 1 つの応答で複数のツールを呼び出せます。
これにより独立した操作のレイテンシーが大幅に削減されます。

並列結果の処理

# Claude は複数の tool_use ブロックを返します：
response.content = [
    {"type": "text", "text": "I'll check both locations..."},
    {"type": "tool_use", "id": "toolu_01", "name": "get_weather",
     "input": {"location": "San Francisco, CA"}},
    {"type": "tool_use", "id": "toolu_02", "name": "get_weather",
     "input": {"location": "New York, NY"}},
    {"type": "tool_use", "id": "toolu_03", "name": "get_time",
     "input": {"timezone": "America/Los_Angeles"}},
    {"type": "tool_use", "id": "toolu_04", "name": "get_time",
     "input": {"timezone": "America/New_York"}}
]

# 並列で実行
import asyncio

async def execute_tools_parallel(tool_uses):
    tasks = [execute_tool(t) for t in tool_uses]
    return await asyncio.gather(*tasks)

results = await execute_tools_parallel(tool_uses)

# ALL 結果を SINGLE ユーザーメッセージで返す（重要！）
tool_results = [
    {"type": "tool_result", "tool_use_id": "toolu_01", "content": "72°F, Sunny"},
    {"type": "tool_result", "tool_use_id": "toolu_02", "content": "45°F, Cloudy"},
    {"type": "tool_result", "tool_use_id": "toolu_03", "content": "2:30 PM PST"},
    {"type": "tool_result", "tool_use_id": "toolu_04", "content": "5:30 PM EST"}
]

# 正解：1 つのメッセージにすべての結果
messages.append({"role": "user", "content": tool_results})

# 間違い：別のメッセージ（並列実行パターンを破壊）
# messages.append({"role": "user", "content": [tool_results[0]]})
# messages.append({"role": "user", "content": [tool_results[1]]})

並列ツール使用を促奨

システムプロンプトに追加：
"For maximum efficiency, whenever you need to perform multiple
independent operations, invoke all relevant tools simultaneously
rather than sequentially."

並列を無効化（必要な場合）

response = client.messages.create(
    model="claude-sonnet-4-5",
    tools=tools,
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages
)

Validation Checks

ツール説明は包括的である必要があります

重要度：WARNING

ツール説明は最低 100 文字である必要があります

メッセージ：ツール説明が短すぎます。使用時期、パラメータ、戻り値について詳細を追加します。

パラメータの説明が必須

重要度：WARNING

すべてのパラメータに説明が必要です

メッセージ：パラメータの説明がありません。それが何であるか、期待されるフォーマットを説明してください。

スキーマは必須フィールドを指定する必要があります

重要度：INFO

どのフィールドが必須であるかを明示的に定義してください

メッセージ：スキーマが必須フィールドを指定していません。'required' 配列を追加してください。

ツール実装にはエラーハンドリングが必要です

重要度：ERROR

ツール関数は例外を処理する必要があります

メッセージ：try/except ブロックなしのツール関数。エラーハンドリングを追加してください。

エラー結果は is_error フラグが必要です

重要度：WARNING

エラーを返すときは、is_error を true に設定します

メッセージ：is_error フラグなしのエラー結果。'is_error': true を追加してください。

ツールは文字列を返す必要があります

重要度：WARNING

dict/object ではなく JSON 文字列を返す

メッセージ：dict の代わりに dict を返しています。json.dumps() または JSON.stringify() を使用してください。

ツールは入力を検証する必要があります

重要度：WARNING

LLM が提供する入力を実行前に検証してください

メッセージ：見える入力検証なしのツール関数。実行前に検証してください。

SQL クエリはパラメータ化を使用する必要があります

重要度：ERROR

ユーザー入力を SQL に連結しないでください

メッセージ：SQL クエリが文字列連結を使用しているようです。パラメータ化クエリを使用してください。

外部呼び出しはタイムアウトが必要です

重要度：WARNING

HTTP リクエストと外部呼び出しはタイムアウトを持つ必要があります

メッセージ：タイムアウトなしの外部 API 呼び出し。タイムアウトパラメータを追加してください。

MCP ツールは inputSchema を持つ必要があります

重要度：ERROR

すべての MCP ツールは inputSchema が必須です

メッセージ：MCP ツール定義に inputSchema がありません。

Collaboration

Delegation Triggers

• user needs to coordinate multiple tools -> multi-agent-orchestration (エージェント間のツール調整)
• user needs persistent memory between tool calls -> agent-memory-systems (ツール呼び出し間の状態管理)
• user building voice agent tools -> voice-agents (オーディオ/音声固有のツール要件)
• user needs computer control tools -> computer-use-agents (デスクトップオートメーションツール)
• user wants to test their tools -> agent-evaluation (ツール検証とテスト)

Related Skills

Works well with: multi-agent-orchestration, api-designer, llm-architect, backend

When to Use

• ユーザーが言及または暗示：agent tool
• ユーザーが言及または暗示：function calling
• ユーザーが言及または暗示：tool schema
• ユーザーが言及または暗示：tool design
• ユーザーが言及または暗示：mcp server
• ユーザーが言及または暗示：mcp tool
• ユーザーが言及または暗示：tool use
• ユーザーが言及または暗示：build tool for agent
• ユーザーが言及または暗示：define function
• ユーザーが言及または暗示：input_schema
• ユーザーが言及または暗示：tool_use
• ユーザーが言及または暗示：tool_result

Limitations

• 上記で説明されたスコープに明確に一致する場合のみこのスキルを使用してください。
• 出力を環境固有の検証、テスト、または専門家のレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全境界、または成功基準が欠落している場合は停止して説明を求めてください。