QuotaCheap Playbook

Thiết kế MCP tools: ít nhưng đúng, tránh mở nguyên backend cho agent

Hướng dẫn thiết kế MCP tools cho AI agent production: naming, input/output schema, read/write separation, idempotency, dry run, confirmation, logs và anti…

Tool surface tốt không phải là nhiều tool. Tool surface tốt là ít, rõ, có schema và có dây an toàn.

Hướng dẫn thiết kế MCP tools cho AI agent production: naming, input/output schema, read/write separation, idempotency, dry-run, confirmation, logs và anti-pattern mở nguyên backend cho agent.

Thiết kế MCP tools: ít nhưng đúng, tránh mở nguyên backend cho agent Khi mới làm MCP server, nhiều team có xu hướng expose càng nhiều tool càng tốt.

Nghe có vẻ linh hoạt, nhưng production thì ngược lại: agent càng thấy nhiều action mơ hồ, rủi ro càng lớn.

Tool surface tốt nên giống một bộ điều khiển được thiết kế cho nhiệm vụ cụ thể, không phải chìa khóa tổng mở mọi phòng trong backend.

Tool nên đại diện cho business action Đừng expose raw database operation kiểu: queryDatabase updateAnyRecord runSql callInternalApi Những tool này quá rộng.

Agent có thể dùng sai và rất khó audit.

Nên expose action có ý nghĩa nghiệp vụ: searchCustomerOrders createDraftRefundRequest getUsageSummaryForWorkspace scheduleFacebookPostDraft findRecentFailedPayments Tên tool càng rõ, agent càng ít phải đoán.

Input schema phải chặt Mỗi tool cần schema rõ: Field nào required?

Kiểu dữ liệu là gì?

Có max length không?

Có validate date range không?

Có chặn wildcard nguy hiểm không?

Schema không chỉ để model hiểu.

Schema là lớp bảo vệ runtime.

Output nên ngắn và có cấu trúc Tool output không nên trả nguyên object khổng lồ nếu agent chỉ cần 5 field.

Output dài làm tốn context và dễ leak dữ liệu.

Output tốt nên có: status summary data tối giản nextActions nếu cần requestId để debug Nếu data dài, lưu artifact bên ngoài và trả reference.

Tách read tools và write tools Read tools thường ít rủi ro hơn write tools.

Hãy tách rõ: getUsageReport previewInvoiceChange createDraftPost publishPost Đừng gộp preview và execute vào cùng một tool nếu action có tác động bên ngoài.

Dry run là bạn thân của production Với write action, nên có dry run hoặc preview mode: Agent tạo bản nháp.

Agent giải thích sẽ làm gì.

User hoặc policy duyệt.

Tool execute thật sau đó.

Điều này đặc biệt quan trọng với email, social post, billing, refund, delete, deploy và data mutation.

Idempotency giúp tránh tai nạn retry Agent và runtime có thể retry khi lỗi mạng, timeout hoặc tool failure.