Domain 2: Tool Design & MCP Integration — Ôn thi CCA-F

#Task 2.1: Thiết kế tool interface hiệu quả với description rõ ràng và ranh giới rõ

#Knowledge of (Kiến thức về)

• Mô tả công cụ: Tool description là cơ chế chính LLM dùng để chọn tool; description sơ sài → chọn tool không đáng tin giữa các tool tương tự.
• Chi tiết trong mô tả: Cần đưa vào description: định dạng input, ví dụ truy vấn, edge case, giải thích ranh giới.
• Tránh chồng lấn: Mô tả mơ hồ/chồng lấn gây định tuyến sai (VD: analyze_content vs analyze_document với description gần giống hệt).
• System prompt override: Ảnh hưởng của cách viết system prompt lên việc chọn tool: chỉ dẫn nhạy cảm với từ khoá có thể tạo liên kết tool ngoài ý muốn.

#Skills in (Kỹ năng về)

• Viết mô tả phân biệt: Phân biệt rõ mục đích từng tool, input/output kỳ vọng, khi nào dùng nó thay vì tool tương tự.
• Refactor tool: Đổi tên tool + cập nhật description để loại bỏ chồng lấn chức năng (VD: đổi analyze_content thành extract_web_results với mô tả chuyên cho web).
• Tách nhỏ công cụ: Tách tool chung chung thành các tool chuyên biệt có input/output contract rõ.
• Rà soát system prompt: Rà soát system prompt tìm chỉ dẫn nhạy từ khoá có thể lấn át description tool viết tốt.

#🧠 Phân tích & Thực tế từ Delivery Manager:

Trong thực tế, 90% lỗi chọn sai tool của Claude không phải do mô hình kém, mà do nhà phát triển lười viết description hoặc viết quá mơ hồ. Hãy coi description của tool là một prompt chuyên dụng để điều hướng hành vi gọi hàm của AI.

❌ Thiết kế kém (Mơ hồ):
"Retrieves customer details"

✅ Thiết kế tốt (Tường minh):
"Tra cứu MỘT khách hàng theo email hoặc số điện thoại. 
Input: email dạng chuỗi hoặc phone dạng số. 
Trả về: mã khách hàng, tên, hạng thành viên, và danh sách 5 đơn hàng gần nhất.
Dùng tool này khi khách hàng hỏi về thông tin cá nhân hoặc tài khoản của họ.
KHÔNG dùng để tra cứu trạng thái đơn hàng cụ thể — việc đó dùng lookup_order."

#Task 2.2: Triển khai structured error response cho MCP tool

#Knowledge of (Kiến thức về)

• Cờ isError: Pattern cờ isError của MCP để báo tool thất bại về cho agent.
• Phân loại lỗi: Transient (timeout, dịch vụ không khả dụng), validation (input sai), business (vi phạm chính sách), permission.
• Tính đồng nhất: Error response đồng nhất (chỉ trả về "Operation failed") khiến agent không quyết định phục hồi đúng được.
• Retryable vs Non-retryable: Lỗi có thể thử lại vs lỗi chết; trả metadata có cấu trúc giúp tránh retry vô ích.

#Skills in (Kỹ năng về)

• Trả error metadata cấu trúc: Trả về errorCategory (transient/validation/permission), boolean isRetryable, và mô tả dễ đọc.
• Chặn retry vô ích: Kèm cờ isRetryable: false + giải thích thân thiện với khách khi vi phạm business rule, để agent truyền đạt phù hợp.
• Phục hồi cục bộ: Phục hồi cục bộ trong subagent với lỗi transient; chỉ đẩy lên coordinator lỗi không tự xử lý được, kèm kết quả một phần và những gì đã thử.
• Kết quả rỗng: Phân biệt lỗi truy cập (cần quyết định retry) với kết quả rỗng hợp lệ (truy vấn thành công nhưng không có match).

#🧠 Phân tích & Thực tế từ Delivery Manager:

