S03 · Tool Utilization

Declared state: complete for now.

This is the repository plan and evidence, not a live health reading. A task marked done may still depend on credentials, devices, deployment or a newer acceptance test.

Dependencies

No dependencies are declared in the catalog.

Tasks and gates

03.F1 · Typed failure contract everywhere — `tool_failed()`, `is_not_configured()`, no

Tier F · done · Verification: hermetic-test

Gate: `test_no_result_sentinels.py`, `test_tool_failure_guard.py`

  • unverified-import · undated · docs/SYSTEMS-DETAILS.md:1068

03.F2 · Missing-argument handling asks rather than fabricates. *gate:* `test_missing_arg.py`

Tier F · done · Verification: hermetic-test

Gate: `test_missing_arg.py`

  • unverified-import · undated · docs/SYSTEMS-DETAILS.md:1070

03.F4 · **A ceiling on tool results at the boundary.** `agent.py` appends `str(result)` into

Tier F · done · Verification: hermetic-test

Gate: `test_tool_result_ceiling.py` 15/15.

  • unverified-import · undated · docs/SYSTEMS-DETAILS.md:1071

03.F3 · **Catalogue narrowing is measured, not assumed.** Per-turn tool count and token cost land

Tier F · done · Verification: hermetic-test

Gate: `test_speed.py` asserts a hard ceiling on presented-catalogue tokens, read from the

  • unverified-import · undated · docs/SYSTEMS-DETAILS.md:1079

03.R1 · TWO-STAGE TOOL SELECTION: the same work as `03.R7`, which carries the measurement and the matching gate. Kept open rather than cancelled, because merging two registry ids is the owner's call and not a bookkeeping edit. A cheap router picks a *family* (10–20 tools), the model picks

Tier R · in-progress · Verification: hermetic-test

Gate: `test_catalogue_narrowing.py` 32/32 (DUPLICATE of 03.R7, same gate) — 60 prompts, correct tool still reachable ≥98% at

  • recorded-note · undated · docs/systems-plan.json 03.R7
  • hermetic-green · undated · bench/test_catalogue_narrowing.py

03.R2 · Argument validation before dispatch, with a repair prompt on the first failure only.

Tier R · done · Verification: hermetic-test

Gate: `test_reminder_args.py` (14), `test_tool_error_handling.py` [03.R2] (82)

  • recorded-note · 2026-09-14 · docs/SYSTEMS-DETAILS.md:1100

03.R3 · Chaining: a result that obviously feeds another (search→open, contact→message) chains in

Tier R · done · Verification: planned-test

Gate: new `test_tool_chaining.py` (29)

  • recorded-note · 2026-09-14 · docs/SYSTEMS-DETAILS.md:1124

03.R4 · Dead-tool sweep: every tool not fired in 90 days is either exercised by a bench case or

Tier R · done · Verification: hermetic-test

Gate: `test_tool_usage.py` [03.R4] (24) + `test_tool_error_handling.py` (82)

  • recorded-note · 2026-09-14 · docs/SYSTEMS-DETAILS.md:1146

03.R5 · **Schema minification.** The catalogue is the dominant per-turn cost and its *size* has

Tier R · done · Verification: planned-test

Gate: new `test_catalogue_budget.py` (27) + `test_speed.py` [catalogue-tokens] ratcheted;

  • recorded-note · 2026-09-14 · docs/SYSTEMS-DETAILS.md:1164

03.R6 · **Speculative dispatch, read tier only.** When the router is confident, start the likely

Tier R · open · Verification: planned-test

Gate: new `test_speculative_dispatch.py` - planned gate. new `test_speculative_dispatch.py` — a confirm-tier tool is never dispatched

    03.E1 · Wrong-tool selection <2% across the behavioural suite (the original 74.8 diagnosis was

    Tier E · open · Verification: unregistered-test

    Gate: `behavioral_suite.py` per-turn tool audit.

      03.R7 · **Two-stage tool router** — the 152-schema surface scored 0.85/4 at confidence 0.81, *too large*, and Jev calls the router necessary rather than optional.

      Tier R · in-progress · Verification: hermetic-test

      Gate: `test_catalogue_narrowing.py` 32/32 — stage one narrows to a candidate set and stage two selects, measured: 60 hand-written prompts reach the right group, per-turn schema tokens fall from 19,069 to a median of 7,792, and the three triggers that mis-fired are gone.

      • hermetic-green · undated · bench/test_catalogue_narrowing.py

      03.R8 · A router miss is recovered inside the turn: a core open_tools tool lists every lazy group in one line, and opening one adds its tools to the next pass of the same turn.

      Tier R · done · Verification: hermetic-test

      Gate: `test_open_tools.py` - every lazy group has a hint and is in the enum; the tool costs <450 tokens and is never on pure chat; on both response paths a miss opens the group, its tools join on the next pass, the answer comes from them, and the group stays warm one turn.

      • hermetic-green · 2026-10-17 · bench/test_open_tools.py

      HUD screen contracts

      All subsystems · Source: docs/systems-plan.json.