Thiết kế Tool cho AI: Tên, mô tả, parameters

Định nghĩa

Tool design là quá trình định nghĩa giao diện (interface) giữa AI và hệ thống bên ngoài — bao gồm tên hàm (function name), mô tả (description) và parameters — để Large Language Model (LLM) có thể quyết định chính xác khi nào cần gọi tool và truyền đúng dữ liệu.

Giải thích chi tiết

Tên tool: Động từ trước danh từ, dùng snake_case

AI đọc tên tool đầu tiên để quyết định có nên gọi hay không. Tên phải là động từ hành động rõ ràng, mô tả chính xác những gì tool sẽ thực hiện.

• ❌ weather_data — danh từ, AI không biết hành động là gì
• ❌ getWeather — camelCase không nhất quán với ecosystem Python/JSON
• ✅ get_current_weather — snake_case rõ ràng, động từ get + đối tượng current_weather

Quy tắc vàng: Bắt đầu bằng động từ mạnh (get, search, create, update, delete, calculate) và tránh động từ mơ hồ như process, handle, manage.

Description: Câu đầu tiên quyết định 80%

AI không đọc toàn bộ description dài dòng. Câu đầu tiên phải trả lời hai câu hỏi: "Tool này làm gì?" và "Khi nào thì dùng?".

Pattern hiệu quả:

Use this tool to [hành động cụ thể] when [điều kiện rõ ràng]. 
[Thêm giới hạn nếu cần: Do not use when...]

Ví dụ tốt:

"Use this tool to retrieve real-time weather data when the user asks about current conditions in a specific location. Only use when the user provides a city name or coordinates."

Ví dụ tệ:

"This is a weather tool."

Parameters: Schema chặt chẽ, type rõ ràng

JSON Schema là "ngôn ngữ hợp đồng" giữa AI và hệ thống. Thiết kế schema cần:

• Type cụ thể: string, number, boolean, array, object — không dùng any hoặc để trống
• Enum cho lựa chọn hữu hạn: Nếu chỉ có 3 loại ưu tiên, dùng "enum": ["high", "medium", "low"] thay vì để AI tự đoán
• Description từng field: Giải thích ý nghĩa business, không chỉ lặp lại tên field. Thay vì "the email", hãy viết "Recipient email address in standard format (e.g., user@company.com)"

Optional vs Required: Giảm bớt cognitive load

Không nên để tất cả parameters là optional. Nếu AI không biết field nào quan trọng, nó sẽ hallucinate hoặc bỏ trống những gì bạn cần.

• required: Những field không có thì tool chạy sai hoặc vô nghĩa
• optional: Chỉ dành cho field có default value hợp lý, hoặc thông tin bổ sung không bắt buộc

Ví dụ: Tool send_email thì to, subject, body là required; priority có thể optional với default "normal".

Multi-provider: OpenAI vs Anthropic

Mặc dù syntax JSON Schema tương tự, có khác biệt implementation:

• OpenAI: Dùng functions array trong payload, mỗi function có name, description, parameters
• Anthropic: Dùng tools array, schema tương tự nhưng có thêm tool_choice để ép buộc tool cụ thể

Tuy nhiên, principles thiết kế tên, description và parameters giống nhau 90% — bạn có thể dùng chung schema cho cả hai platform.

Ví dụ thực tế

Tìm kiếm sản phẩm (E-commerce)

{
  "name": "search_products",
  "description": "Search the product catalog when the user wants to find items to buy or check availability. Use this for queries about price, stock, or features. Do not use for general knowledge questions about products not in our catalog.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search keywords describing what the user wants, e.g., 'wireless noise-canceling headphones'"
      },
      "max_price": {
        "type": "number",
        "description": "Maximum price filter in USD. Only include if user mentions a specific budget limit."
      },
      "category": {
        "type": "string",
        "enum": ["electronics", "clothing", "home", "sports"],
        "description": "Product category to narrow search results"
      },
      "in_stock_only": {
        "type": "boolean",
        "default": false,
        "description": "If true, only return items currently available for immediate shipping"
      }
    },
    "required": ["query"]
  }
}

