Đặc tả Tài liệu Function Calling: Cách Lập tài liệu Công cụ cho AI Agents

TL;DR

Tài liệu từ các nhà cung cấp nền tảng (Vendor docs) thường giải thích cách gọi (invoke) các API function-calling, nhưng hiếm khi hướng dẫn cách lập tài liệu cho các công cụ (tools) do chính tổ chức của bạn xuất bản. Đặc tả này giải quyết khoảng trống đó. Sử dụng bảy khối nội dung bắt buộc đối với mỗi công cụ — tên (name), mô tả (description), tham số (parameters định dạng JSON Schema), đầu ra (returns), lỗi (errors), tính lũy đẳng (idempotency), và ví dụ (examples) — kết hợp với các chú thích (annotations) tùy chọn của MCP đối với hành vi thế giới mở (open-world) hoặc phá hủy (destructive). Các công cụ tuân thủ tiêu chuẩn này sẽ tối ưu hóa khả năng lựa chọn, gọi hàm, và trích dẫn của agent.

1. Phạm vi và đối tượng độc giả

Đặc tả này áp dụng cho mọi cá nhân hoặc tổ chức xuất bản các công cụ có thể gọi được (callable tools) phục vụ các agents dựa trên nền tảng LLM thông qua phương thức function calling, tool use, hoặc Model Context Protocol (MCP). Đặc tả này không phụ thuộc vào nền tảng (platform-agnostic); các mô tả công cụ (tool descriptors) có thể chuyển đổi tương thích với các schema công cụ của OpenAI, các khối công cụ (tool blocks) của Anthropic, các khai báo hàm của Gemini, hoặc tải trọng tools/list của MCP.

Đặc tả này không hướng dẫn cách tiêu thụ phản hồi function calling ở phía client — vui lòng tham khảo tài liệu API của nhà cung cấp nền tảng tương ứng.

2. Tại sao cần một đặc tả phía nhà xuất bản

Function calling là cầu nối giữa các LLMs và hệ thống thực tế: mô hình tạo ra một đối tượng JSON có cấu trúc chỉ định tên công cụ và các đối số (arguments), runtime thực thi nó, và kết quả được nạp (feed) trở lại ngữ cảnh hội thoại. Có ba thách thức lớn khiến việc lập tài liệu công cụ theo phương pháp ứng biến (ad-hoc) không còn đáp ứng tiêu chuẩn production:

• Sự bùng nổ của công cụ (Tool sprawl). Các agents trong môi trường production có thể tải từ hàng chục đến hàng nghìn công cụ. Các cơ chế như tool_search của OpenAI, Tool Search Tool của Anthropic, và phần liệt kê tool của MCP đều phụ thuộc vào chất lượng thuộc tính description để xếp hạng các ứng viên.
• Tái sử dụng xuyên nền tảng (Cross-platform reuse). Một công cụ có thể được triển khai (exposed) cho ChatGPT, Claude, Gemini, và các agents tùy chỉnh. Một descriptor duy nhất bắt buộc phải tương thích đa nền tảng.
• Kiểm toán và trích dẫn (Audit and citation). Các chuyên gia GEO/AEO yêu cầu các nền tảng AI trích dẫn trực tiếp (cite) tài liệu của công cụ. Điều này đòi hỏi siêu dữ liệu (metadata) phải có cấu trúc và khả năng trích xuất.

3. Các trường mô tả công cụ bắt buộc

Mọi công cụ khi lập tài liệu BẮT BUỘC bao gồm đủ bảy trường dưới đây.

3.1 Tên (name)

• Mã định danh ổn định (stable identifier), máy đọc được (machine-readable) theo chuẩn snake_case.
• Phải là duy nhất (Unique) bên trong danh mục công cụ (tool catalog).
• Giới hạn tối đa 64 ký tự; chỉ sử dụng ký tự ASCII, chữ số, và dấu gạch dưới (_).
• KHÔNG ĐƯỢC PHÉP thay đổi sau khi xuất bản; sử dụng quy trình ngừng hỗ trợ (deprecate) khi cần phát hành công cụ mới.

