Thiết kế schema để tham số công cụ có nghĩa rõ ràng
Xác định quy tắc khoảng thời gian, múi giờ, phân trang và quyền truy cập; kiểm tra biên cùng giờ địa phương bị lặp trong công cụ tìm lịch.
Với lập trình viên cung cấp công cụ cho LLM, schema tốt phải làm rõ ý nghĩa của từng tham số để ứng dụng kiểm tra được. Kiểu dữ liệu là cần thiết, nhưng đơn vị, quy tắc biên và cách hiểu giá trị thiếu mới quyết định một payload hợp lệ có thực hiện đúng thao tác không. Trường chuỗi tên date để lại quá nhiều điều chưa xác định.
Xét công cụ tìm lịch chỉ đọc trong ví dụ giả định. Người dùng hỏi “Tìm các cuộc họp của tôi vào sáng thứ Sáu tới.” Công cụ phải tìm trên lịch được phép truy cập và trả sự kiện phù hợp. Nó không được tạo, dời hoặc hủy cuộc họp. Ranh giới năng lực này cần có trong danh mục công cụ lẫn bộ thực thi.
Quyết định ý nghĩa của khoảng thời gian
Biểu diễn tìm kiếm bằng thời điểm bắt đầu và thời điểm kết thúc không bao gồm trong khoảng. Với cách khớp theo giờ bắt đầu, sự kiện bắt đầu đúng biên chung chỉ thuộc khoảng kế tiếp. Với cách khớp theo giao nhau, sự kiện kéo qua biên có thể hợp lệ trong cả hai lần tìm liền nhau; biên cuối loại trừ không tự loại trùng những kết quả ấy. Cần kèm múi giờ dùng để hiểu các cụm như “buổi sáng”, hoặc giải nghĩa chúng ở bước riêng trước khi gọi công cụ.
{
"name": "search_calendar_events",
"arguments": {
"calendar_id": "primary",
"start": "2026-10-02T09:00:00+07:00",
"end_exclusive": "2026-10-02T12:00:00+07:00",
"timezone": "Asia/Ho_Chi_Minh",
"limit": 20,
"cursor": null
}
}Đây là lời gọi ở tầng ứng dụng để minh họa, không phải yêu cầu API đầy đủ của nhà cung cấp. Lịch và khoảng thời gian là giá trị kiểm thử. Ứng dụng phải quyết định sự kiện được tính khi bắt đầu trong khoảng hay bất cứ khi nào giao với khoảng. Cuộc họp từ 08:30 đến 09:30 làm rõ khác biệt đó.
Với quy tắc giao nhau, sự kiện khớp khi bắt đầu trước biên cuối truy vấn và kết thúc sau biên đầu, còn cần xét cách lịch xử lý sự kiện cả ngày và mục có thời lượng bằng không. Hãy ghi rõ các chi tiết này thay vì cho rằng mô hình sẽ suy ra cùng quy tắc như backend.
Hình cho thấy sự kiện đi qua biên đầu truy vấn. Schema có thể yêu cầu timestamp hợp lệ mà vẫn không giải thích sự kiện ấy có được trả về không. Mô tả phải chứa quy tắc ngữ nghĩa đó.
Biến quy tắc giao nhau thành mã chạy được
Trong bài tập này, sự kiện có giờ và cửa sổ truy vấn đều là khoảng nửa mở không rỗng: chứa điểm bắt đầu, không chứa điểm kết thúc. Hàm từ chối mục có thời lượng bằng không. Ngày của sự kiện cả ngày cần adapter riêng để mở rộng theo quy tắc múi giờ của lịch; truyền chuỗi lúc nửa đêm khi chưa quyết định điều này sẽ âm thầm tự đặt ra ngữ nghĩa.
Hàm Python sau yêu cầu datetime có thông tin múi giờ và đổi từng thời điểm sang UTC trước khi so sánh. Nó không giải nghĩa “thứ Sáu tới”, kiểm tra cursor phân trang hay xác nhận quyền đọc lịch. Đó là các tầng khác của hợp đồng công cụ.
from datetime import datetime, timezone
def overlaps(event_start, event_end, query_start, query_end):
values = [event_start, event_end, query_start, query_end]
if any(value.utcoffset() is None for value in values):
raise ValueError("all instants must have a timezone")
e0, e1, q0, q1 = [value.astimezone(timezone.utc) for value in values]
if e1 <= e0 or q1 <= q0:
raise ValueError("intervals must have positive duration")
return e0 < q1 and e1 > q0
parse = datetime.fromisoformat
query_start = parse("2026-10-02T09:00:00+07:00")
query_end = parse("2026-10-02T12:00:00+07:00")
print(overlaps(parse("2026-10-02T08:30:00+07:00"),
parse("2026-10-02T09:30:00+07:00"),
query_start, query_end))Kết quả là True. Sự kiện kết thúc lúc 09:00 trả về false vì không có thời điểm được tính nào chung với truy vấn. Sự kiện bắt đầu lúc 12:00 cũng trả false. Sự kiện 11:30 đến 12:30 khớp cả truy vấn này lẫn truy vấn liền kề từ trưa đến 15:00. Thấy nó hai lần qua hai phép tìm có giao nhau là đúng quy tắc đã chọn, không chứng minh biên cuối loại trừ bị hỏng.
Đổi sang UTC tránh thêm một lỗi khó thấy. Tài liệu datetime của Python, truy cập ngày 21 tháng 9 năm 2026, giải thích rằng phép so sánh dùng cùng đối tượng múi giờ bỏ qua fold. Trong giờ địa phương bị lặp, cùng giờ hiển thị có thể biểu thị hai thời điểm khác nhau. Ví dụ, tạo 01:15 với fold=0 và 01:45 với fold=1 ở America/New_York ngày 1 tháng 11 năm 2026: sau khi đổi UTC, khoảng kéo dài 90 phút. Truy vấn 01:30 đến 01:40 với fold=1 giao với nó. Kiểm thử phải xét các thời điểm ấy, không chỉ so chuỗi đồng hồ hiển thị.
Hàm nhận datetime đã được giải nghĩa. Nó không phát hiện giờ địa phương không tồn tại trong lần chuyển giờ mùa xuân, chọn fold cho yêu cầu mơ hồ hay kiểm tra độ lệch UTC ghi rõ có khớp múi giờ IANA cung cấp riêng hay không. Bên gọi phải giải quyết hoặc từ chối các tình huống đó trước thực thi. Cách tách này tránh hiểu nhầm một biểu thức giao nhau ngắn là bộ phân tích lịch hoàn chỉnh.
Bài thiết kế công cụ của Ken Aizawa ngày 11 tháng 9 năm 2025 khuyến nghị viết rõ những ngữ cảnh mà kỹ sư thường hiểu ngầm vào mô tả công cụ. Với lịch này, đó là giao nhau hay khớp theo giờ bắt đầu, hành vi sự kiện cả ngày và ý nghĩa kết quả không khả dụng. Hãy đánh giá cách viết mô tả khác nhau bằng yêu cầu người dùng thực tế; ví dụ tính toán chỉ xác lập ngữ nghĩa đã chọn, không cho biết cách diễn đạt nào được mô hình hiểu ổn định nhất.
Tách kiểm tra schema khỏi kiểm tra quyền
Tài liệu gọi hàm của OpenAI, truy cập ngày 20 tháng 9 năm 2026, mô tả việc định nghĩa tham số bằng schema. Dùng tập giá trị liệt kê khi lựa chọn đóng, yêu cầu trường cần thiết và từ chối thuộc tính bổ sung không hỗ trợ nếu tích hợp đáp ứng hợp đồng đó.
Sau đó thêm kiểm tra ứng dụng. Biên cuối phải sau biên đầu, khoảng tìm phải nằm trong giới hạn cho phép và số kết quả phải có cận. Lịch được yêu cầu phải nằm trong tập lịch người dùng đã xác thực có quyền truy cập. Mã lịch đúng cú pháp không cấp quyền đọc lịch.
Đừng nhận user_id tùy ý chỉ vì mô hình truyền vào. Xác định chủ thể từ phiên đã xác thực. Nếu quản trị viên có thể tìm lịch của người khác, cần biểu diễn năng lực đó rõ ràng và kiểm tra khi thực thi. Mô hình không được mở rộng quyền bằng cách đổi tham số.
Mô tả lỗi như một phần của công cụ
Bộ thực thi có thể trả invalid_interval, calendar_not_accessible, ambiguous_timezone hoặc lỗi nhà cung cấp tạm thời. Mỗi trạng thái gợi ra hành động khác nhau. Khoảng sai có thể sửa từ yêu cầu người dùng. Lịch không truy cập được không nên dẫn tới việc đoán lặp các mã khác.
Tránh lộ tên lịch riêng tư hoặc lỗi nội bộ của nhà cung cấp trong phản hồi từ chối. Cung cấp đủ thông tin để mô hình giải thích thất bại mà không tiết lộ bản ghi người dùng không được xem. Hợp đồng lỗi thuộc cùng ranh giới riêng tư với kết quả thành công.
Đặc tả công cụ MCP phiên bản 2025-06-18 mô tả metadata, schema đầu vào và kết quả gọi. Nó chuẩn hóa trao đổi, còn ứng dụng vẫn quyết định ngữ nghĩa lịch và chính sách truy cập. Cần nêu phiên bản giao thức đang triển khai vì các chi tiết có thể thay đổi.
Ràng buộc phân trang với truy vấn
Giới hạn kết quả bảo vệ ứng dụng khỏi đầu ra không có cận. Nếu còn sự kiện, trả cursor tiếp tục cùng phép tìm. Ràng buộc cursor với lịch, khoảng thời gian, thứ tự và phạm vi quyền liên quan. Nếu không, mô hình có thể vô tình dùng lại cursor sau khi đổi ngày và nhận kết quả khó hiểu.
Định nghĩa thứ tự xác định, chẳng hạn thời điểm bắt đầu rồi mã sự kiện ổn định. Nếu lịch thay đổi giữa các trang, nói rõ đây là duyệt dữ liệu đang thay đổi hay bản chụp. Công cụ không được hứa tập kết quả đầy đủ, ổn định khi nhà cung cấp chỉ trả các trang có thể đổi.
Trả mã nguồn và timestamp để trợ lý trích dẫn hoặc hiển thị. Nếu người dùng muốn dời cuộc họp sau khi xem kết quả, thao tác ghi phải là công cụ riêng với kiểm tra và yêu cầu phê duyệt riêng. Kết quả tìm kiếm không được âm thầm biến thành quyền sửa mọi sự kiện chứa trong đó.
Kiểm thử cách hiểu, không chỉ cách tuần tự hóa
Dùng dữ liệu cho cuộc họp nằm trong khoảng, kết thúc đúng biên đầu, bắt đầu đúng biên cuối và giao qua biên đầu. Thêm sự kiện cả ngày và lần chuyển múi giờ nếu vùng được hỗ trợ cần chúng. Kiểm tra cả tập kết quả công cụ trả về lẫn lời giải thích của mô hình.
Cũng thử yêu cầu không có ngữ cảnh múi giờ. Trợ lý phải hỏi điều cần làm rõ hoặc dùng tùy chọn đã được ghi nhận của người dùng, không tự bịa địa điểm. Mô tả tốt giảm mơ hồ; bộ thực thi bắt phần mơ hồ còn lại. Kết hợp cả hai giúp lời gọi hợp lệ có một ý nghĩa đủ rõ để xem xét.