Tool Schemas

Schemas are enforced on both sides of the call. Arguments are validated before dispatch; results are validated before entering working memory.

Design rules#

1. 1Set additionalProperties: false. Unconstrained objects invite plausible-looking invented fields.
2. 2Constrain strings with enum, pattern or format wherever a finite set exists.
3. 3Bound arrays with maxItems. Unbounded fan-out is a cost and a reliability problem.
4. 4Prefer explicit identifiers over free text — warehouseId beats location.
5. 5Make the empty result representable. An empty array is a valid answer; an exception is not.
6. 6Return structured errors instead of prose. The runtime routes on error type, not on message text.

Validation failure handling#

{
  class="tok-str">"error": {
    class="tok-str">"type": class="tok-str">"rate_limited",
    class="tok-str">"retryable": true,
    class="tok-str">"retry_after_ms": class="tok-num">4200,
    class="tok-str">"detail": class="tok-str">"Upstream quota exhausted for connector.inventory",
    class="tok-str">"upstream_status": class="tok-num">429
  }
}