3.2 Mô tả (description)

• Độ dài cỡ một đoạn văn, từ 2-5 câu.
• Cấu trúc "Trả lời trước" (Answer-first): câu đầu tiên nêu rõ chức năng của công cụ và bối cảnh kích hoạt.
• Bao gồm các cụm từ kích hoạt (trigger phrases) cụ thể ("thời tiết hiện tại", "hóa đơn mới nhất") khi phù hợp.
• Tránh mô tả chi tiết triển khai hệ thống nội bộ; tập trung vào các hành vi có thể quan sát được (observable behavior).
• Cả tài liệu của Anthropic và OpenAI đều đánh giá chất lượng mô tả (description quality) là yếu tố dự báo quan trọng nhất cho độ chính xác khi lựa chọn công cụ của agent.

3.3 Tham số (parameters - JSON Schema)

• Một đối tượng JSON Schema hợp lệ (type: "object").
• Mỗi thuộc tính (property) BẮT BUỘC có một description.
• Sử dụng enum cho các tập hợp giá trị đóng.
• Khai báo format (như date, date-time, email, uri) tại các trường dữ liệu tương ứng.
• Đánh dấu các trường bắt buộc minh bạch thông qua mảng required: [...].
• Thiết lập thuộc tính additionalProperties: false trừ khi cố ý cho phép dữ liệu đầu vào tự do (free-form).
• Ưu tiên các schemas phẳng (flat schemas); cấu trúc đối tượng lồng nhau (nested objects) làm giảm độ chính xác của các mô hình nhỏ.

3.4 Đầu ra (returns)

• Một JSON Schema mô tả cấu trúc (shape) của kết quả trả về trong trường hợp thành công.
• Bao gồm một mô tả tóm tắt (one-line description) về tải trọng dữ liệu (payload).
• Lập tài liệu trực tiếp (inline) cho các đơn vị đo lường (units), múi giờ (time zones), và mã tiền tệ (currency codes).

3.5 Lỗi (errors)

Danh sách các mã lỗi (error codes) mà công cụ có thể phát ra, với mỗi mã bao gồm:

• code — một chuỗi định danh ổn định (NOT_FOUND, RATE_LIMITED, VALIDATION_ERROR).
• http_status — trạng thái HTTP tương ứng.
• retryable — cờ xác định khả năng thử lại (true hoặc false).
• description — phần diễn giải lỗi dành cho người dùng hoặc hệ thống.
• recovery — hướng dẫn hành động cho agent khi gặp lỗi ("thử lại sau khoảng thời gian Retry-After", "yêu cầu người dùng làm rõ", "hủy thao tác").

3.6 Tính lũy đẳng (idempotency)

• idempotent: true | false.
• safe: true | false (đảm bảo hoàn toàn không tạo ra tác dụng phụ).
• destructive: true | false (thay đổi trạng thái hệ thống một cách không thể đảo ngược).
• Các định nghĩa này ánh xạ (map) trực tiếp vào các chú thích công cụ (tool annotations) của MCP (readOnlyHint, destructiveHint, idempotent, openWorld).

3.7 Các ví dụ (examples)

Yêu cầu tối thiểu hai ví dụ minh họa thực tế cho mỗi công cụ:

1. Một kịch bản gọi hàm thành công tiêu chuẩn (canonical successful call) chứa đầy đủ đối số truyền vào và kết quả trả về.
2. Một kịch bản phát sinh lỗi (error case) minh họa cấu trúc dữ liệu lỗi (error envelope).

Các ví dụ cần ngắn gọn, hoàn chỉnh (complete), và hỗ trợ sao chép trực tiếp.

4. Các trường tùy chọn nhưng được khuyến nghị

