assertToolCalled
Verify that a specific assistant tool was called after a user utterance by waiting for the matching tool_called event, anchored before injection to avoid missing late calls.
Instructions
Phase 4 — wait for an assistant.tool_called event matching name (and optionally argsMatch partial-match). Re-scans the backend event log every ~200ms from a FIXED anchor until match or timeout, then returns the matched event payload directly (or errors with tool_not_called on timeout). Pass sinceCursor — the watchCursor from the injectAssistantUtterance that triggered the tool. That anchors the wait BEFORE the inject, so the triggered tool call (which the model fires 0.5-2s later) is always caught even if this call starts after the tool already fired. Without sinceCursor the call anchors at its own start ("now") and will MISS a tool that fired in the gap between your inject and this call — the dominant false-negative cause before the 2026-05-29 fix. The fixed-anchor re-scan (vs an advancing cursor) also means a late-committing event is never skipped, and the match is pure seq-comparison so it has zero clock-skew dependency. USE in the agent E2E loop right after injectAssistantUtterance. DON'T USE to inspect the full event trace (use getEventLog) or to check static tool registration (use inspectIntegration).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Exact tool name to wait for. Must match the `name` argument passed to `tool(name, description) { ... }` in the customer's glasses.assistant.start { } block. | |
| argsMatch | No | Optional top-level partial match against the tool's parsed args. All keys in argsMatch must be present in the call's args with equal scalar values; nested objects compared structurally. v1 ships top-level partial-match only — nested glob patterns deferred. Omit for any-args match. | |
| sessionId | Yes | ||
| timeoutMs | No | Max time to wait, in ms. Default 5000. Clamped to [250, 60000]. The Mock provider dispatches in <50ms so 5000 is generous; OpenAi provider dispatches in 500-2000ms post-utterance (budget 10000+ for camera/vision tools). | |
| sinceCursor | No | **Strongly recommended.** The `watchCursor` value returned by the `injectAssistantUtterance` that should trigger this tool. Anchors the wait at the point BEFORE the inject, guaranteeing the triggered tool call is caught regardless of model latency or how quickly you call assertToolCalled. Omit only when watching for a tool with no preceding inject in this same agent turn (e.g. a tool fired by a real sim-browser voice turn) — then the call anchors at "now" and only catches tools that fire after this call starts. |