Điểm hay: query là duy nhất required — AI có thể tìm kiếm rộng ngay cả khi khách chưa rõ ràng. max_price optional vì không phải lúc nào cũng có ngân sách cụ thể.

Gửi email tự động

{
  "name": "send_email",
  "description": "Send an email to external recipients. Only use when the user explicitly requests to send a message or confirms they want to email someone. Always confirm the recipient address with the user if unclear.",
  "parameters": {
    "type": "object",
    "properties": {
      "to": {
        "type": "string",
        "format": "email",
        "description": "Recipient email address. Must be a valid email format."
      },
      "subject": {
        "type": "string",
        "description": "Email subject line - keep concise under 100 characters"
      },
      "body": {
        "type": "string",
        "description": "Main content of the email. Should be professional and include greeting/closing."
      },
      "cc": {
        "type": "array",
        "items": {"type": "string", "format": "email"},
        "description": "Optional CC recipients"
      },
      "priority": {
        "type": "string",
        "enum": ["low", "normal", "high"],
        "default": "normal",
        "description": "Email priority level"
      }
    },
    "required": ["to", "subject", "body"]
  }
}

Điểm hay: Description có guardrail "Only use when..." ngăn AI tự động gửi email mỗi khi người dùng nhắc đến từ "email". cc là array cho phép nhiều người, nhưng optional.

Tính toán chính xác

{
  "name": "calculate",
  "description": "Perform precise mathematical calculations when the user asks for numerical results or comparisons. Use this instead of computing mentally for accuracy, especially with large numbers, percentages, or complex formulas. Always use for financial calculations.",
  "parameters": {
    "type": "object",
    "properties": {
      "expression": {
        "type": "string",
        "description": "Mathematical expression to evaluate in standard notation, e.g., '15 * 23.5 + 100' or '(5000 * 0.15) / 12'"
      },
      "precision": {
        "type": "integer",
        "enum": [0, 2, 4],
        "default": 2,
        "description": "Number of decimal places in result. Use 0 for integers, 2 for currency, 4 for scientific."
      }
    },
    "required": ["expression"]
  }
}

Điểm hay: Description ép buộc dùng tool cho tính toán tài chính, giải quyết vấn đề LLM thường tính sai số học. precision dùng enum hạn chế lựa chọn hợp lý.

Ứng dụng

Developer xây dựng chatbot hỗ trợ khách hàng

Khi xây dựng chatbot tra cứu đơn hàng, thiết kế tool check_order_status với description rõ ràng "Only use when user provides an order ID or email associated with the order" giúp AI không cố gắng đoán mã đơn hàng khi khách chưa cung cấp. Điều này giảm 70% lỗi hallucination trong production.

Product Manager thiết kế tính năng AI

Thiết kế tool book_meeting với parameters duration_minutes dùng enum [15, 30, 60, 90] thay vì number tự do giúp kiểm soát scope sản phẩm — AI không thể đặt cuộc họp 999 phút hay 3 phút vì schema giới hạn. Đây là cách dùng kỹ thuật để ép buộc business rule.

Doanh nghiệp tích hợp API nội bộ

Khi expose internal CRM hoặc ERP cho AI, đặt tên create_crm_ticket thay vì api_post_v2 giúp AI hiểu ngữ cảnh nghiệp vụ, tránh gọi nhầm endpoint khi người dùng hỏi về "tạo ticket". Description nên ghi rõ "Use when customer reports a technical issue requiring follow-up" để phân biệt với create_sales_lead.

So sánh

Kết luận: Tool design không chỉ là kỹ thuật — đó là product design. Một tool tốt giúp AI ra quyết định đúng ngay từ đầu, giảm thiểu validation phức tạp sau khi AI đã gọi. Chi phí viết description rõ ràng chính là đầu tư vào độ chính xác của toàn bộ hệ thống.

Bài viết liên quan

Cùng cụm

Đọc tiếp