5. Quy tắc viết mô tả

Phần mô tả là đòn bẩy quan trọng nhất ảnh hưởng trực tiếp đến độ chính xác của lệnh gọi công cụ (tool-call accuracy).

• Mở đầu bằng cụm động từ + bổ ngữ (verb + object). Dùng "Tìm kiếm thời tiết hiện tại…" thay vì "Công cụ này có thể được sử dụng để…".
• Gọi tên các câu lệnh kích hoạt (trigger). Trích dẫn các cụm từ truy vấn của người dùng thường kích hoạt công cụ.
• Nêu rõ các giới hạn phạm vi. Ví dụ: "Chỉ trả về thời tiết trong 24 giờ tới."
• Giải quyết sự mập mờ (Disambiguate) với các công cụ tương tự. Nếu hệ thống cung cấp cả công cụ get_forecast, cần giải thích rõ điều kiện kích hoạt của từng công cụ.
• Tránh sử dụng ngôn ngữ tiếp thị. Các AI Agent thường bỏ qua các từ ngữ định tính, cường điệu.

6. Quy tắc cho lược đồ tham số

• Mọi thuộc tính (property) BẮT BUỘC có một description. Không có ngoại lệ.
• Kiểm soát giá trị chặt chẽ. Khai thác tối đa enum, minimum, maximum, pattern, và format.
• Lập tài liệu về các đơn vị (units) ngay trong phần mô tả. Ví dụ: "Nhiệt độ tính bằng độ C" (Temperature in degrees Celsius).
• Mặc định yêu cầu tham số (required-by-default). Nếu một tham số là tùy chọn (optional), hãy khai báo rõ ràng và cung cấp giá trị mặc định cấp máy chủ (server-side default) hợp lý.
• Giới hạn độ sâu lồng nhau (depth) ≤ 2 cấp độ. Cấu trúc lồng nhau (nesting) phức tạp làm suy giảm độ chính xác của các mô hình ngôn ngữ cỡ nhỏ.
• Tránh sử dụng thuộc tính oneOf / anyOf tại cấp độ cao nhất (top level). Thay vào đó, hãy phân tách thành các công cụ hoạt động độc lập (separate tools).

7. Phân loại lỗi

Một hệ thống phân loại lỗi (error taxonomy) ổn định và được tài liệu hóa tốt cho phép agent thực thi quy trình phục hồi tự động (recover automatically). Dưới đây là chuẩn cơ sở (baseline) được khuyến nghị:

Lỗi nên được trả về dưới định dạng cấu trúc dữ liệu (structured envelope) thay vì chuỗi văn bản tự do:

[[CODE_FENCE_LANG=json]]

{

"error": {

"code": "RATE_LIMITED",

"message": "Quota exceeded",

"retry_after_seconds": 30

}

}

[[/CODE_FENCE]]

8. Tính lũy đẳng và gợi ý an toàn

MCP chính thức hóa (formalizes) bốn loại chú thích (annotations) hỗ trợ agent lên lịch trình thực thi an toàn: readOnlyHint, destructiveHint, idempotent, openWorld. Hệ thống nên phản ánh (mirror) các thuộc tính này vào nội hàm của descriptor:

• Các công cụ Read-only có thể được gọi theo cơ chế song song (parallel) hoặc suy đoán (speculative).
• Idempotent writes (Thao tác ghi lũy đẳng) có thể được tiến hành retry an toàn mà không phát sinh lỗi biến thiên trạng thái.
• Destructive tools (Công cụ phá hủy) BẮT BUỘC (SHOULD) yêu cầu tín hiệu xác nhận thủ công từ người dùng thông qua giao diện Agent (Agent UI).
• Open-world tools (web fetch, search) yêu cầu các cam kết (guarantees) tuân thủ quy tắc thu thập dữ liệu (crawl-etiquette) — tham khảo đặc tả Browser Agent Crawl Etiquette tại Geodocs.

