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

server.tool(
  "query_database",
  // 四要素：做什么 + 何时用 + 何时不用 + 返回什么
  `Execute a read-only SQL query against the analytics database.
   Use this tool when the user asks for data insights, statistics,
   or specific records from the database.
   Do NOT use this for modifying data - use update_database instead.
   Returns: JSON array of matching rows, or an error message
   if the query is invalid.`,
  { query: z.string().describe("A valid SELECT SQL statement") },
  async ({ query }) => { /* ... */ }
);

// 工具 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."

{
  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.")
}

{
  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")
}

{
  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")
}

// 差：深度嵌套
{
  config: {
    database: {
      connection: { host: string, port: number },
      query: { table: string, filters: {...} }
    }
  }
}

// 好：扁平化
{
  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")
}

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

// 错误响应
{
  content: [{
    type: "text",
    text: JSON.stringify({
      success: false,
      error: {
        code: "INVALID_QUERY",
        message: "SQL syntax error near 'FORM'",
        suggestion: "Did you mean 'FROM'? Check your SQL syntax."
      }
    })
  }],
  isError: true
}

const handleQuery = async ({ query, maxResults = 10 }) => {
  const allResults = await db.execute(query);
  const truncated = allResults.slice(0, maxResults);
  
  return {
    content: [{
      type: "text",
      text: JSON.stringify({
        results: truncated,
        totalCount: allResults.length,
        hasMore: allResults.length > maxResults,
        hint: allResults.length > maxResults
          ? `Showing ${maxResults} of ${allResults.length} results. Use 'page' parameter to see more.`
          : undefined
      })
    }]
  };
};

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
    };
  }
};

const deleteFile = async ({ path }) => {
  // Schema 只能约束类型，业务规则需要手动校验
  const normalizedPath = path.normalize(path);
  
  // 防止路径穿越攻击
  if (normalizedPath.includes('..') || !normalizedPath.startsWith(ALLOWED_ROOT)) {
    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 }) => {
    // confirmPhrase 的 literal 类型强制 LLM 明确传入确认文本
    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('query_database tool', () => {
  it('should return results for valid query', async () => {
    const result = await queryHandler({ query: 'SELECT * FROM users LIMIT 5' });
    expect(result.content[0].text).toContain('"success":true');
  });

  it('should return error for invalid SQL', async () => {
    const result = await queryHandler({ query: 'INVALID SQL' });
    expect(result.isError).toBe(true);
    expect(result.content[0].text).toContain('INVALID_QUERY');
  });

  it('should respect maxResults limit', async () => {
    const result = await queryHandler({ query: 'SELECT * FROM users', maxResults: 2 });
    const parsed = JSON.parse(result.content[0].text);
    expect(parsed.results.length).toBeLessThanOrEqual(2);
    expect(parsed.hasMore).toBeDefined();
  });
});

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

  it('should accept valid enum values', () => {
    const schema = toolDefinitions['export_data'].inputSchema;
    const result = schema.safeParse({ format: 'csv', query: 'SELECT 1' });
    expect(result.success).toBe(true);
  });
});