Bài 4 — Định nghĩa Tool/Function cho model gọi đúng

Model chỉ gọi tool tốt như cách bạn mô tả nó. Một tool schema mơ hồ khiến model gọi nhầm tool, điền sai tham số, hoặc gọi khi không cần. Bài này dạy thiết kế định nghĩa tool để model "nhìn phát hiểu ngay".

Cấu trúc một tool definition

Mỗi tool gồm 3 phần model dựa vào để quyết định:

• name: động từ + danh từ rõ ràng, ví dụ get_weather, create_invoice, search_flights.
• description: mô tả KHI NÀO dùng và KHI NÀO KHÔNG dùng. Đây là phần quan trọng nhất.
• parameters: JSON Schema cho tham số (áp dụng mọi nguyên tắc ở Bài 2).

{
  "name": "search_flights",
  "description": "Tìm chuyến bay giữa hai thành phố cho một ngày cụ thể. Dùng khi người dùng muốn xem/đặt vé máy bay. KHÔNG dùng cho tàu, xe khách, hay hỏi giá chung chung.",
  "parameters": {
    "type": "object",
    "properties": {
      "origin": { "type": "string", "description": "Mã sân bay IATA, vd HAN" },
      "destination": { "type": "string", "description": "Mã sân bay IATA, vd SGN" },
      "date": { "type": "string", "format": "date", "description": "Ngày bay YYYY-MM-DD" },
      "passengers": { "type": "integer", "minimum": 1, "maximum": 9 }
    },
    "required": ["origin", "destination", "date"],
    "additionalProperties": false
  }
}

Các bước thiết kế bộ tool

• Một tool = một việc rõ ràng. Tránh tool "đa năng" nhận action string rồi tự phân nhánh — model khó chọn tham số đúng.
• Viết description theo công thức: [Làm gì] + [Dùng khi nào] + [KHÔNG dùng khi nào] + [ví dụ nếu cần].
• Ràng buộc tham số bằng schema như Bài 2: enum, format, min/max.
• Đặt tên phân biệt rõ giữa các tool dễ nhầm (ví dụ get_order_status vs cancel_order).
• Giới hạn số lượng tool hiển thị mỗi lần: quá nhiều tool (>15-20) làm model rối và giảm độ chính xác. Nhóm/lọc theo ngữ cảnh nếu cần.
• Cho phép model KHÔNG gọi tool: nếu câu hỏi chỉ cần trả lời thường, đừng ép nó gọi.

Điều khiển hành vi gọi tool (tool_choice)

• auto: model tự quyết gọi hay không (mặc định, linh hoạt nhất).
• required/any: bắt buộc gọi ít nhất một tool (dùng khi bạn chắc chắn cần hành động).
• Ép tên tool cụ thể: buộc gọi đúng một tool (dùng cho flow cố định, ví dụ luôn phải extract dữ liệu).

Khung tư duy: tool như API cho một đồng nghiệp mới

Hãy viết description như thể giải thích cho nhân viên mới chưa biết gì về hệ thống. Nếu họ đọc xong vẫn phân vân "dùng khi nào", model cũng sẽ phân vân.

Checklist một tool tốt

• [ ] Tên là động từ + danh từ, không mơ hồ?
• [ ] Description nêu rõ dùng khi nào VÀ không dùng khi nào?
• [ ] Mỗi tham số có description + ràng buộc miền?
• [ ] Tool làm đúng một việc, không đa năng?
• [ ] Đã cân nhắc số lượng tool tổng thể?

Sai lầm thường gặp

• Description sơ sài kiểu "Tìm chuyến bay". Thiếu ranh giới khiến model gọi cả khi người dùng hỏi về tàu hỏa.
• Tool đa năng nhận action string. Gộp create/update/delete vào một tool làm model khó điền tham số và dễ chọn sai nhánh.
• Tên tool na ná nhau (update_user, update_profile) không giải thích khác biệt.
• Quá nhiều tool cùng lúc. Độ chính xác chọn tool giảm mạnh khi danh sách phình to.
• Ép required gọi tool cho mọi câu, khiến model gọi tool vô nghĩa cho câu chào hỏi.

Đã có tool định nghĩa tốt, bài tiếp theo ta khai thác sức mạnh gọi NHIỀU tool cùng lúc để tăng tốc agent.