Thiết kế tool cho AI agent: đừng bọc API, hãy bọc công việc

Cách nhanh nhất để tạo tool cho agent là bọc từng endpoint API sẵn có: list_users, list_events, create_event… Kết quả thường tệ: agent gọi chục lần, đọc hàng trăm bản ghi không cần, nhầm UUID, và hết context trước khi xong việc. Bài viết kỹ thuật Writing effective tools for AI agents của Anthropic (Ken Aizawa, 9/2025) lập luận rằng tool là một loại phần mềm mới: nó là "hợp đồng" giữa hệ thống tất định và một agent không tất định, nên phải được thiết kế cho agent. Bài này tóm tắt quy trình và 5 nguyên tắc, áp dụng được cho cả MCP server lẫn tool trong API.

Quy trình: prototype → eval → để Claude sửa

1. Prototype nhanh: dựng tool (local MCP server hoặc truyền thẳng vào API), tự dùng thử qua Claude Code.
2. Eval bằng task thật: nhiều prompt thực tế, có thể cần hàng chục lần gọi tool. "Hẹn họp với An tuần sau, đính kèm biên bản lần trước, đặt phòng" tốt hơn "tạo sự kiện cho email X". Mỗi task cần cách kiểm tra kết quả.
3. Đo nhiều chỉ số: độ chính xác, thời gian, số lần gọi tool, token, lỗi tool. Gọi lặp thừa là dấu hiệu nên gộp tool.
4. Đọc transcript và để Claude refactor: dán log eval vào Claude Code để nó sửa nhiều tool cùng lúc. Theo bài viết, phần lớn lời khuyên của họ đến từ chính vòng lặp này, có tập test giữ riêng để tránh overfit.

Ví dụ trong bài: Claude cứ tự thêm "2025" vào câu tìm kiếm web; sửa mô tả tool là hết.

5 nguyên tắc thiết kế tool

1. Chọn đúng tool, ít mà chất

Thêm tool không đồng nghĩa với tốt hơn: tool chồng chéo làm agent phân tâm.

2. Đặt namespace

Khi có hàng chục MCP server, gom tool theo tiền tố dịch vụ/tài nguyên: asana_search, jira_search, asana_projects_search. Bài viết ghi nhận tiền tố hay hậu tố cho kết quả khác nhau tuỳ model, nên hãy thử bằng eval.

3. Trả về ngữ cảnh có nghĩa

Ưu tiên name, image_url, file_type hơn uuid, mime_type. Đổi ID khó hiểu thành tên đọc được giúp giảm "bịa". Khi agent vẫn cần ID để gọi tiếp, thêm tham số response_format với hai giá trị "concise"/"detailed". Trong ví dụ Slack của bài, bản chi tiết 206 token, bản gọn 72 token, khoảng một phần ba.

4. Tiết kiệm token

• Phân trang, lọc, chọn khoảng, cắt bớt với mặc định hợp lý. Claude Code giới hạn kết quả tool ở 25.000 token theo mặc định.
• Khi cắt bớt, nói cho agent biết cách thu hẹp tìm kiếm.
• Thông báo lỗi phải hành động được: nói sai ở đâu và ví dụ input đúng, không trả mã lỗi hay stack trace trơ trụi.

5. Viết mô tả tool như hướng dẫn người mới

Mô tả và tên tham số nằm trong context nên ảnh hưởng mạnh tới hành vi. Giải thích định dạng query đặc thù, thuật ngữ nội bộ, quan hệ giữa các tài nguyên. Đặt tên tham số không mơ hồ (user_id thay vì user), dùng schema chặt. Với MCP, dùng annotation để đánh dấu tool có tác động phá huỷ hoặc truy cập bên ngoài.

Rủi ro và lưu ý

• Gộp tool quá tay thành "siêu tool" nhiều chế độ cũng làm agent bối rối; gộp theo quy trình thật của người dùng.
• Eval do chính Claude sinh có thể thiên vị; giữ một tập test viết tay.
• Tool có tác dụng phụ (gửi email, xoá dữ liệu) cần xác nhận hoặc quyền riêng, không chỉ dựa vào mô tả.

Áp dụng thế nào?

• Dev: Rà MCP server đang viết: tool nào chỉ là bọc endpoint? Gộp theo tác vụ, thêm response_format và phân trang mặc định.
• Tech Lead: Dựng bộ eval 20–50 task thật cho tool nội bộ, theo dõi số lần gọi và token mỗi lần đổi mô tả.
• PM: Mô tả workflow người dùng ("đặt lịch họp kèm tài liệu") thay vì danh sách API. Đó là đầu vào tốt nhất để thiết kế tool.