Nếu hệ thống gặp lỗi timeout từ cổng thanh toán bên thứ ba, chúng ta muốn Agent tự động thử lại (retry) thêm 1-2 lần trước khi báo lỗi cho khách. Ngược lại, nếu thẻ của khách hết số dư, việc retry 10 lần chỉ gây lãng phí tài nguyên và làm chậm hệ thống.

// Lỗi transient (Mạng tạm lỗi) → Agent NÊN tự động thử lại
{
  "isError": true,
  "errorCategory": "transient",
  "isRetryable": true,
  "message": "Payment gateway timeout sau 5s. Thử lại sau ít giây."
}

// Lỗi business (Hết hạn mức) → Thử lại VÔ ÍCH, Agent phải escalate hoặc báo lỗi
{
  "isError": true,
  "errorCategory": "business",
  "isRetryable": false,
  "message": "Số tiền hoàn $600 vượt hạn mức tự động $500. Cần duyệt tay.",
  "customerFacing": "Khoản hoàn tiền này cần nhân viên kiểm duyệt, tôi đã chuyển tiếp yêu cầu."
}

#Task 2.3: Phân bổ tool hợp lý giữa các agent và cấu hình tool choice

#Knowledge of (Kiến thức về)

• Quá tải công cụ: Agent có quá nhiều tool (VD: 18 thay vì 4-5) → độ tin cậy chọn tool giảm do độ phức tạp của không gian quyết định.
• Sử dụng sai chuyên môn: Agent có tool ngoài chuyên môn thường dùng sai (VD: synthesis agent tự đi web search).
• Scoped tool access: Chỉ cấp tool cần cho vai trò; tool chéo vai trò (cross-role) chỉ giới hạn cho nhu cầu tần suất cao cụ thể.
• Cấu hình tool_choice: Cú pháp "auto", "any", và ép chọn tool cụ thể.

#Skills in (Kỹ năng về)

• Giới hạn tool set: Giới hạn tool set của mỗi subagent theo đúng vai trò, tránh dùng sai ngoài chuyên môn.
• Ràng buộc công cụ: Thay tool chung chung bằng bản có ràng buộc (VD: thay fetch_url bằng load_document có validate URL tài liệu).
• Forced tool choice: Dùng tool_choice ép chọn để bảo đảm một tool được gọi trước (VD: ép extract_metadata trước các tool enrichment), các bước sau xử lý ở lượt tiếp theo.
• Ép gọi tool: Đặt tool_choice: "any" để bảo đảm model phải gọi tool thay vì chỉ trả về text hội thoại.
• Cung cấp scoped cross-role tool: Thiết kế các tool phạm vi hẹp cho các nhu cầu tần suất cao (VD: cung cấp tool chuyên biệt verify_fact trực tiếp cho synthesis agent) thay vì bắt nó phải định tuyến các yêu cầu tra cứu đơn giản thông qua coordinator, từ đó giảm latency đáng kể cho luồng nghiệp vụ.

#🧠 Phân tích & Thực tế từ Delivery Manager:

Thiết kế hệ multi-agent đòi hỏi sự cân bằng giữa bảo mật và hiệu năng. Bắt synthesis agent chạy một pipeline phức tạp chỉ để kiểm chứng một con số thống kê đơn giản là một sự lãng phí tài nguyên lớn. Bằng cách cấp cho nó một tool chuyên trách có scope hẹp (verify_fact), tôi đã giải phóng coordinator khỏi các queue xử lý vụn vặt.

#Task 2.4: Tích hợp MCP server vào Claude Code và agent workflow

#Knowledge of (Kiến thức về)

• Scope của MCP server: Project-level (.mcp.json) cho tooling chung của team vs user-level (~/.claude.json hoặc ~/.code.json) cho server cá nhân/thử nghiệm.
• Biến môi trường: Mở rộng biến môi trường trong .mcp.json (VD: ${GITHUB_TOKEN}) để quản lý credential mà không commit secret.
• Khám phá đồng thời: Tool từ tất cả MCP server đã cấu hình được phát hiện lúc kết nối và khả dụng đồng thời.
• MCP resources: Resources để phơi bày catalog nội dung (tóm tắt issue, cây tài liệu, schema database) → giảm tool call thăm dò.

