2.1 Tool Interface Design

Những gì cần nắm

Tool description là cơ chế CHÍNH để LLM chọn tool. Không phải metadata phụ, cũng không phải thứ viết cho có. Nó là cơ chế. Khi model nhận một bộ tool, nó đọc description để quyết định gọi cái nào — và nếu description chỉ có mỗi câu kiểu “Retrieves customer information”, model không có cách nào phân biệt hai tool có mục đích chồng lấn.

Thế nào là một tool description tốt

Một tool description đạt mức production gồm năm phần:

Tool làm gì — mục đích chính, nói rõ không mập mờ
Nhận input gì — kiểu dữ liệu, định dạng, ràng buộc, field nào bắt buộc và field nào tùy chọn
Ví dụ những query nó xử lý tốt — use case cụ thể để model neo vào
Edge case và giới hạn — tool KHÔNG làm gì, và chuyện gì xảy ra khi input nằm ngoài khoảng mong đợi
Ranh giới tường minh — khi nào dùng tool NÀY thay vì các tool tương tự trong cùng bộ

Đây là khác biệt giữa một description tối giản và một description đạt mức production:

Tối giản (gây misrouting):

get_customer: "Retrieves customer information"
lookup_order: "Retrieves order details"

Mức production (chọn tool ổn định):

get_customer: "Looks up a customer account by email address,
phone number, or customer ID. Returns customer profile
(name, contact details, account status, loyalty tier).
Use this when you need to verify who the customer is.
Do NOT use for order-specific queries — use lookup_order
for those."

