A tool result carries artifacts alongside its data, never inside it

A tool can return something structured (a chart, a record, a file reference) that the model should not have to read as prose. It travels beside the result, not inside it.

What it means

An artifact-free result is indistinguishable from a plain three-key result — artifacts only appears once at least one artifact was attached. A caller that never expects artifacts can keep reading {success, data, error} and never notice the key exists. data and artifacts stay disjoint: an artifact is never folded into data alongside the prose-facing values, and attaching one never changes what data already holds.

Example

{ "success": true, "data": { "ok": true }, "error": null }

{
  "success": true,
  "data": { "ok": true },
  "error": null,
  "artifacts": [{ "type": "link", "payload": { "url": "https://example.com" } }]
}