#Skills in (Kỹ năng về)

• Cấu hình biến môi trường: Cấu hình MCP server dùng chung trong .mcp.json với biến môi trường cho token xác thực.
• Nâng cấp mô tả MCP: Nâng cấp description của MCP tool giải thích chi tiết năng lực và output — tránh việc agent thích dùng built-in tool (như Grep) hơn MCP tool mạnh hơn.
• MCP Resource catalog: Phơi catalog nội dung dưới dạng MCP resource để agent thấy dữ liệu khả dụng mà không phải gọi tool thăm dò.
• Cấu hình user-scoped server: Thiết lập các cấu hình mang tính thử nghiệm cá nhân trong ~/.claude.json hoặc ~/.code.json để tránh làm ảnh hưởng đến cấu hình team-wide chung của repo.
• Ưu tiên MCP server cộng đồng: Lựa chọn sử dụng các MCP server có sẵn của cộng đồng (Jira, GitHub, Postgres) cho các tích hợp tiêu chuẩn, chỉ tự viết MCP server tùy chỉnh cho các luồng nghiệp vụ nội bộ/đặc thù của team để tối ưu hóa thời gian phát triển và chi phí bảo trì.

#🧠 Phân tích & Thực tế từ Delivery Manager:

Một sai lầm phổ biến của các đội ngũ kỹ thuật là cố gắng tự viết lại MCP server cho Jira hoặc Slack. Điều này làm tăng nợ kỹ thuật (technical debt). Với tư cách là DM, tôi luôn yêu cầu dev sử dụng các MCP server chính chủ hoặc từ cộng đồng tin cậy đã được kiểm định, giải phóng nguồn lực tập trung vào phát triển core logic.

#Task 2.5: Chọn và dùng built-in tool (Read, Write, Edit, Bash, Grep, Glob) hiệu quả

#Knowledge of (Kiến thức về)

• Grep: Tìm theo nội dung file (tên hàm, message lỗi, câu import).
• Glob: Tìm theo đường dẫn/tên file (theo pattern tên hoặc extension).
• Read/Write: Thao tác đọc/ghi cả file; Edit: sửa nhắm đích bằng text match duy nhất.
• Fallback sửa đổi: Khi Edit fail vì text match không duy nhất → fallback Read + Write để sửa file đáng tin.

#Skills in (Kỹ năng về)

• Chọn đúng công cụ:
  • Chọn Grep khi tìm nội dung code khắp codebase (VD: tìm mọi caller của một hàm, tìm message lỗi).
  • Chọn Glob khi tìm file theo pattern tên (VD: **/*.test.tsx).
• Sử dụng fallback: Dùng Read đọc cả file rồi Write khi Edit không tìm được anchor text duy nhất.
• Tìm hiểu tăng dần (Incremental traces): Xây hiểu biết codebase tăng dần: bắt đầu bằng Grep tìm entry point, rồi Read lần theo import và trace flow — thay vì đọc hết file từ đầu.
• Trace function usage chéo qua wrapper modules: Thực hiện định vị vết hàm bằng cách tìm tất cả exported names từ module nguồn, sau đó chạy Grep tìm kiếm chính xác từng tên đó trên toàn bộ cấu trúc thư mục dự án để xác định vùng tác động (impact zone).

#🧠 Phân tích & Thực tế từ Delivery Manager:

Khi onboarding một dev mới vào dự án legacy khổng lồ, việc trace code không khoa học sẽ làm ngốn hàng tuần trời. Tôi luôn huấn luyện dev cách trace ngược bằng Grep để xác định điểm xuất phát, sau đó dùng Glob lọc file test liên quan. Việc này giúp giảm thời gian làm quen hệ thống xuống còn 1/3.

Quay lại Trang Hub ôn thi CCA-F.