---
id: RT-TOOL-8
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-8
specification: FlowDrop Workflow Specification 1.0-draft
licence: CC BY 4.0
---

# RT-TOOL-8 — A model's tool arguments are normalized against the tool's own schema

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

Models hand back arguments that are nearly right: a JSON array as a string, a value escaped twice. Normalization repairs exactly the cases the tool's own schema can vouch for, and leaves the rest for validation to report honestly.

## The rule

> **Normative.** This is the rule.
>
> 1. Before a tool is invoked, the arguments a model supplied are reconciled with the tool's declared input schema.
>
> 2. A string argument is decoded as JSON only where all three hold: the schema declares that parameter `array` or `object`, the string parses as JSON, and the parsed shape matches what was declared: a list for `array`, a map for `object`.
>
> 3. A parameter declared `string` is never decoded, and a parsed value of the wrong shape is never substituted; an argument that fails any of the three is passed through unmodified.
>
> 4. Independently, every string leaf of an argument has its HTML character references decoded, repeated until the value stops changing so that a doubly-escaped value resolves fully rather than one level short; an implementation may bound the number of passes.
>
> 5. Keys are never modified, and text containing no character reference is returned unchanged.


## What it means

The two repairs are independent and run on different things. JSON-string
decoding looks only at whether the tool's own schema declares that
parameter `array` or `object`, and only fires when the parsed result
actually has that shape — a string that parses as JSON but produces the
wrong shape (an object where the schema declares an array) is left exactly
as sent, never coerced or substituted. Entity decoding, by contrast, runs on
every string leaf regardless of what the schema declares, repeating until
the value stops changing, so a doubly-escaped value resolves fully rather
than stopping one level short. Keys are never touched by either repair.

## Example

A title argument arrives HTML-escaped twice over:

```json title="A doubly-escaped title argument" verdict="sent"
{ "title": "Ember & Oak" }
```

```json title="What reaches the tool" verdict="decoded"
{ "title": "Ember & Oak" }
```

An object literal sent for a parameter the schema declares `array` is left
untouched rather than substituted into the wrong shape:

```json title="An object literal where the schema declares an array" verdict="sent"
{ "ops": "{\"op\":\"add\"}" }
```

## References

**Normative** — incorporated into this rule:

- HTML Standard, Named character references (https://html.spec.whatwg.org/multipage/named-characters.html) — The set of named references a string argument is decoded against.

---

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.