---
id: RT-TOOL-1
family: RT-TOOL
level: extended
profiles: [runtime]
posture: normative-target
added: "1.0"
changed: "1.0"
source: https://flowdrop.io/spec/rules/rt-tool/rt-tool-1
specification: FlowDrop Workflow Specification 1.0-draft
licence: CC BY 4.0
---

# RT-TOOL-1 — A tool result carries artifacts alongside its data, never inside it

*RT-TOOL (Part II) · level: extended · profiles: runtime · added in 1.0*

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.

## The rule

> **Normative.** This is the rule.
>
> 1. A tool result is `{success, data, error}`.
>
> 2. A result whose call attached structured artifacts carries an additional `artifacts` key, present only when at least one artifact was attached, so an artifact-free result keeps the plain three-key shape unchanged.
>
> 3. Artifacts are attached additively, and are never folded into `data`: the two are disjoint.


## 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

```json title="A result with nothing attached" verdict="plain"
{ "success": true, "data": { "ok": true }, "error": null }
```

```json title="The same result, once one artifact is attached" verdict="attached"
{
  "success": true,
  "data": { "ok": true },
  "error": null,
  "artifacts": [{ "type": "link", "payload": { "url": "https://example.com" } }]
}
```

## Related rules

- Names: RT-TOOL-2
- Referenced by: RT-TOOL-2

---

Rule identifiers are permanent and are never renumbered. This specification carries
no implementation status: each implementation publishes its own standing against
these rules. Licensed CC BY 4.0.