9. Cấu trúc ví dụ

Ví dụ (Examples) là một phần cốt lõi của descriptor, không phải thành phần trang trí. MỖI ví dụ BẮT BUỘC chứa:

• Câu mô tả bằng ngôn ngữ tự nhiên, đóng vai trò miêu tả câu lệnh kích hoạt (prompt) công cụ.
• Định dạng JSON của tool_call để hệ thống agent tham chiếu chuẩn đầu ra (emit).
• Mã JSON đại diện cho kết quả mà runtime trả về (result) cho client.
• Ghi chú bổ sung ("notes") nếu ví dụ mô tả một cấu trúc logic phức tạp.

10. Ánh xạ đa nền tảng

Tệp Descriptor là nguồn siêu dữ liệu gốc (canonical metadata source). Hệ thống cần chuyển hóa nội dung này xuống từng định dạng nền tảng:

• OpenAI Responses / Chat Completions. Tích hợp Name, Description, và Parameters trực tiếp vào đối tượng Tool. Khuyến nghị thiết lập strict: true để buộc mô hình AI tuân thủ điều kiện required và additionalProperties: false.
• Anthropic Messages. Ánh xạ toàn bộ dữ liệu vào cấu trúc tools[].name, tools[].description, và tools[].input_schema.
• Gemini. Phân bổ dữ liệu vào hệ thống function_declarations[].name, description, parameters.
• MCP Servers. Phơi bày metadata thông qua tools/list, xuất kèm inputSchema, cấu trúc tùy chọn outputSchema, và hệ thống chú thích (annotations) dựa trên tiêu chuẩn tại Mục 8.

11. Quản lý phiên bản và ngừng hỗ trợ

• Sử dụng hệ tiêu chuẩn SemVer cho thuộc tính version.
• Khi triển khai các thay đổi phá vỡ tương thích (Breaking changes) (ví dụ: đổi tên Parameter, gỡ bỏ thuộc tính, sửa đổi Enum), BẮT BUỘC thay đổi major version và xuất bản dưới một tên công cụ mới (ví dụ: get_weather_v2).
• Áp dụng cờ deprecated: true cho công cụ phiên bản cũ và thiết lập tham chiếu điều hướng đến phiên bản mới nhất.
• Bắt buộc duy trì tính tương thích của công cụ deprecated tối thiểu trong một chu kỳ phát hành (release cycle) để agent có thời gian đào tạo lại (retrain) hoặc lập chỉ mục lại (re-index) toàn bộ dữ liệu.

12. Tối ưu hóa tìm kiếm công cụ

Các kiến trúc Agent quy mô lớn thường dựa vào cơ chế thu hồi (retrieval) đối với các danh mục công cụ (Tool catalog) (ví dụ: tool_search của OpenAI, Tool Search Tool của Anthropic, tính năng discovery của nền tảng MCP). Để tối ưu hóa thứ hạng hiển thị (ranking):

• Bổ sung 3-7 từ khóa vào mảng tool_search_keywords, bao phủ các từ đồng nghĩa mà người dùng có thể truy vấn.
• Giới hạn mô tả (description) dưới 600 ký tự; mô tả quá dài sẽ làm giảm hiệu suất thu hồi (recall) trong hệ thống xếp hạng.
• Định hướng mỗi công cụ xử lý một chức năng (purpose) duy nhất. Các công cụ đa nhiệm (multi-purpose tools) thường bị hạn chế đáng kể về điểm xếp hạng tìm kiếm.

13. Các mức độ tuân thủ

• Cấp độ 1 — Tối thiểu (Minimum): Triển khai đầy đủ bảy trường cấu trúc thiết yếu theo yêu cầu tại Mục 3.
• Cấp độ 2 — Production: Bổ sung hệ thống phân loại lỗi (§7), chú thích lũy đẳng (§8), và cung cấp tối thiểu 2 ví dụ (examples) cho mỗi công cụ.
• Cấp độ 3 — AI-native: Tích hợp các tham số tìm kiếm tool-search keywords, chỉ báo độ trễ (latency hints), chính sách ngừng hỗ trợ (deprecation policy), và bộ công cụ tạo sơ đồ kiến trúc (generator) tự động cho từng nền tảng (platform).

