---

name: agent-tool-builder description: 工具是 AI 代理与世界交互的方式。设计良好的工具是代理正常工作与产生幻觉、静默失败或消耗 10 倍多余 token 之间的区别。此技能涵盖从 schema 到错误处理的工具设计。 risk: unknown source: vibeship-spawner-skills (Apache 2.0) date_added: 2026-02-27

代理工具构建器

工具是 AI 代理与世界交互的方式。设计良好的工具是代理正常工作与产生幻觉、静默失败或消耗 10 倍多余 token 之间的区别。

此技能涵盖从 schema 到错误处理的工具设计。JSON Schema 最佳实践、真正帮助 LLM 的描述编写、验证，以及正在成为 AI 工具通用语言的新兴 MCP 标准。

关键洞察：工具描述比工具实现更重要。LLM 永远看不到你的代码——它只看到 schema 和描述。

原则

• 描述质量 > 实现质量（对 LLM 准确性而言）
• 目标少于 20 个工具——更多会造成混乱
• 每个工具需要显式错误处理——静默失败会毒害代理
• 返回字符串，而非对象——LLM 处理文本
• 执行前的验证关卡——拒绝、修复或升级，永不静默失败
• 用 LLM 测试工具，而非仅用单元测试

能力

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

范围

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

工具

标准

• JSON Schema - 何时：所有工具定义 注意：工具 schema 的通用格式
• MCP（Model Context Protocol）- 何时：构建可复用的跨平台工具 注意：Anthropic 的开放标准，广泛采用

框架

• Anthropic SDK - 何时：基于 Claude 的代理 注意：Beta tool runner 处理大部分复杂性
• OpenAI Functions - 何时：基于 OpenAI 的代理 注意：使用 strict 模式保证 schema 合规
• Vercel AI SDK - 何时：多提供商工具处理 注意：抽象提供商之间的差异
• LangChain Tools - 何时：基于 LangChain 的代理 注意：将 MCP 工具转换为 LangChain 格式

模式

工具 Schema 设计

为工具创建清晰、无歧义的 JSON Schema

何时使用：为代理定义任何新工具

工具 SCHEMA 最佳实践：

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. 参数描述

每个参数需要：

• 它是什么
• 期望的格式
• 有效值的示例
• 边界情况或限制

3. 错误处理模式

def tool_with_error_handling(params):
    # 验证输入
    if not params.get("ticker"):
        return "Error: ticker is required. Provide a stock symbol like AAPL or GOOGL."
    
    # 尝试执行
    try:
        result = fetch_price(params["ticker"])
        return f"The current price of {params['ticker']} is ${result:.2f} USD."
    except TickerNotFound:
        return f"Error: '{params['ticker']}' is not a valid ticker symbol."
    except RateLimited:
        return "Error: Rate limited. Please wait 60 seconds before retrying."

4. MCP 工具模式

server.tool("get_stock_price", {
  description: "Retrieves current stock price for a US-listed ticker symbol",
  inputSchema: {
    type: "object",
    properties: {
      ticker: {
        type: "string",
        description: "Stock ticker symbol (e.g., AAPL, GOOGL)"
      }
    },
    required: ["ticker"]
  }
}, async ({ ticker }) => {
  const price = await fetchPrice(ticker);
  return { content: [{ type: "text", text: `${ticker}: $${price}` }] };
});