lookup_order: "Retrieves order details by order number
(format: #NNNNN) or tracking ID. Returns order status,
items, shipping details, and refund eligibility.
Use this when a customer asks about a specific order.
Do NOT use for customer identity verification —
use get_customer for that."

Bản thứ hai cho model cơ sở phân biệt rõ ràng. Model biết mỗi tool nhận loại identifier nào, trả về gì, và quan trọng nhất là khi nào KHÔNG nên dùng tool nào.

Vấn đề misrouting

Hai tool có description chồng lấn hoặc gần như giống nhau sẽ gây nhầm lẫn khi chọn. Câu hỏi mẫu số 2 trong exam guide đúng là tình huống này: get_customer và lookup_order với description tối giản, khiến agent định tuyến “check my order #12345” sang nhầm tool.

Đề thi kiểm tra xem bạn có nhận ra cách sửa đúng không. Bốn lựa chọn đều nghe hợp lý, ba trong số đó sai:

Mở rộng description — đúng. Công sức thấp, đòn bẩy cao, đánh thẳng vào gốc vấn đề.
Few-shot examples — sai. Thêm token overhead mà không sửa được lý do model nhầm. Đó là chữa triệu chứng, không chữa bệnh.
Routing classifier — sai. Quá nặng cho một bước đầu tiên. Nó bỏ qua khả năng hiểu ngôn ngữ tự nhiên của LLM và thêm độ phức tạp hạ tầng.
Gộp tool — sai ở vai trò bước đầu tiên. Về dài hạn đây là lựa chọn kiến trúc hợp lệ, nhưng tốn công hơn nhiều so với mở rộng description.

Đề thi luôn ưu tiên cách sửa ít công mà đòn bẩy cao. Description tốt hơn trước khi nghĩ tới routing classifier. Quyền truy cập thu hẹp trước khi cấp quyền đầy đủ. Community server trước khi tự build.

Tách tool

Tool chung chung ôm quá nhiều trách nhiệm thì sinh ra mập mờ. Cách sửa: tách thành các tool chuyên biệt, mỗi cái có hợp đồng input/output rõ ràng.

Trước khi tách:

analyze_document: "Analyses a document and returns results"

Sau khi tách:

extract_data_points: "Extracts structured data fields
(dates, amounts, names) from a document"

summarize_content: "Produces a concise summary of a
document's key arguments and conclusions"

verify_claim_against_source: "Checks whether a specific
claim is supported by the source document, returning
supporting/contradicting evidence"

Mỗi tool sau khi tách làm một việc hẹp, mô tả rõ ràng. Model chọn được đúng cái người dùng thực sự cần.

Đổi tên tool cho rõ nghĩa

Khi hai tool có tên giống nhau đến mức dễ lẫn, đổi tên xử lý phần chồng lấn ngay ở lớp interface. Đổi analyze_content thành extract_web_results, cho nó một description gắn với web, và mục đích của tool trở nên rõ ràng — mà không phải đụng vào phần implementation.

Tương tác với system prompt

Các chỉ dẫn nhạy từ khóa trong system prompt có thể tạo ra liên tưởng tool ngoài ý muốn, đè lên cả description viết tốt. Nếu system prompt nói “always check customer details before proceeding”, model có thể đẩy mọi query liên quan tới khách hàng sang get_customer bất kể description viết gì.

Nên sau khi cập nhật tool description, đọc lại system prompt xem có xung đột không. Đây là chế độ lỗi khá kín, và đề thi có hỏi.

Tool description là cơ chế chính để LLM chọn tool. Khi misrouting bắt nguồn từ description yếu, cải thiện description là cách sửa đầu tiên — không phải few-shot examples, routing classifier hay gộp tool.

Đọc kỹ điều kiện đi kèm, vì đề thi hỏi cả hai vế. Description là cách sửa khi agent có số lượng tool vừa phải mà chỉ đơn giản không phân biệt nổi hai cái. Nó không phải cách sửa khi chính bộ tool mới là vấn đề: vượt khoảng 4-5 tool mỗi agent, độ chính xác khi chọn tụt chỉ vì độ phức tạp của quyết định, và viết lại 22 description không chạm tới chuyện đó. Chẩn đoán xem mình đang gặp ca nào trước khi chọn thuốc. Task Statement 2.3 nói về ngưỡng quá tải tool và phải làm gì thay thế.

Bẫy thi

Tình huống luyện tập

Log production cho thấy agent thường gọi get_customer khi người dùng hỏi về đơn hàng (ví dụ ‘check my order #12345’), thay vì gọi lookup_order. Cả hai tool đều có description tối giản (‘Retrieves customer information’ / ‘Retrieves order details’) và nhận định dạng identifier tương tự nhau. Bước đầu tiên hiệu quả nhất để cải thiện độ tin cậy khi chọn tool là gì?

A. Thêm 5-8 few-shot examples vào system prompt minh họa cách chọn tool đúng cho query liên quan đơn hàng
B. Mở rộng description của từng tool để có định dạng input, ví dụ query, edge case và ranh giới nói rõ khi nào dùng nó thay vì tool tương tự
C. Dựng một lớp routing phân tích input của người dùng trước mỗi lượt và chọn sẵn tool phù hợp theo từ khóa phát hiện được
D. Gộp cả hai tool thành một lookup_entity nhận mọi loại identifier rồi tự xác định bên trong nên truy vấn backend nào

Đáp án & giải thích

Đúng: B

A — Few-shot examples thêm token overhead mà không sửa vấn đề nền. Gốc vấn đề là description không phân biệt được các tool — sửa description trước.
B — Tool description là cơ chế chính để LLM chọn tool. Mở rộng chúng là cách ít công nhất, đòn bẩy cao nhất và đánh thẳng vào gốc của misrouting.
C — Lớp routing là giải pháp quá nặng cho bước đầu tiên. Nó bỏ qua khả năng hiểu ngôn ngữ tự nhiên của LLM và thêm độ phức tạp hạ tầng không cần thiết.
D — Gộp tool là lựa chọn kiến trúc hợp lệ nhưng tốn công hơn hẳn so với mở rộng description. Đề thi ưu tiên bước đầu tương xứng.

Nguồn

Claude Certified Architect Foundations Exam Guide — Domain 2, Task Statement 2.1 — Anthropic
Tool use — Anthropic API Documentation — Anthropic
Model Context Protocol Specification — Tools — Model Context Protocol

Exam Simulator

Năm câu trắc nghiệm theo format đề thi về Tool Interface Design. Chọn đáp án trước, rồi mở phần giải thích.

Câu 1

Log production cho thấy agent thường gọi get_customer khi người dùng hỏi về đơn hàng (ví dụ “check my order #12345”), thay vì gọi lookup_order. Cả hai tool đều có description tối giản (“Retrieves customer information” / “Retrieves order details”) và nhận định dạng identifier tương tự nhau. Bước đầu tiên hiệu quả nhất để cải thiện độ tin cậy khi chọn tool là gì?

A. Thêm 5-8 few-shot examples vào system prompt bao các query dạng đơn hàng
B. Thêm một lớp routing phân tích mỗi lượt người dùng và chọn sẵn tool theo từ khóa
C. Gộp cả hai thành một tool lookup_entity nhận mọi identifier rồi tự xác định bên trong nên truy vấn backend nào
D. Mở rộng cả hai description để có định dạng input, ví dụ query, edge case và ranh giới tường minh

Đáp án & giải thích

Đúng: D

D đúng vì tool description là cơ chế chính để LLM chọn tool. Mở rộng chúng là cách ít công nhất, đòn bẩy cao nhất, và đánh thẳng vào gốc vấn đề, bởi hiện tại không description nào nói tool của nó dùng để làm gì hay khi nào nên ưu tiên cái kia.
A sai vì few-shot examples thêm token overhead vào mọi request mà vẫn để nguyên sự mập mờ. Chúng chỉ bù đắp cho description vẫn không phân biệt nổi hai tool.
B sai vì lớp routing là giải pháp quá nặng cho bước đầu tiên. Nó bỏ qua khả năng hiểu ngôn ngữ của model và thêm hạ tầng phải bảo trì mỗi khi bộ tool thay đổi.
C sai vì gộp tool là lựa chọn kiến trúc chính đáng nhưng là thay đổi lớn hơn nhiều so với viết lại hai description. Đề thi ưu tiên bước đầu tương xứng.

Câu 2

Một tool tên analyse_document có description “Analyses a document and returns results.” Người dùng phản ánh rằng agent đôi khi trích xuất dữ liệu trong khi họ muốn tóm tắt, và ngược lại. Cách xử lý tốt nhất là gì?

A. Tách thành các tool chuyên biệt, mỗi cái một description hẹp và hợp đồng input/output riêng
B. Thêm few-shot examples cho thấy khi nào trích xuất data point và khi nào tóm tắt
C. Đổi tên thành extract_and_summarise_document để cả hai thao tác hiện rõ trong tên
D. Thêm một bước tiền xử lý phân loại ý định trước

Đáp án & giải thích

Đúng: A

A đúng vì một tool chung chung ôm nhiều trách nhiệm buộc model phải đoán người dùng muốn thao tác nào. Tách thành extract_data_points, summarise_content và verify_claim_against_source cho model các lựa chọn hẹp với hợp đồng input/output rõ ràng.
B sai vì few-shot examples chỉ chữa triệu chứng. Gốc vấn đề là một tool gánh nhiều trách nhiệm, và thêm bao nhiêu ví dụ cũng không xóa được sự mập mờ đó.
C sai vì cái tên giờ liệt kê cả hai thao tác nhưng tool vẫn làm cả hai, nên model vẫn phải suy ra mỗi lần gọi là muốn thao tác nào.
D sai vì bước tiền xử lý là giải pháp quá nặng. Chỗ cần sửa nằm ở tool interface, không phải ở một lớp routing bên ngoài.

Câu 3

Sau khi cải thiện description cho get_customer và lookup_order, một developer nhận thấy query về đơn hàng đôi khi vẫn chạy sang get_customer. System prompt có câu: “Always check customer details before proceeding with any request.” Nguyên nhân nhiều khả năng là gì?

A. Description vẫn cần chi tiết hơn nữa để thắng được chỉ dẫn nằm trong system prompt
B. Một chỉ dẫn nhạy từ khóa trong system prompt tạo liên tưởng cạnh tranh ở mọi lượt
C. Model đã cache description cũ và cần reset context
D. Tên hai tool vẫn quá giống nhau, nên đổi tên cả hai cho rõ

Đáp án & giải thích

Đúng: B

B đúng vì chỉ dẫn nhạy từ khóa trong system prompt có thể âm thầm đè lên description viết tốt. Câu “Always check customer details before proceeding with any request” gắn mọi request với get_customer, và nó được cân nhắc ngang hàng với description chứ không nằm dưới.
A sai vì chất lượng description không còn là điểm nghẽn; description đã được cải thiện rồi. Thêm chi tiết nữa cũng không gỡ được một chỉ dẫn đang cạnh tranh.
C sai vì tool description không được cache giữa các lần gọi API. Mỗi request được đánh giá dựa trên các định nghĩa gửi kèm nó.
D sai vì get_customer và lookup_order vốn đã là hai tên khác biệt. Phần misrouting còn lại bắt nguồn từ system prompt, không phải từ tên tool.

Câu 4

Hai tool có tên giống nhau đến mức dễ lẫn: analyse_content và analyse_web_content. Cả hai đều xử lý dữ liệu web. Cách sửa hiệu quả nhất là gì?

A. Thêm description chi tiết cho cả hai, nói rõ phạm vi khác nhau thế nào và nên ưu tiên cái nào
B. Gộp cả hai thành một tool analyse_all_content xử lý mọi loại
C. Đổi tên analyse_content thành extract_web_results và cho nó description giới hạn ở kết quả web
D. Thêm routing classifier chọn giữa hai tool bằng cách xem nội dung input trước

Đáp án & giải thích

Đúng: C

C đúng vì phần chồng lấn nằm ở interface, không nằm ở implementation. Đổi tên thành extract_web_results kèm description cụ thể làm mục đích của tool hết mập mờ mà không đổi thứ nó làm.
A sai vì khi hai cái tên đã giống nhau đến mức dễ lẫn, description phải chống lại chính cái tên. Mập mờ do tên tạo ra thì nên gỡ bỏ chứ đừng bù đắp.
B sai vì gộp lại tái tạo đúng vấn đề tool chung chung: một tool gánh nhiều trách nhiệm.
D sai vì routing classifier là giải pháp quá nặng khi chỉ cần đổi tên là hết mập mờ.

Câu 5

Một tool description đạt mức production nên gồm năm phần nào?

A. Mục đích, input mong đợi, ví dụ query, edge case, và ranh giới tường minh so với các tool tương tự
B. Tên, version, tác giả, giấy phép, và danh sách phụ thuộc
C. Endpoint URL, phương thức xác thực, rate limit, response schema, và các error code có thể trả về
D. Function signature, kiểu trả về, độ phủ unit test, link tài liệu, và changelog đầy đủ của các bản phát hành

Đáp án & giải thích

Đúng: A

A đúng vì năm phần này cho model đủ ngữ cảnh để phân biệt tool này với tool kia: nó dùng để làm gì, nhận gì (kèm định dạng và ràng buộc), hợp với query nào, dừng ở đâu, và khi nào tool bên cạnh mới là lựa chọn đúng.
B sai vì đó là các field metadata của package. Không field nào nói cho model biết tool dùng để làm gì hay khi nào nên chọn nó.
C sai vì đó là các field đặc tả API. Phần input có chồng lấn phần nào, nhưng bộ này thiếu ví dụ query và ranh giới — đúng hai thứ quyết định việc chọn giữa các tool tương tự.
D sai vì đó là các field tài liệu phần mềm hướng tới người bảo trì, không phải tín hiệu chọn tool hướng tới model.