14. Danh sách kiểm tra xác thực

• [ ] Công cụ sở hữu đầy đủ bảy trường cấu hình bắt buộc.
• [ ] Mỗi Parameter đều có thuộc tính description chi tiết.
• [ ] Cung cấp tối thiểu một kịch bản gọi hàm thành công (happy-path) và một kịch bản báo lỗi (error case).
• [ ] Cấu trúc trả về của khối Lỗi (Error envelope) chứa mã lỗi (error code) định danh.
• [ ] Trạng thái Phá hủy (Destructive) hoặc Lũy đẳng (Idempotent) được khai báo minh bạch (explicit).
• [ ] Không có thay đổi phá vỡ (breaking changes) nếu chưa thiết lập cấp độ phiên bản mới (version bump) hoặc đổi tên định danh.
• [ ] Gói Descriptor được xác thực cấu trúc chuẩn xác (correct) tương thích với payload của OpenAI, Anthropic, Gemini, và MCP.

15. FAQ

Q: Khối tham số trong đặc tả này có đồng nhất với JSON Schema không?

A: Không hoàn toàn. JSON Schema chỉ được áp dụng cho phần tham số đầu vào (Parameters). Nội dung của đặc tả (spec) này bao quát toàn bộ quy chuẩn cấp "Nhà xuất bản" (publisher-side) bao gồm — Tên (Name), Mô tả (description), cấu trúc kết quả (returns), hệ mã báo lỗi (errors), quy chế lũy đẳng (idempotency), và các ví dụ (examples) — trong đó JSON Schema chỉ đóng vai trò như một thành phần (component) cục bộ (§3.3).

Q: Đặc tả này tương thích với giao thức MCP như thế nào?

A: MCP chuẩn hóa giao thức truyền tải (transport layer - JSON-RPC 2.0) và cơ chế liệt kê điểm cuối (listing endpoint - tools/list). Đặc tả này chuẩn hóa ngữ nghĩa và cấu trúc nội dung của tool descriptor để đảm bảo tính tương thích chéo. Một descriptor tuân thủ đặc tả có thể được định tuyến qua OpenAI, Anthropic, Gemini, và đóng vai trò làm nền tảng siêu dữ liệu cho kiến trúc MCP.

Q: Tôi có bắt buộc phải tách riêng các công cụ Read/Write thành hai thực thể độc lập không?

A: Có, trong trường hợp chức năng phân định rõ ràng. Việc tách get_user và update_user giúp agent thiết lập đánh giá rủi ro an toàn và cho phép gán chú thích MCP (readOnlyHint, destructiveHint) với độ chính xác tuyệt đối.

Q: Độ dài hợp lý của một đoạn mô tả (description) công cụ là bao nhiêu?

A: Khuyến nghị từ 2-5 câu, và ≤ 600 ký tự. Mô tả quá dài sẽ làm giảm hiệu suất xếp hạng trong các tool catalog quy mô lớn và làm loãng chuỗi tín hiệu Động từ - Bổ ngữ (verb-object).

Q: Có nên tích hợp thông số độ trễ (latency) hoặc chi phí (cost) vào tệp mô tả không?

A: Có, đặc biệt trong môi trường production. Các Agent thực thi quy trình đa bước (multi-step workflows) thường yêu cầu phân bổ ngân sách tối ưu cho từng công cụ. Ngay cả khi các chỉ báo (hints) chỉ ở mức độ cơ bản (fast/slow; free/metered), chúng vẫn cải thiện rõ rệt độ chính xác khi lập kế hoạch (Plan quality) của hệ thống.