6. Result, Error, Files, Pagination, dan Operational Safety

Jangan return payload random. Gunakan envelope yang konsisten agar model dan client dapat melakukan follow-up.

Get:  { found, item }
List: { items, nextCursor, total }
Write:{ ok, id, changedFields }
Scalar:{ result }

Jika memakai structuredContent, sediakan outputSchema yang sesuai.

Protocol error dan tool execution error harus dipisahkan.

Gunakan JSON-RPC error untuk malformed request, unknown tool, invalid params, atau unsupported protocol. Untuk operasi tool yang ditemukan tetapi gagal, return tool result dengan isError: true.

Kategori useful: AUTHENTICATION_REQUIRED, INSUFFICIENT_SCOPE, APPROVAL_REQUIRED, POLICY_DENIED, VALIDATION_ERROR, RATE_LIMITED, TIMEOUT, UPSTREAM_ERROR.

• pagination limit + cursor
• max request/result bytes
• timeouts + cancellation
• read/write/destructive rate limits
• explicit truncation metadata

Jangan silently truncate.

File/URL adalah threat surface sendiri: authorize sebelum fetch, HTTPS, SSRF protection, block localhost/private/metadata networks, redirect limit, MIME allowlist, size limit, timeout, safe filename, short-lived signed URL, dan jangan bocorkan local absolute path.

• deployment kill switch
• maximum scope ceiling
• catalog/toolset version + hash
• immediate revocation
• audit logging + redaction
• timeout/error metrics
• restart-storm suppression untuk supervised runtimes