为 AI Agent 编写高质量工具 (Tools) 的最佳实践

server.tool(
  "get_sales_summary",
  // 四要素：做什么 + 何时用 + 何时不用 + 返回什么
  `Return an approved sales summary for a named region and date range.
   Use this for aggregate reporting, not arbitrary database exploration.
   The server applies tenant, row, query, and result-size policy.
   Returns a bounded summary with an optional next cursor.`,
  {
    region: z.enum(["APAC", "EMEA", "AMER"]),
    from: z.string().date(),
    to: z.string().date()
  },
  async ({ region, from, to }) => { /* ... */ }
);

// 工具 A
"Search documents by keyword. Use for full-text search across all documents. "
+ "For filtering by metadata (date, author, tag), use filter_documents instead."

// 工具 B
"Filter documents by metadata fields (date range, author, tags). "
+ "For keyword-based content search, use search_documents instead."

const schema = {
  format: z.enum(["json", "csv", "xml"])
    .describe("Output format. Must be one of: json, csv, xml"),
  
  // 而不是
  format: z.string()
    .describe("Output format like json, csv, etc.")
};

const dateRangeSchema = {
  startDate: z.string()
    .describe("Start date in ISO 8601 format (YYYY-MM-DD). Example: 2026-01-15"),
  maxResults: z.number()
    .min(1).max(100)
    .describe("Maximum number of results to return. Default: 10, Max: 100")
};

const searchSchema = {
  query: z.string().describe("Search query - required"),
  page: z.number().optional().default(1)
    .describe("Page number for pagination. Optional, defaults to 1"),
  includeArchived: z.boolean().optional().default(false)
    .describe("Whether to include archived results. Optional, defaults to false")
};

// 差：深度嵌套
const nestedSchema = {
  config: {
    database: {
      connection: { host: "string", port: "number" },
      query: { table: "string", filters: "object" }
    }
  }
};

// 好：扁平化
const flatSchema = {
  dbHost: z.string().describe("Database host address"),
  dbPort: z.number().describe("Database port number"),
  table: z.string().describe("Target table name"),
  filterColumn: z.string().optional().describe("Column name to filter by"),
  filterValue: z.string().optional().describe("Value to filter for")
};

// 成功响应
const successResponse = {
  content: [{
    type: "text",
    text: JSON.stringify({
      success: true,
      data: { /* 业务数据 */ },
      metadata: { totalCount: 42, executionTimeMs: 123 }
    })
  }]
};

// 错误响应
const errorResponse = {
  content: [{
    type: "text",
    text: JSON.stringify({
      success: false,
      error: {
        code: "INVALID_DATE_RANGE",
        message: "The end date must not precede the start date.",
        suggestion: "Provide an ISO date range with from <= to."
      }
    })
  }],
  isError: true
};

const handleSalesSummary = async ({ region, from, to, cursor }) => {
  const page = await reports.getSalesSummary({ region, from, to, cursor });
  
  return {
    content: [{
      type: "text",
      text: JSON.stringify({
        results: page.rows,
        hasMore: page.nextCursor !== null,
        nextCursor: page.nextCursor
      })
    }]
  };
};

const handleTool = async (params) => {
  try {
    // 业务逻辑
    const result = await businessLogic(params);
    return { content: [{ type: "text", text: JSON.stringify(result) }] };
  } catch (error) {
    // 根据错误类型返回可操作的信息
    if (error.code === 'ENOENT') {
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            success: false,
            error: "FILE_NOT_FOUND",
            message: `File '${params.path}' does not exist.`,
            suggestion: "Check the file path. Use the list_files tool to see available files in the directory.",
            retryable: false
          })
        }],
        isError: true
      };
    }
    
    // 兜底处理
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          success: false,
          error: "INTERNAL_ERROR",
          message: "An unexpected error occurred. This may be a temporary issue.",
          retryable: true
        })
      }],
      isError: true
    };
  }
};

import pathModule from "node:path";

const deleteFile = async ({ path: requestedPath }) => {
  // Schema 只能约束类型，业务规则需要手动校验
  const normalizedPath = pathModule.resolve(ALLOWED_ROOT, requestedPath);
  const relativePath = pathModule.relative(ALLOWED_ROOT, normalizedPath);
  
  // 防止路径穿越攻击
  if (relativePath.startsWith('..') || pathModule.isAbsolute(relativePath)) {
    return {
      content: [{ type: "text", text: "Access denied: path is outside the allowed directory." }],
      isError: true
    };
  }
  
  // 防止删除关键文件
  const PROTECTED_PATTERNS = ['.env', 'package.json', '.git'];
  if (PROTECTED_PATTERNS.some(p => normalizedPath.includes(p))) {
    return {
      content: [{ type: "text", text: "This file is protected and cannot be deleted." }],
      isError: true
    };
  }
  
  // 执行删除
  await fs.unlink(normalizedPath);
  return { content: [{ type: "text", text: `Deleted: ${normalizedPath}` }] };
};

server.tool(
  "delete_database_table",
  "Permanently delete a database table and all its data. This action is IRREVERSIBLE.",
  {
    tableName: z.string().describe("Name of the table to delete"),
    confirmPhrase: z.literal("I understand this is irreversible")
      .describe("You must pass exactly 'I understand this is irreversible' to confirm")
  },
  async ({ tableName, confirmPhrase }) => {
    // 文本只是用户意图信号；真正的授权、资源检查和一次性审批在服务端完成
    const approved = await approvalService.consume({
      action: "delete_database_table",
      resource: tableName,
      confirmation: confirmPhrase
    });
    if (!approved) {
      return { content: [{ type: "text", text: "Approval required." }], isError: true };
    }
    await db.dropTable(tableName);
    return { content: [{ type: "text", text: `Table '${tableName}' has been permanently deleted.` }] };
  }
);

const createOrder = async ({ orderId, items }) => {
  // 幂等键：相同的 orderId 只会创建一次订单
  const existing = await db.orders.findOne({ orderId });
  if (existing) {
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          success: true,
          data: existing,
          note: "Order already exists. Returning existing order."
        })
      }]
    };
  }
  
  const newOrder = await db.orders.create({ orderId, items });
  return {
    content: [{
      type: "text",
      text: JSON.stringify({ success: true, data: newOrder })
    }]
  };
};

describe('get_sales_summary tool', () => {
  it('should return results for valid query', async () => {
    const result = await summaryHandler({ region: 'APAC', from: '2026-01-01', to: '2026-03-31' });
    expect(result.content[0].text).toContain('"success":true');
  });

  it('should return error for an invalid date range', async () => {
    const result = await summaryHandler({ region: 'APAC', from: '2026-04-01', to: '2026-01-01' });
    expect(result.isError).toBe(true);
    expect(result.content[0].text).toContain('INVALID_DATE_RANGE');
  });

  it('should return a bounded page', async () => {
    const result = await summaryHandler({ region: 'APAC', from: '2026-01-01', to: '2026-03-31' });
    const parsed = JSON.parse(result.content[0].text);
    expect(parsed.hasMore).toBeDefined();
    expect(parsed.nextCursor).toBeDefined();
  });
});

describe('Schema validation', () => {
  it('should reject missing required fields', () => {
    const schema = toolDefinitions['get_sales_summary'].inputSchema;
    const result = schema.safeParse({});
    expect(result.success).toBe(false);
  });

  it('should accept valid enum values', () => {
    const schema = toolDefinitions['get_sales_summary'].inputSchema;
    const result = schema.safeParse({ region: 'APAC', from: '2026-01-01', to: '2026-03-31' });
    expect(result.success).toBe(true);
  });
});