Skip to content

Automation foundation model for tiny devices: 2-bit, 8-29 MB, tool calls, ASR, structured extraction and embeddings on phones, wearables, smart homes, robots, cars and microcontrollers.

fix(docs): clarify argument processing and grounding in API documentation

HenryNdubuaku132b0860181e
diff --git a/doc/apis.md b/doc/apis.md
index 474c8fe..8159a3f 100644
--- a/doc/apis.md
+++ b/doc/apis.md
@@ -120,6 +120,7 @@ Needle solves every problem as a function call. The context declares what may be
- A request no declared tool can serve is refused with the empty call `[]`. That is the whole contract for off-topic input; there is no free-text fallback.
- Arguments contain only values evidenced by the input. An optional field with no evidence is omitted, not guessed; omission is the field-level `[]`.
- A date argument whose year matches none of the years written in the conversation so far or in the `system` facts is reported in `validation.ungrounded` as `tool.field`, alongside anything the engine itself flags as ungrounded. `run()` does not execute such a call; its result is `{"error": "ungrounded field"}` and the model continues from it. Pass `strict=False` to execute anyway.
+- Arguments arrive after the engine's deterministic repair step, which grounds them in the request text (first/last name split, phone completion, verbatim quoted titles, place queries with their street address, weekday and explicit dates resolved against the `date:` fact, empty optionals and duplicate calls dropped). Enumerated parameters are never altered.
- `reasoning` is the model's short derivation of each argument from its source span (`'ten minutes' -> minutes 10`). It is generated unconstrained; only the call itself is grammar-constrained, so the JSON cannot be malformed while the derivation stays legible.
- After you execute a call, pass the result back as the next `complete()`. The model continues from it, and later arguments may depend on earlier results: `search_for_contact` first, then `send_instant_message` with the returned `contact_id`. A final `"type": "respond"` with empty `function_calls` signals the loop is done; the answer is the tool results themselves, which `run()` collects on the final response as `results`. No free text is generated.
- An agent shares one toolset. Later turns are bare queries against the same tools; `reset()` rewinds the conversation and keeps the tools loaded.
diff --git a/llms.txt b/llms.txt
index 7a8d8d3..a8d1c8f 100644
--- a/llms.txt
+++ b/llms.txt
@@ -104,6 +104,7 @@ Every turn returns one dict:
- `reasoning` is a short unconstrained derivation of each argument from its source span.
- `confidence` is a calibrated score in [0,1] (see Confidence gating).
- `validation.ungrounded`, when present, lists `tool.field` names whose value is not grounded in the input, including date arguments whose year matches nothing in the conversation or the `system` facts. `run()` refuses those calls with `{"error": "ungrounded field"}` unless `strict=False`.
+- Arguments arrive after the engine's deterministic repair step, which grounds them in the request text: a full name in one of a first/last pair is split, a truncated phone number is completed, quoted titles are restored verbatim, place queries recover dropped words and a following street address, weekday and `March 4th` style dates resolve against the `date:` fact, empty optional strings and duplicate calls are dropped. Enumerated parameters are never altered.
## Behaviour contract (important for correct code)