@tomtom-org/maps-sdk-plugin-agent-toolkit 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -10,7 +10,7 @@ import { LanguageModel, ModelMessage, PrepareStepFunction, ToolLoopAgent } from
 type JobSpec = {
   /** Ids of every entry this job reads. The engine re-runs the job when any of them changes. */
   affectedEntryIds: readonly string[];
-  /** The recipe, opaque to the engine — stored as the single home of the code + for re-arm change-detect. */
+  /** The recipe, opaque to the engine and the single home of the code, compared on re-arm to detect change. */
   code: string;
   /** Whether the engine scans this job. A paused job (`false`) is retained but never run. */
   active: boolean;
@@ -21,20 +21,20 @@ type JobSpec = {
 };
 /** A registered job, handed back to the owner as the reference linking a sink record to its recurrence. */
 interface Job {
-  /** Ids of every entry this job reads (immutable; a re-arm with different sources is a different job). */
+  /** Ids of every entry this job reads (immutable, as a re-arm with different sources is a different job). */
   readonly affectedEntryIds: readonly string[];
-  /** The recipe behind this job — compared on re-arm to decide whether to drop stale history. */
+  /** The recipe behind this job, which a re-arm compares to decide whether to drop stale history. */
   readonly code: string;
   /** Whether the engine currently scans this job. */
   readonly active: boolean;
-  /** Pause (`false`) or resume (`true`) scanning. A paused job keeps its recipe for later promotion. */
+  /** Pauses (`false`) or resumes (`true`) scanning. A paused job keeps its recipe for later promotion. */
   setActive(active: boolean): void;
-  /** Remove the job from the engine. The owner drops its stored reference. */
+  /** Removes the job from the engine. The owner drops its stored reference. */
   unregister(): void;
 }
 /**
- * Session-level recurrence engine. Held on `ToolState` as `state.engine`; constructed and wired by the
- * state factory. Owners ({@link Analyses}, {@link EventsState}) register jobs and keep the returned
+ * Session-level recurrence engine, held on `ToolState` as `state.engine`, which the state factory
+ * constructs and wires. Owners ({@link Analyses}, {@link EventsState}) register jobs and keep the returned
  * handles.
  *
  * @group Agent Toolkit
@@ -45,12 +45,12 @@ declare class JobEngine {
   private scanning;
   private scheduled;
   private pending;
-  /** Register a job and return its handle. Stored by the owner as its reference to the recurrence. */
+  /** Registers a job and returns its handle, which the owner stores as its reference to the recurrence. */
   register(spec: JobSpec): Job;
   /** @internal — called by {@link JobHandle.unregister}. */
   drop(job: JobHandle): void;
   /**
-   * Subscribe the scan to every input slice's `entries-change`, exactly once per session. The state
+   * Subscribes the scan to every input slice's `entries-change`, exactly once per session. The state
    * factory calls this at construction (it holds the slices), so every `ToolState` gets a live engine
    * without the job builders having to wire lazily.
    */
@@ -61,7 +61,7 @@ declare class JobEngine {
   private hasActiveJob;
   private scheduleScan;
   private runScan;
-  /** Drop every job. Walked automatically by `destroyState` (duck-typed `reset`). Subscriptions persist
+  /** Drops every job. `destroyState` calls it automatically (duck-typed `reset`). Subscriptions persist
    * (harmless without jobs), mirroring the one-shot `wired` guard. */
   reset(): void;
 }
@@ -80,8 +80,8 @@ declare class JobHandle implements Job {
 //#region src/tools/shared/sandbox-code.d.ts
 export type AnalysisOutputFormat = 'json' | 'chart';
 /**
- * Compact sandbox-code blurb shared by `process-places`, `process-geometries`,
- * `analyse-places`, `analyse-geometries`, and `analyse-routes`. Keeps the
+ * Compact sandbox-code blurb shared by every code-generation tool, through
+ * `buildSandboxToolsDoc`. Keeps the
  * "what's in scope / what's forbidden" rules short and consistent across all
  * code-generation tools so the LLM is prompted the same way each time. Pass
  * the names of the injected identifiers (the params the AsyncFunction body
@@ -118,11 +118,11 @@ export declare const ANALYSE_OUTPUT_FORMAT_DESCRIPTION: string;
  */
 export declare const buildAnalyseReturnPrompt: (jsonExamples: string, chartLabelExample?: string) => string;
 /**
- * Validates the value returned by analyse-* sandboxed code: rejects
+ * Validates the value returned by sandboxed code: rejects
  * `undefined`, JSON-normalizes via `toJsonSafe`, and — when
  * `outputFormat: "chart"` — checks the result is a Chart.js
- * `ChartConfiguration`. Centralises the contract shared by analyse-places,
- * analyse-routes, and analyse-geometries.
+ * `ChartConfiguration`. Centralises the contract shared by `analyseData` and every
+ * recurring re-run (`sandbox-replay.ts`: monitored analyses, trackers, `clusterIncidents` code).
  *
  * @ignore
  */
@@ -137,11 +137,11 @@ export declare const sandboxedGlobalShadows: readonly ["fetch", "XMLHttpRequest"
 export declare const WORKER_PROVIDED_PARAMS: readonly ["turf", "h3", "routeUtils", "log", "cluster"];
 /**
  * Pluggable strategy for executing sandbox code. The default
- * {@link mainThreadExecutor} compiles + runs in the host realm; an alternative
- * executor (e.g. the iframe-worker one) can run the same code in a locked-down
+ * {@link mainThreadExecutor} compiles and runs in the host realm. An alternative
+ * executor, such as the iframe-worker one, can run the same code in a locked-down
  * realm off the main thread while honouring this exact contract.
  *
- * `run` MUST resolve to `{ value }` or `{ error }` and never reject — execution
+ * `run` MUST resolve to `{ value }` or `{ error }` and never reject. Execution
  * failures are reported as `{ error }` via {@link formatSandboxExecutionError}.
  *
  * @group Agent Toolkit
@@ -152,7 +152,7 @@ export type SandboxExecutor = {
   } | {
     error: string;
   }>;
-  /** Release any held resources (iframe / worker). No-op for the main-thread executor. */
+  /** Releases any held resources (iframe / worker). No-op for the main-thread executor. */
   destroy?(): void;
 };
 /**
@@ -168,7 +168,7 @@ export declare const mainThreadExecutor: SandboxExecutor;
  * Compiles `code` as the body of an `async` function that takes the named
  * `paramNames`, sanitises injected redeclarations, runs it with `args`, and
  * returns either `{ value }` or `{ error }`. Centralises the AsyncFunction
- * dance shared by every sandbox-running tool (analyse-* and process-*) so
+ * dance shared by every sandbox-running tool (analyseData, processData, createTracker, clusterIncidents) so
  * each callsite only owns its inputs and result handling.
  *
  * In addition to the caller's `paramNames`, a fixed set of network / storage /
@@ -207,18 +207,18 @@ export declare const formatSandboxExecutionError: (verb: string, error: unknown)
 /**
  * @module agent-toolkit-state
  *
- * Tiny typed event emitter used by every state slice (PlacesState, RoutingState, ...) to notify
- * subscribers when their internals change. The shape mirrors the SDK's `ModuleEvents` API
- * (`on(type, handler) => unsubscribe`, `off(type)`) so consumers see one consistent pattern across
- * the SDK and the agent toolkit. Designed to plug straight into React's `useSyncExternalStore`.
+ * A tiny typed event emitter that every state slice (PlacesState, RoutingState, ...) uses to notify
+ * subscribers when its internals change. Its shape mirrors the SDK's `ModuleEvents` API
+ * (`on(type, handler) => unsubscribe`, `off(type)`), so consumers see one consistent pattern across
+ * the SDK and the agent toolkit. It plugs straight into React's `useSyncExternalStore`.
  *
  * @group Agent Toolkit
  */
 /**
- * Generic typed event bus. The `EventMap` parameter declares the set of event names this emitter
- * supports along with each event's payload type — `on` and `emit` are then strongly typed against it.
+ * A generic typed event bus. The `EventMap` parameter declares the event names this emitter supports
+ * and each event's payload type, and `on` and `emit` are strongly typed against it.
  *
- * Usage from outside the slice (subscribe-only):
+ * Outside the slice, you can only subscribe:
  * ```ts
  * const unsub = state.places.events.on('entries-change', ({ entries }) => render(entries));
  * // ...
@@ -230,10 +230,10 @@ export declare const formatSandboxExecutionError: (verb: string, error: unknown)
 declare class StateEvents<EventMap extends Record<string, unknown>> {
   private readonly handlers;
   /**
-   * Subscribe to an event. Returns an unsubscribe function that removes only this handler.
+   * Subscribes to an event and returns an unsubscribe function that removes only this handler.
    */
   on<K extends keyof EventMap>(type: K, handler: (payload: EventMap[K]) => void): () => void;
-  /** Remove all handlers for a given event type. Use the unsubscribe from `on` for single-handler removal. */
+  /** Removes all handlers for an event type. To remove one handler, call the unsubscribe `on` returns. */
   off<K extends keyof EventMap>(type: K): void;
   /**
    * Fire an event. Internal — only the owning slice should call this. We don't make it `protected`
@@ -243,7 +243,7 @@ declare class StateEvents<EventMap extends Record<string, unknown>> {
    * @internal
    */
   emit<K extends keyof EventMap>(type: K, payload: EventMap[K]): void;
-  /** Drop every handler for every type. Used by slice `reset()` to detach lingering listeners. */
+  /** Removes every handler for every type. A slice's `reset()` calls it to detach lingering listeners. */
   clear(): void;
 }
 //#endregion
@@ -268,12 +268,12 @@ type EntryAnalysis = {
   data: unknown;
 };
 /**
- * One analysis tracked by the session-level {@link Analyses} registry — the single home for every
- * `analyseData` analysis, one-shot or monitored, across every entry kind. Pure sink state: metadata plus
- * the bounded result `history`. The recipe (`code` / `inputs`) and recurrence are NOT here — they live on
- * the analysis's {@link Job} (see `_jobs`). `affectedEntryIds` is the per-entry lookup key
- * ({@link Analyses.getAnalysesForEntry}); `history` is the result timeline (oldest first), whose latest
- * is the current result and is threaded back into the sandbox code as `previous`.
+ * One analysis tracked by the session-level {@link Analyses} registry, the single home for every
+ * `analyseData` analysis, one-shot or monitored, across every entry kind. It is pure sink state,
+ * metadata plus the bounded result `history`. The recipe (`code` / `inputs`) and recurrence are NOT
+ * here. They live on the analysis's {@link Job} (see `_jobs`). `affectedEntryIds` is the per-entry
+ * lookup key ({@link Analyses.getAnalysesForEntry}). `history` is the result timeline (oldest first),
+ * whose latest is the current result, threaded back into the sandbox code as `previous`.
  *
  * @group Agent Toolkit
  */
@@ -289,8 +289,8 @@ type AnalysisRecord = {
   history: EntryAnalysis[];
 };
 /**
- * {@link Analyses.register} input — the record's metadata. No `history` (the registry builds that as
- * results land) and no recipe (that lives on the {@link Job}).
+ * The input of {@link Analyses.register}, the record's metadata. It has no `history` (the registry
+ * builds that as results land) and no recipe (that lives on the {@link Job}).
  *
  * @group Agent Toolkit
  */
@@ -311,15 +311,15 @@ type AnalysesEvents = {
   };
 };
 /**
- * Session-level registry of EVERY analysis — the single source of truth that replaces the per-entry
- * `_analyses` stores. Holds one {@link AnalysisRecord} per analysis (keyed by `analysisId`), each with
- * its own bounded result history. Entries carry no analysis state; per-entry views call
- * {@link getAnalysesForEntry}. Held on `ToolState` as `state.analyses`.
+ * The session-level registry of EVERY analysis, the single source of truth that replaces the per-entry
+ * `_analyses` stores. It holds one {@link AnalysisRecord} per analysis (keyed by `analysisId`), each
+ * with its own bounded result history. Entries carry no analysis state. Per-entry views call
+ * {@link getAnalysesForEntry}. `ToolState` holds it as `state.analyses`.
  *
- * Pure sink: metadata + result history only. The recurrence lives on the {@link JobEngine}; this
- * registry keeps each monitored analysis's {@link Job} handle in `_jobs` (keyed by `analysisId`) so it
- * can pause/resume it ({@link job}) or compare its `code` on re-arm. A one-shot analysis keeps a paused
- * job for later promotion.
+ * It is a pure sink of metadata and result history. The recurrence lives on the {@link JobEngine}.
+ * This registry keeps each monitored analysis's {@link Job} handle in `_jobs` (keyed by `analysisId`)
+ * so it can pause or resume it ({@link job}) or compare its `code` on re-arm. A one-shot analysis keeps
+ * a paused job for later promotion.
  *
  * @group Agent Toolkit
  */
@@ -327,36 +327,37 @@ declare class Analyses {
   private readonly _records;
   /** analysisId → the {@link Job} backing it (one-shot = paused). The reference linking record to engine. */
   private readonly _jobs;
-  /** Subscribe to {@link AnalysesEvents} — fired whenever a result is attached or recomputed. */
+  /** The {@link AnalysesEvents} emitter, fired whenever a result is attached or recomputed. */
   readonly events: StateEvents<AnalysesEvents>;
   /**
-   * Insert or replace a record's metadata (NOT its result — use {@link attachResult}; nor its recipe —
-   * that lives on the {@link Job}). Re-registering an existing `analysisId` preserves its result
-   * history; callers drop stale history explicitly via {@link resetHistory} when the recipe changes.
+   * Inserts or replaces a record's metadata, NOT its result (use {@link attachResult}) or its recipe,
+   * which lives on the {@link Job}. Re-registering an existing `analysisId` preserves its result
+   * history. Callers drop stale history explicitly with {@link resetHistory} when the recipe changes.
    */
   register(input: AnalysisRegistration): void;
-  /** Store the {@link Job} backing an analysis — the reference linking this record to the engine. */
+  /** Stores the {@link Job} backing an analysis, the reference linking this record to the engine. */
   setJob(analysisId: string, job: Job): void;
   /** The {@link Job} backing an analysis, if monitored or a retained one-shot. */
   job(analysisId: string): Job | undefined;
-  /** Drop an analysis's result history — called on re-arm when the recipe changed (stale `previous`). */
+  /** Drops an analysis's result history. A re-arm calls it when the recipe changed (stale `previous`). */
   resetHistory(analysisId: string): void;
   /**
-   * Append a result to a record's timeline, evicting the oldest when the per-analysis cap is hit. A
+   * Appends a result to a record's timeline, evicting the oldest when the per-analysis cap is hit. A
    * same-timestamp re-run (an id-stability re-read of an unchanged snapshot) overwrites the last entry
-   * rather than duplicating it. No-op (no emit) when the `analysisId` is unknown. Emits `analysis-change`.
+   * rather than duplicating it. It emits `analysis-change`, unless the `analysisId` is unknown
+   * (a no-op).
    */
   attachResult(analysisId: string, result: EntryAnalysis): void;
   /**
-   * Latest result of every analysis attached to `entryId`, in registration order. The on-demand
-   * replacement for the old per-entry `_analyses.results`. Linear scan over records — fine at session
-   * scale (one record per distinct analyseData name+sources, plus one per clustered incidents entry).
+   * Returns the latest result of every analysis attached to `entryId`, in registration order,
+   * replacing the old per-entry `_analyses.results`. It scans records linearly, fine at session scale
+   * (one record per distinct analyseData name+sources, plus one per clustered incidents entry).
    */
   getAnalysesForEntry(entryId: string): readonly EntryAnalysis[];
   /**
-   * Every analysis record, in registration order — the combined, cross-entry view. Read
-   * `record.history.at(-1)` for each one's latest result. (Tracker verdicts are no longer analyses, so
-   * every record here is operator-facing.)
+   * Returns every analysis record in registration order, the combined cross-entry view. Read
+   * `record.history.at(-1)` for each one's latest result. Tracker verdicts are not analyses, so every
+   * record here is operator-facing.
    */
   all(): readonly AnalysisRecord[];
   /** Full result timeline for one analysis, oldest first. Empty when unknown. */
@@ -366,14 +367,14 @@ declare class Analyses {
   get(analysisId: string): AnalysisRecord | undefined;
   /** Whether the analysis is currently recomputed on source change (its job exists and is active). */
   isMonitored(analysisId: string): boolean;
-  /** Remove an analysis: tear down its job and drop the record + handle. */
+  /** Removes an analysis, tearing down its job and dropping the record and handle. */
   remove(analysisId: string): void;
   /**
-   * Remove every record sharing a `name`, across all source entries. Mirrors the old per-entry
-   * `unregister(name)` which dropped a named analysis wherever it was attached.
+   * Removes every record sharing a `name`, across all source entries, as the old per-entry
+   * `unregister(name)` dropped a named analysis wherever it was attached.
    */
   removeByName(name: string): void;
-  /** Drop every record + job handle. Walked automatically by `destroyState` (duck-typed `reset`). */
+  /** Drops every record and job handle. `destroyState` calls it automatically (duck-typed `reset`). */
   reset(): void;
 }
 //#endregion
@@ -568,39 +569,38 @@ interface FeatureCollection$1<G extends Geometry | null = Geometry, P = GeoJsonP
 /**
  * @module agent-toolkit-state
  *
- * Shared base shape for the per-slice history entries (places / routes / ranges / byod /
- * custom-geometries / traffic-area-analytics / traffic-incidents). Every slice keeps an append-only
- * history of entries, and they all share the same four fields — an `id`, a `timestamp`, a `label`,
- * and a single `data` payload. Those live here so each slice's entry type can be written as
- * `BaseEntry<TPayload> & { … }` plus only the fields unique to that slice (its per-entry display and
- * runtime state).
+ * The shared base shape for the per-slice history entries of places, routes, ranges, byod,
+ * custom-geometries, traffic-area-analytics and traffic-incidents. Every slice keeps an append-only
+ * history of entries that share four fields: an `id`, a `timestamp`, a `label`, and a single `data`
+ * payload. They live here, so each slice's entry type is `BaseEntry<TPayload> & { … }` plus only the
+ * fields unique to that slice, its per-entry display and runtime state.
  *
  * @group Agent Toolkit
  */
 /**
- * The fields shared by every history entry across the toolkit's state slices: identity
- * (`id`), provenance (`timestamp`, `label`), and the slice's payload (`data`). Each slice intersects
- * this with its own per-entry display state — e.g. `type RoutesEntry = BaseEntry<Routes> & { … }`.
+ * The fields every history entry shares across the toolkit's state slices, namely identity
+ * (`id`), provenance (`timestamp`, `label`) and the slice's payload (`data`). Each slice intersects
+ * this with its own per-entry display state, such as `type RoutesEntry = BaseEntry<Routes> & { … }`.
  *
- * @typeParam TData - the entry's payload type (e.g. `Routes`, `Place[]`, `FeatureCollection`,
- * `TrafficIncident[]`). It is the single result the entry was created to hold.
+ * @typeParam TData - The entry's payload type, such as `Routes`, `Place[]`, `FeatureCollection` or
+ * `TrafficIncident[]`. It is the single result the entry was created to hold.
  *
  * @group Agent Toolkit
  */
 type BaseEntry<TData> = {
   /**
-   * Stable, slice-unique entry id (e.g. `places-0`, or a caller-supplied id deduped against
-   * existing entries on collision). Used to address the entry from tools and recall surfaces.
+   * The stable, slice-unique entry id, such as `places-0` or a caller-supplied id deduped against
+   * existing entries on collision. Tools and recall surfaces address the entry by it.
    */
   id: string;
   /**
-   * Creation / last-refresh time, in milliseconds since the epoch. Set when the entry is added and
-   * bumped on each in-place replace (a monitored re-run stamps the source sample time).
+   * The creation or last-refresh time, in milliseconds since the epoch. It is set when the entry is
+   * added and bumped on each in-place replace. A monitored re-run stamps the source sample time.
    */
   timestamp: number;
-  /** Short, human-readable label for the entry — shown in recall / recents surfaces. */
+  /** A short, human-readable label, shown in recall and recents surfaces. */
   label: string;
-  /** The entry's payload — the single result this entry was created to hold. */
+  /** The entry's payload, the single result it was created to hold. */
   data: TData;
 };
 //#endregion
@@ -700,7 +700,7 @@ type BYODEntry = BaseEntry<FeatureCollection$1> & {
 /**
  * State for base map display: style, language, viewport and layers.
  *
- * Provides direct access to the TomTomMap and MapLibre instances alongside
+ * It exposes the TomTomMap and MapLibre instances directly, alongside
  * lazy-initialized BaseMapModule, StylingFoundationsModule and TerrainModule.
  *
  * @group Agent Toolkit
@@ -910,18 +910,18 @@ export declare const applyFitOnMap: (state: ToolState, fit: FitOnMapInput) => z.
 //#endregion
 //#region src/tools/shared/geocode-areas.d.ts
 /**
- * Administrative-AREA geography types accepted when resolving a query to a *containing area*
- * (`within` mode). Restricting the geocode to these (via `entityTypeSet`) is what stops streets and
- * POIs from drowning the area — e.g. "De Pijp" / "Westminster" geocode to Streets at rank 0 without
- * it. Excludes `Country` (too coarse) and `PostalCodeArea` (homonym noise — "A10" → a Kazakh
- * postcode).
+ * Administrative-area geography types accepted when resolving a query to a *containing area*
+ * (`within` mode). Restricting the geocode to these (via `entityTypeSet`) stops streets and POIs
+ * from drowning the area. Without it, "De Pijp" and "Westminster" geocode to Streets at rank 0.
+ * Excludes `Country` (too coarse) and `PostalCodeArea` (homonym noise, such as "A10" matching a
+ * Kazakh postcode).
  */
 export declare const AREA_GEOGRAPHY_TYPES: GeographyType[];
 /**
- * Geocodes `query` restricted to administrative AREA geographies (not streets/POIs), biased toward
+ * Geocodes `query` restricted to administrative area geographies (not streets/POIs), biased toward
  * `bias` (the map centre). Because `geographyTypes` filters to areas, every result carries a
- * `boundingBox`. Callers choose among the candidates (e.g. the one nearest the current view) — a
- * centre bias is used rather than a hard viewport-bbox filter so out-of-view areas still resolve.
+ * `boundingBox`. Callers choose among the candidates, for example the one nearest the current view.
+ * A centre bias is used rather than a hard viewport-bbox filter, so out-of-view areas still resolve.
  */
 export declare const geocodeAreas: (query: string, opts?: {
   bias?: Position;
@@ -937,8 +937,8 @@ export declare const geocodeAreas: (query: string, opts?: {
 export type GeometriesIdKind = 'place' | 'places' | 'ranges' | 'customGeometries';
 /**
  * Tagged geometries id. The Zod schema is exposed so tools can plug it
- * straight into their input shape (`z.array(geometriesIdSchema).min(1)`)
- * — no string parsing on the way in.
+ * straight into their input shape (`z.array(geometriesIdSchema).min(1)`),
+ * with no string parsing on the way in.
  *
  * @group Agent Toolkit
  */
@@ -1007,10 +1007,10 @@ export declare const GEOMETRIES_SOURCE_IDS_DESC = "Tagged input ids that contrib
  * @module agent-toolkit-tools
  *
  * Compact schema doc for the geometry polygons consumed/produced by sandboxed
- * code in `processData` / `analyseData` — injected per source as
+ * code in `processData` / `analyseData`, injected per source as
  * `geometriesByEntry[key]`. Each item is a
- * `PolygonFeature<CommonPlaceProps>`; only the non-GeoJSON-standard bits are
- * spelled out here.
+ * `PolygonFeature<CommonPlaceProps>`, and only its non-GeoJSON-standard bits
+ * are spelled out here.
  */
 /** @ignore */
 export declare const GEOMETRIES_SCHEMA_DOC: string;
@@ -1029,8 +1029,8 @@ type CustomGeometriesAnalysis = EntryAnalysis;
 //#endregion
 //#region src/state/digest.d.ts
 /**
- * Compact snapshot of the user-visible parts of `ToolState`. Designed to be diffable: every field
- * is serialisable to JSON and stable for `===` comparison when the underlying state hasn't changed.
+ * A compact, diffable snapshot of the user-visible parts of `ToolState`. Every field serialises to
+ * JSON and stays stable for `===` comparison while the underlying state is unchanged.
  *
  * @group Agent Toolkit
  */
@@ -1040,25 +1040,25 @@ type StateDigest = {
     shownAsPin: string[];
     /** Entry ids currently rendered as base-map POIs, sorted ascending. */
     shownAsBaseMap: string[];
-    /** Display policy in force on the slice — `multiple` (default) or `single`. */
+    /** The slice's display policy, `multiple` (default) or `single`. */
     entryMode: EntryMode;
   };
   routes: {
     /** Routes-entry ids currently drawn on the map, sorted ascending. */
     shown: string[];
-    /** Display policy in force on the slice — `multiple` (default) or `single`. */
+    /** The slice's display policy, `multiple` (default) or `single`. */
     entryMode: EntryMode;
   };
   ranges: {
     /** Range-entry ids currently drawn on the map, sorted ascending. */
     shown: string[];
-    /** Display policy in force on the slice — `multiple` (default) or `single`. */
+    /** The slice's display policy, `multiple` (default) or `single`. */
     entryMode: EntryMode;
   };
   traffic: {
     /** Traffic-area-analytics entry ids currently rendered on the map, sorted ascending. */
     shown: string[];
-    /** Display policy in force on the slice — `multiple` (default) or `single`. */
+    /** The slice's display policy, `multiple` (default) or `single`. */
     entryMode: EntryMode;
     /** Total traffic-area-analytics entries in history (shown + hidden). */
     entryCount: number;
@@ -1068,13 +1068,13 @@ type StateDigest = {
     shown: string[];
     /** Entry ids currently being polled by the per-entry network monitor, sorted ascending. */
     monitored: string[];
-    /** Display policy in force on the slice — `multiple` (default) or `single`. */
+    /** The slice's display policy, `multiple` (default) or `single`. */
     entryMode: EntryMode;
   };
   customGeometries: {
     /** Custom-geometries entry ids currently rendered on the map, sorted ascending. */
     shown: string[];
-    /** Display policy in force on the slice — `multiple` (default) or `single`. */
+    /** The slice's display policy, `multiple` (default) or `single`. */
     entryMode: EntryMode;
     /** Total custom-geometries entries in history (shown + hidden). */
     entryCount: number;
@@ -1082,23 +1082,23 @@ type StateDigest = {
   byod: {
     /** BYOD entry ids currently rendered on the map, sorted ascending. */
     shown: string[];
-    /** Display policy in force on the slice — `multiple` (default) or `single`. */
+    /** The slice's display policy, `multiple` (default) or `single`. */
     entryMode: EntryMode;
     /** Total BYOD entries in history (shown + hidden). */
     entryCount: number;
   };
 };
 /**
- * Snapshot the user-visible state surface. Call after every assistant turn (to record the
- * "agent-known" baseline) and again before each user prompt (to detect what changed since).
+ * Takes a snapshot of the user-visible state surface. Call it after every assistant turn to record
+ * the "agent-known" baseline, and again before each user prompt to detect what changed since.
  *
  * @group Agent Toolkit
  */
 export declare const getStateDigest: (state: ToolState) => StateDigest;
 /**
- * Produce a compact, LLM-readable summary of the differences between two digests, or `null` when
+ * Returns a compact, LLM-readable summary of the differences between two digests, or `null` if
  * nothing changed. The output is short enough to prepend to a user prompt without bloating the
- * conversation; longer per-field diffs are deliberately omitted.
+ * conversation, so it deliberately omits longer per-field diffs.
  *
  * @example
  * ```ts
@@ -1143,12 +1143,12 @@ type PlacesAnalysis = EntryAnalysis;
 //#endregion
 //#region src/state/places/state.d.ts
 /**
- * The marker looks an entry can be rendered with: individual pins, base-map POIs, or clustered
- * pins. A type-checked subset of the SDK's `PlacesMarkerType` — `circle-icon` is not offered to
- * the agent. Every tool enum for marker types derives from this array rather than repeating it.
+ * The marker looks an entry can render with, namely individual pins, base-map POIs, or clustered
+ * pins. It is a type-checked subset of the SDK's `PlacesMarkerType` that doesn't offer `circle-icon`
+ * to the agent. Every tool enum for marker types derives from this array instead of repeating it.
  */
 declare const placesMarkerTypes: readonly ["pin", "base-map", "pin-clustered"];
-/** How an entry is rendered on the map — one of {@link placesMarkerTypes}. */
+/** How an entry renders on the map, one of {@link placesMarkerTypes}. */
 type PlacesMarkerType = (typeof placesMarkerTypes)[number];
 /**
  * Events fired by {@link PlacesState}. Subscribe via `state.places.events.on(type, handler)`.
@@ -1157,33 +1157,33 @@ type PlacesMarkerType = (typeof placesMarkerTypes)[number];
  */
 type PlacesStateEvents = {
   /**
-   * History changed — entry added, replaced, or cleared via `reset()`. `entries` is the full
-   * snapshot after the change; `changedIds` lists the ids of the entries this specific change
-   * added, replaced in place, or removed (the {@link JobEngine} matches these against each job's
-   * `affectedEntryIds`).
+   * An entry was added or replaced, or `reset()` cleared the history. `entries` is the full
+   * snapshot after the change, and `changedIds` lists the ids of the entries this change added,
+   * replaced in place, or removed. The {@link JobEngine} matches these against each job's
+   * `affectedEntryIds`.
    */
   'entries-change': {
     entries: readonly PlacesEntry[];
     changedIds: readonly string[];
   };
-  /** Set of entries currently rendered on the map changed (or marker type swapped). */
+  /** The set of entries rendered on the map, or a marker type, changed. */
   'shown-change': ReadonlySet<string>;
   /** Boundary polygons were fetched and cached on an entry. */
   'geometries-change': {
     entryId: string;
     count: number;
   };
-  /** Display policy switched between `single` and `multiple`. */
+  /** The display policy switched between `single` and `multiple`. */
   'mode-change': EntryMode;
 };
 /**
- * State for the places layer: an append-only history of place results plus per-entry display
+ * The state for the places layer, an append-only history of place results plus per-entry display
  * modules.
  *
- * Each entry owns a single PlacesModule (switched in place via `updateConfig` when the marker
- * type changes — an entry only renders under one marker type at a time) and a dedicated
- * GeometriesModule, lazy-initialised on first show. Display state lives on the entry, so two
- * entries can be rendered side by side under different marker types without sharing a single source.
+ * Each entry owns a single PlacesModule and a dedicated GeometriesModule, both initialised lazily
+ * on first show. An entry renders under one marker type at a time, so `updateConfig` switches its
+ * PlacesModule in place when the marker type changes. Display state lives on the entry, so two
+ * entries can render side by side under different marker types without sharing a single source.
  *
  * @group Agent Toolkit
  */
@@ -1191,37 +1191,38 @@ declare class PlacesState implements StateSlice {
   private readonly _ttMap;
   private _entries;
   private _entryMode;
-  /** Subscribe to state changes — see {@link PlacesStateEvents}. */
+  /** The state change events, listed in {@link PlacesStateEvents}. */
   readonly events: StateEvents<PlacesStateEvents>;
   constructor(_ttMap: TomTomMap);
   /**
-   * Display policy: `multiple` (default) keeps every history entry available to render
-   * simultaneously; `single` enforces "at most one entry on the map at a time" and trims
-   * the history down to the latest entry whenever it's set.
+   * The display policy. `multiple` (default) keeps every history entry available to render
+   * simultaneously. `single` allows at most one entry on the map at a time and trims the
+   * history to the latest entry whenever it's set.
    */
   get entryMode(): EntryMode;
   /**
-   * Switch the display policy. When moving from `multiple` → `single` we hide every entry
-   * older than the latest, drop them from history, and emit `entries-change` so listeners
-   * (the recents rail, recall tools, …) re-render. No-op when the mode hasn't changed.
+   * Switches the display policy. Moving from `multiple` to `single` hides every entry older
+   * than the latest, drops them from history, and emits `entries-change` so listeners (the
+   * recents rail, recall tools, …) re-render. Does nothing if the mode hasn't changed.
    */
   setEntryMode(mode: EntryMode): Promise<void>;
   /**
-   * Lazy-init and return the entry's PlacesModule, switched to `markerType`. An entry only
-   * ever renders under one marker type at a time, so the same module is reused — flipping marker
-   * types calls `updateConfig` in place. Throws when the entry id is unknown.
+   * Returns the entry's PlacesModule, created on first call and switched to `markerType`. An entry
+   * renders under only one marker type at a time, so flipping marker types reuses the same module
+   * and calls `updateConfig` in place. Throws if the entry id is unknown.
    */
   getEntryPlacesModule(entryId: string, markerType: PlacesMarkerType): Promise<PlacesModule>;
   /**
-   * Lazy-init and return the entry's place-geometries module (for POI footprints, municipality
-   * outlines). Re-applies the config when the fill style changes. Throws on unknown entry id.
+   * Returns the entry's place-geometries module for POI footprints and municipality outlines,
+   * created on first call. Re-applies the config when the fill style changes. Throws on an
+   * unknown entry id.
    */
   getEntryGeometriesModule(entryId: string, fillStyle?: GeometryFillStyle): Promise<GeometriesModule>;
   private _requireEntry;
   get entries(): readonly PlacesEntry[];
   /**
-   * This is used purely to pass data between tools in a context-dependent way,
-   * so we assume the most recent entry is the relevant one to show on the map.
+   * Only passes data between tools in a context-dependent way, so it assumes
+   * the most recent entry is the relevant one to show on the map.
    */
   get latestPlace(): Place[] | undefined;
   addPlaceResult(place: Place | Places, label: string, explicitId?: string, connections?: PlaceConnectionDisplay[], geometries?: PolygonFeature<CommonPlaceProps>[]): Promise<string>;
@@ -1249,18 +1250,17 @@ declare class PlacesState implements StateSlice {
    */
   fetchGeometriesForEntry(entryId: string, options?: ToolExecuteOptions): Promise<PolygonFeature<CommonPlaceProps>[]>;
   /**
-   * Render the given polygons via the entry's GeometriesModule. The `mode` flag is
-   * scoped to **this entry's layer only** — it does not touch other entries (use
-   * the slice's per-entry hide/show methods for cross-entry visibility).
+   * Renders the given polygons via the entry's GeometriesModule. The `mode` flag applies to
+   * **this entry's layer only** and doesn't touch other entries. For cross-entry visibility,
+   * use the slice's per-entry hide and show methods.
    *
-   * - `mode: 'replace'` (default) — calls `module.show` with exactly these features, replacing
-   *   whatever was previously on this entry's layer. An empty array clears the layer.
-   * - `mode: 'add'` — merges the new features with the polygons currently shown on this
-   *   entry's layer (deduped by `feature.id`) and re-renders the union. An empty array is a
-   *   no-op.
+   * - `mode: 'replace'` (default) calls `module.show` with exactly these features, replacing
+   *   whatever was on this entry's layer before. An empty array clears the layer.
+   * - `mode: 'add'` merges the new features with the polygons shown on this entry's layer,
+   *   deduped by `feature.id`, and re-renders the union. An empty array does nothing.
    *
-   * `entryId` defaults to the latest entry that owns geometries — handy when callers only ever
-   * render the most-recently produced footprints. Pass an explicit id to target an older one.
+   * `entryId` defaults to the latest entry that owns geometries, which suits callers that only
+   * render the most recently produced footprints. Pass an explicit id to target an older one.
    */
   showPlaceGeometries(features: PolygonFeature<CommonPlaceProps>[], fillStyle?: GeometryFillStyle, mode?: 'add' | 'replace', entryId?: string): Promise<void>;
   private _latestGeometriesEntryId;
@@ -1276,37 +1276,36 @@ declare class PlacesState implements StateSlice {
   private _idsShownAs;
   /** Marker type for a specific entry, or undefined if it is not shown. */
   getShownMarkerType(id: string): PlacesMarkerType | undefined;
-  /** Return the union of all features belonging to currently-shown entries. */
+  /** Returns the union of all features belonging to the shown entries. */
   getShownFeatures(): Place[];
   /**
-   * Replace the shown set for `markerType` with exactly these ids and re-render.
-   * Entries currently shown as `markerType` but absent from `ids` are hidden;
-   * entries in `ids` are switched to `markerType` (lazy-creating their module).
+   * Replaces the shown set for `markerType` with exactly these ids and re-renders.
+   * Entries shown as `markerType` but absent from `ids` are hidden. Entries in `ids`
+   * switch to `markerType`, creating their module if needed.
    */
   setShownEntries(ids: readonly string[], markerType: PlacesMarkerType): Promise<Place[]>;
   /**
-   * Add ids to the shown set under `markerType`. Any id previously shown as
-   * a different marker type is moved (its module switches to the new
-   * marker type).
+   * Adds ids to the shown set under `markerType`. Any id shown as a different
+   * marker type moves, and its module switches to the new marker type.
    *
-   * Under `entryMode === 'single'` everything else is hidden first, so the
-   * effective behaviour collapses to "show exactly the last id in the list".
+   * With `entryMode === 'single'`, everything else is hidden first, so in effect
+   * only the last id in the list is shown.
    */
   addShownEntries(ids: readonly string[], markerType: PlacesMarkerType): Promise<Place[]>;
-  /** Remove ids from the shown set and clear their modules. */
+  /** Removes ids from the shown set and clears their modules. */
   removeShownEntries(ids: readonly string[]): Promise<Place[]>;
-  /** Clear everything from the map (does not touch entries history). */
+  /** Clears everything from the map but leaves the entries history untouched. */
   clearShownEntries(): Promise<void>;
   /**
-   * Hide every PlacesState rendering — pins AND attached boundary polygons. Map-only:
-   * history (`entries`) is untouched. Implements {@link ClearableMapSlice}.
+   * Hides every PlacesState rendering, both pins and attached boundary polygons, but leaves
+   * the history (`entries`) untouched. Implements {@link ClearableMapSlice}.
    */
   clearShown(): Promise<void>;
   clearShownGeometries(ids?: readonly string[]): Promise<void>;
   /**
-   * Drop a single entry from history. Hides it from the map first (clears every module
-   * it owns) then removes it from `_entries`. Emits `entries-change` and, when the entry was
-   * shown, `shown-change`. No-op when the id is unknown.
+   * Drops a single entry from history. It first hides the entry by clearing every module it
+   * owns, then removes it from `_entries`. Emits `entries-change`, plus `shown-change` if the
+   * entry was shown. Does nothing if the id is unknown.
    */
   removeEntry(id: string): Promise<void>;
   private _showEntryAs;
@@ -1403,25 +1402,25 @@ type RangesEntry = BaseEntry<ReachableRange[]> & {
  */
 type RangeStateEvents = {
   /**
-   * Range history changed — entry added or cleared via `reset()`. `entries` is the full snapshot
-   * after the change; `changedIds` lists the ids of the entries this specific change added,
-   * replaced in place, or removed.
+   * An entry was added, or `reset()` cleared the range history. `entries` is the full snapshot
+   * after the change, and `changedIds` lists the ids of the entries this change added, replaced
+   * in place, or removed.
    */
   'entries-change': {
     entries: readonly RangesEntry[];
     changedIds: readonly string[];
   };
-  /** Set of ranges entries currently rendered on the map changed (multi-show under `multiple`). */
+  /** The set of ranges entries rendered on the map changed (multi-show under `multiple`). */
   'shown-change': ReadonlySet<string>;
-  /** Display policy switched between `single` and `multiple`. */
+  /** The display policy switched between `single` and `multiple`. */
   'mode-change': EntryMode;
 };
 /**
  * State for reachable range results.
  *
- * Stores semantic summaries of calculated ranges (origin, budgets).
- * Also retains raw polygon geometry internally for use in geometry searches
- * (e.g. discoverPlaces withinRange). Displayed on the map via ReachableRangesModule.
+ * It stores semantic summaries of calculated ranges (origin, budgets), plus the raw polygon
+ * geometry internally for geometry searches such as discoverPlaces withinRange.
+ * ReachableRangesModule displays them on the map.
  *
  * @group Agent Toolkit
  */
@@ -1429,56 +1428,55 @@ declare class RangeState implements ShownEntriesSlice {
   private readonly _ttMap;
   private _entries;
   private _entryMode;
-  /** Subscribe to state changes — see {@link RangeStateEvents}. */
+  /** The state change events, listed in {@link RangeStateEvents}. */
   readonly events: StateEvents<RangeStateEvents>;
   constructor(_ttMap: TomTomMap);
   /** Set of ranges-entry ids currently rendered on the map. */
   get shownEntryIds(): ReadonlySet<string>;
   /**
-   * Display policy: `multiple` (default) lets several reachable-area entries render side
-   * by side; `single` forces "at most one ranges entry on the map" — `markEntryShown`
-   * then hides any previously-shown entry first.
+   * The display policy. `multiple` (default) lets several reachable-area entries render
+   * side by side. `single` allows at most one ranges entry on the map, so `markEntryShown`
+   * first hides any previously-shown entry.
    */
   get entryMode(): EntryMode;
   /**
-   * Switch the display policy. When moving from `multiple` → `single` we hide every
-   * non-latest entry, drop them from history, and emit `entries-change`. No-op when the
-   * mode hasn't changed.
+   * Switches the display policy. Moving from `multiple` to `single` hides every non-latest
+   * entry, drops them from history, and emits `entries-change`. Does nothing if the mode
+   * hasn't changed.
    */
   setEntryMode(mode: EntryMode): Promise<void>;
   /**
-   * Lazy-init the entry's ReachableRangesModule (for the isochrone/isodistance polygons),
-   * applying the requested fill style. Throws on unknown id.
+   * Initialises the entry's ReachableRangesModule for the isochrone/isodistance polygons
+   * lazily and applies the requested fill style. Throws on unknown id.
    */
   getEntryRangesModule(entryId: string, fillStyle?: GeometryFillStyle): Promise<ReachableRangesModule>;
   /**
-   * Lazy-init the entry's plain GeometriesModule, for drawing the entry's polygons in a style of
-   * your own (per-feature colours, border widths) rather than as reachable-range bands.
+   * Initialises the entry's plain GeometriesModule lazily for drawing the entry's polygons in a
+   * style of your own (per-feature colours, border widths) instead of as reachable-range bands.
    * Updates only the fill style when it changes, keeping the styling applied since. Throws on
    * unknown id.
    */
   getEntryGeometriesModule(entryId: string, fillStyle?: GeometryFillStyle): Promise<GeometriesModule>;
   /**
-   * Lazy-init the entry's origin-pin PlacesModule. Each entry maintains its own pin module
-   * so multiple ranges entries can be on the map simultaneously without the pins of one
-   * overwriting another.
+   * Initialises the entry's origin-pin PlacesModule lazily. Each entry has its own pin module,
+   * so several ranges entries can share the map without one's pins overwriting another's.
    */
   getEntryPlacesModule(entryId: string): Promise<PlacesModule>;
   /**
-   * Mark this entry as shown — records `_shown = true` and emits `shown-change`. The
-   * caller is expected to push features into the lazy modules itself; this method only
-   * keeps the `_shown` flag in sync with what the user sees.
+   * Marks the entry as shown by recording `_shown = true` and emitting `shown-change`. The
+   * caller pushes features into the lazy modules itself. This method only keeps the `_shown`
+   * flag in sync with what the user sees.
    *
-   * Under `entryMode === 'single'` any other shown entry is hidden first so two range
+   * With `entryMode === 'single'`, any other shown entry is hidden first so two range
    * layers don't overlap.
    */
   markEntryShown(entryId: string): Promise<void>;
-  /** Hide every module on the entry (clear). No-op when the entry is unknown. */
+  /** Clears every module on the entry. Does nothing if the entry is unknown. */
   hideEntry(entryId: string): Promise<void>;
   /**
-   * Drop a single entry from history. Hides it from the map first (clears its ranges +
-   * origin-pin modules) then removes it from `_entries`. Emits `entries-change`. No-op when
-   * the id is unknown.
+   * Drops a single entry from history. It clears the entry's ranges and origin-pin modules to
+   * hide it, then removes it from `_entries`. Emits `entries-change`. Does nothing if the id is
+   * unknown.
    */
   removeEntry(entryId: string): Promise<void>;
   private _requireEntry;
@@ -1486,8 +1484,8 @@ declare class RangeState implements ShownEntriesSlice {
   get latestEntry(): RangesEntry | undefined;
   addEntry(entry: Omit<RangesEntry, 'id' | 'timestamp'>): Promise<string>;
   /**
-   * Hide every reachable-range entry currently on the map. Map-only — history is kept.
-   * Implements {@link ClearableMapSlice}.
+   * Hides every reachable-range entry on the map but keeps the history. Implements
+   * {@link ClearableMapSlice}.
    */
   clearShown(): Promise<void>;
   reset(): void;
@@ -1516,8 +1514,8 @@ type RouteSnapshot = {
   routes: Routes;
 };
 /**
- * Lifecycle state of a per-entry route monitor. `stopped-error` indicates the last recalculation
- * failed and the timer has been cleared — start the monitor again to retry.
+ * The lifecycle state of a per-entry route monitor. `stopped-error` means the last recalculation
+ * failed and the timer was cleared. To retry, start the monitor again.
  *
  * @group Agent Toolkit
  */
@@ -1525,11 +1523,11 @@ type RoutePollingStatus = 'idle' | 'running' | 'stopped-error';
 //#endregion
 //#region src/state/routing/monitor/monitor.d.ts
 /**
- * Dependency injection for a {@link RouteMonitor}. Production code wires `recalculate` to a closure
- * over `calculateRoute` + the entry's waypoints / params (so each tick re-runs the SAME route);
- * tests pass a deterministic fake and override the timer.
+ * The injected dependencies of a {@link RouteMonitor}. Production code wires `recalculate` to a
+ * closure over `calculateRoute` and the entry's waypoints and params, so each tick re-runs the same
+ * route. Tests pass a deterministic fake and override the timer.
  *
- * The recalculator returns just the routes — the monitor stamps `takenAt` itself so every consumer of
+ * The recalculator returns only the routes. The monitor stamps `takenAt` itself, so every consumer of
  * one tick (entry data, derived analyses) agrees on the same canonical moment.
  *
  * @group Agent Toolkit
@@ -1542,21 +1540,21 @@ type RouteMonitorDeps = {
 };
 /**
  * Events fired by {@link RouteMonitor}. The slice subscribes once and re-emits translated copies
- * (`monitor-tick` / `monitor-error`) keyed by entry id.
+ * (`monitor-tick`, `monitor-error`) keyed by entry id.
  */
 type RouteMonitorEvents = {
-  /** A recalculation succeeded. Payload: the fresh snapshot. */
+  /** A recalculation succeeded. The payload is the fresh snapshot. */
   tick: RouteSnapshot;
-  /** A recalculation failed — the monitor has cleared its timer and moved to `stopped-error`. */
+  /** A recalculation failed, so the monitor cleared its timer and moved to `stopped-error`. */
   error: string;
 };
 /**
- * One-shot polling loop that recalculates a single route on an interval. Owns its timer, status, and
- * error. Re-starting after `stop()` is allowed and resets all state.
+ * A one-shot polling loop that recalculates a single route on an interval. It owns its timer, status,
+ * and error. Restarting it after `stop()` resets all state.
  *
- * The monitor never knows about the entry that owns it — the `recalculate` closure captures the
- * waypoints + params, and the caller decides what to do with each fresh snapshot. Mirrors
- * `IncidentMonitor`; routes carry live traffic, so periodic recalculation keeps the entry fresh.
+ * The monitor never knows about the entry that owns it. The `recalculate` closure captures the
+ * waypoints and params, and the caller decides what to do with each fresh snapshot. It mirrors
+ * `IncidentMonitor`. Routes carry live traffic, so periodic recalculation keeps the entry fresh.
  *
  * @group Agent Toolkit
  */
@@ -1569,19 +1567,20 @@ declare class RouteMonitor {
   private _recalculate?;
   get status(): RoutePollingStatus;
   get error(): string | undefined;
-  /** True when the monitor is *currently* recalculating on its interval. */
+  /** Whether the monitor is *currently* recalculating on its interval. */
   get isRunning(): boolean;
-  /** True when the monitor has any activity (running or stopped-error). */
+  /** Whether the monitor has any activity (running or stopped-error). */
   get isActive(): boolean;
   /**
-   * Begin polling. Captures `deps` for the lifetime of the run, fires the first recalculation
-   * immediately (unless `skipInitialTick`), then schedules an interval. No-op when already running.
+   * Starts polling. It captures `deps` for the lifetime of the run, fires the first recalculation
+   * immediately unless `skipInitialTick` is set, then schedules an interval. Does nothing if
+   * already running.
    *
-   * `skipInitialTick` is for a caller that JUST calculated the route and only wants the recurring
-   * refresh — an eager first tick would be a redundant duplicate recalculation.
+   * Set `skipInitialTick` if you just calculated the route and only want the recurring refresh,
+   * since an eager first tick would duplicate that recalculation.
    */
   start(deps: RouteMonitorDeps, intervalMs?: number, skipInitialTick?: boolean): void;
-  /** Stop polling and reset state. No-op when idle. */
+  /** Stops polling and resets state. Does nothing when idle. */
   stop(): void;
   private _tick;
   private _failed;
@@ -1651,9 +1650,9 @@ type RoutesEntry = BaseEntry<Routes> & {
  */
 type RoutingStateEvents = {
   /**
-   * Route history changed — new calculation stored, analysis attached, or cleared via `reset()`.
-   * `entries` is the full snapshot after the change; `changedIds` lists the ids of the entries
-   * this specific change added, replaced in place, or removed.
+   * A calculation was stored, an analysis attached, or `reset()` cleared the history.
+   * `entries` is the full snapshot after the change, and `changedIds` lists the ids of the
+   * entries this change added, replaced in place, or removed.
    */
   'entries-change': {
     entries: readonly RoutesEntry[];
@@ -1663,28 +1662,28 @@ type RoutingStateEvents = {
   'planning-change': readonly PlanningWaypoint[];
   /** Route parameters (alternatives, cost model, depart/arrive time) changed. */
   'params-change': RouteParams;
-  /** Set of routes entries currently rendered on the map changed (multi-show under `multiple`). */
+  /** The set of routes entries rendered on the map changed (multi-show under `multiple`). */
   'shown-change': ReadonlySet<string>;
-  /** Display policy switched between `single` and `multiple`. */
+  /** The display policy switched between `single` and `multiple`. */
   'mode-change': EntryMode;
-  /** Monitoring began on an entry (idle → running). Skipped when already running. */
+  /** Monitoring began on an entry (idle → running). Skipped if already running. */
   'monitor-start': {
     entryId: string;
   };
   /**
-   * Monitoring halted on an entry. `reason: 'manual'` covers explicit `stopMonitoring` and entry
-   * teardown (remove / reset); `reason: 'error'` fires alongside `monitor-error`.
+   * Monitoring halted on an entry. `reason: 'manual'` covers an explicit `stopMonitoring` and
+   * entry teardown (remove, reset). `reason: 'error'` fires alongside `monitor-error`.
    */
   'monitor-stop': {
     entryId: string;
     reason: 'manual' | 'error';
   };
-  /** A monitored route was recalculated (per-tick). The entry's data has been updated in place. */
+  /** A monitored route was recalculated on a tick. The entry's data was updated in place. */
   'monitor-tick': {
     entryId: string;
     snap: RouteSnapshot;
   };
-  /** A monitored route's recalculation failed — the monitor cleared its timer and stopped. */
+  /** A monitored route's recalculation failed, so the monitor cleared its timer and stopped. */
   'monitor-error': {
     entryId: string;
     error: string;
@@ -1694,9 +1693,9 @@ type RoutingStateEvents = {
  * State for route calculation, waypoint management, and route planning parameters.
  *
  * Each entry carries its own lazy-initialised RoutingModule (`entry._module`), so display
- * state lives on the entry instead of a shared slice-level module. Two routes can be rendered
- * concurrently by showing both entries, and switching the active route hides the previous
- * entry's module without disturbing its calculated data.
+ * state lives on the entry instead of a shared slice-level module. To render two routes at once,
+ * show both entries. Switching the active route hides the previous entry's module without
+ * disturbing its calculated data.
  *
  * @group Agent Toolkit
  */
@@ -1718,34 +1717,34 @@ declare class RoutingState implements ShownEntriesSlice {
    * set is `shownEntryIds` (derived from each entry's `_shown` flag).
    */
   private _lastShownEntryId?;
-  /** Subscribe to state changes — see {@link RoutingStateEvents}. */
+  /** The state change events, listed in {@link RoutingStateEvents}. */
   readonly events: StateEvents<RoutingStateEvents>;
   constructor(_ttMap: TomTomMap);
   /** Set of routes-entry ids currently rendered on the map. */
   get shownEntryIds(): ReadonlySet<string>;
   /**
-   * Display policy: `multiple` (default) lets several entries render side-by-side;
-   * `single` forces "at most one route on the map" — `showEntry` then hides any
-   * previously-shown entry first.
+   * The display policy. `multiple` (default) lets several entries render side-by-side.
+   * `single` allows at most one route on the map, so `showEntry` first hides any
+   * previously-shown entry.
    */
   get entryMode(): EntryMode;
   /**
-   * Switch the display policy. When moving from `multiple` → `single` we hide every
-   * non-latest entry, drop them from history, and emit `entries-change`. No-op when the
-   * mode hasn't changed.
+   * Switches the display policy. Moving from `multiple` to `single` hides every non-latest
+   * entry, drops them from history, and emits `entries-change`. Does nothing if the mode
+   * hasn't changed.
    */
   setEntryMode(mode: EntryMode): Promise<void>;
   /**
-   * Lazy-init and return an entry's RoutingModule. Throws on unknown id. Callers that need
-   * to show/hide should prefer the higher-level {@link showEntry} / {@link hideEntry}.
+   * Returns an entry's RoutingModule, created on first call. Throws on unknown id. To show or
+   * hide it, prefer the higher-level {@link showEntry} and {@link hideEntry}.
    */
   getEntryRoutingModule(entryId: string): Promise<RoutingModule>;
   /**
-   * Render the given entry's routes + waypoints on its own RoutingModule.
+   * Renders the given entry's routes and waypoints on its own RoutingModule.
    *
-   * Under `entryMode === 'single'` any other shown entry is hidden first so two route
-   * layers don't pile up. Under `entryMode === 'multiple'` previously-shown entries stay
-   * rendered, letting the caller overlay several routes at once.
+   * With `entryMode === 'single'`, any other shown entry is hidden first so two route
+   * layers don't pile up. With `entryMode === 'multiple'`, previously-shown entries stay
+   * rendered, so the caller can overlay several routes at once.
    *
    * Emits `shown-change` once the new entry is up. Pass `showWaypoints: false` to render the
    * route lines without origin/stop/destination pins, and `showSummaryBubbles: false` to drop the
@@ -1755,29 +1754,28 @@ declare class RoutingState implements ShownEntriesSlice {
     showWaypoints?: boolean;
     showSummaryBubbles?: boolean;
   }): Promise<void>;
-  /** Slice-level route colour persisted across entry swaps. Undefined when none has been set. */
+  /** The slice-level route colour, persisted across entry swaps. Undefined if none was set. */
   get color(): string | undefined;
   /**
-   * Set the slice-level route colour. The colour is applied immediately to every currently-shown
-   * entry's RoutingModule and remembered so that subsequent {@link showEntry} calls apply it
-   * automatically. Pass `undefined` to clear the sticky colour — currently-shown modules keep
-   * their last paint until they're re-shown (MapLibre style restore handles full revert).
+   * Sets the slice-level route colour. It applies immediately to every shown entry's
+   * RoutingModule, and later {@link showEntry} calls apply it automatically. Pass `undefined` to
+   * clear the sticky colour. Shown modules then keep their last paint until they're re-shown,
+   * and MapLibre style restore handles the full revert.
    */
   setColor(color: string | undefined): void;
   /**
-   * Hide the entry's routes + waypoints on its module (clear; the module stays cached).
-   * No-op when the entry is unknown or already hidden.
+   * Hides the entry's routes and waypoints by clearing its module, which stays cached.
+   * Does nothing if the entry is unknown or already hidden.
    */
   hideEntry(entryId: string): Promise<void>;
   /**
-   * Drop a single entry from history. Hides it from the map first (clears its routing module)
-   * then removes it from `_entries`. Emits `entries-change`. No-op when the id is unknown.
+   * Drops a single entry from history. It clears the entry's routing module to hide it, then
+   * removes it from `_entries`. Emits `entries-change`. Does nothing if the id is unknown.
    */
   removeEntry(entryId: string): Promise<void>;
   private _requireEntry;
   /**
-   * RoutingModule of the most-recently-shown entry, if any. Returns undefined when no
-   * entry is currently shown.
+   * The RoutingModule of the most recently shown entry, or undefined if no entry is shown.
    */
   get currentEntryModule(): RoutingModule | undefined;
   get entries(): readonly RoutesEntry[];
@@ -1790,15 +1788,15 @@ declare class RoutingState implements ShownEntriesSlice {
   setWaypointAt(index: number, waypoint: WaypointLike): void;
   setParams(params: Partial<RouteParams>): void;
   /**
-   * Replace a route entry's data in place (a monitor recalculated it). Bumps `_tick`, updates
+   * Replaces a route entry's data in place after a monitor recalculated it. Bumps `_tick`, updates
    * `data`/`timestamp`, emits `entries-change`, and re-renders the route on its module when shown.
-   * The `_tick` guard bails if a newer tick overwrote `data` while `showRoutes` awaited. No-op
-   * (returns false) when the entry is unknown. Mirrors `TrafficIncidentsState.replaceEntryData`.
+   * The `_tick` guard bails if a newer tick overwrote `data` while `showRoutes` awaited. Returns
+   * false if the entry is unknown. Mirrors `TrafficIncidentsState.replaceEntryData`.
    */
   replaceRouteData(entryId: string, routes: Routes, sampledAt: number): Promise<boolean>;
   private _createMonitorForEntry;
   /**
-   * Arm background recalculation on an entry. Lazy-creates its monitor, then starts polling with
+   * Arms background recalculation on an entry. Lazy-creates its monitor, then starts polling with
    * the caller-supplied `recalculate` closure. Emits `monitor-start` on the idle → running
    * transition. Throws on unknown id.
    */
@@ -1806,13 +1804,13 @@ declare class RoutingState implements ShownEntriesSlice {
     intervalMs?: number;
     skipInitialTick?: boolean;
   }): void;
-  /** Stop recalculating an entry; its last data stays. Emits `monitor-stop`. No-op when not running. */
+  /** Stops recalculating an entry but keeps its last data. Emits `monitor-stop`. Does nothing if not running. */
   stopMonitoring(entryId: string): void;
-  /** True when the entry is currently being recalculated on its interval. */
+  /** Whether the entry is being recalculated on its interval. */
   isMonitored(entryId: string): boolean;
   /**
-   * Hide every route + waypoint set currently on the map. Map-only — history (`entries`)
-   * stays intact. Implements {@link ClearableMapSlice}.
+   * Hides every route and waypoint set on the map but keeps the history (`entries`) intact.
+   * Implements {@link ClearableMapSlice}.
    */
   clearShown(): Promise<void>;
   reset(): void;
@@ -1834,10 +1832,10 @@ export interface StateSlice {
 //#endregion
 //#region src/state/trackers.d.ts
 /**
- * The features within ONE source entry that matched the rule — the per-entry unit of a {@link Verdict}.
- * `featureIds` is the matched SUBSET, not the whole entry: a rule selects features by arbitrary sandbox
- * logic (proximity, threshold, filter), and that selection isn't recoverable from `entryId` alone (the
- * entry holds every feature) without re-running the rule — so the verdict records exactly what matched.
+ * The features within one source entry that matched the rule, the per-entry unit of a {@link Verdict}.
+ * `featureIds` is the matched subset, not the whole entry. A rule selects features by arbitrary sandbox
+ * logic (proximity, threshold, filter). The entry holds every feature, so without re-running the rule
+ * that selection can't be recovered from `entryId` alone, and the verdict records exactly what matched.
  * These are the features the UI highlights and the `summary` cites.
  */
 type MemberRef = {
@@ -1845,24 +1843,24 @@ type MemberRef = {
   featureIds: string[];
 };
 /**
- * What a tracker's sandboxed `evaluateCode` returns — stored verbatim as the rule analysis's `data`
- * and read back by the reducer. `members` groups matches by source entry so a verdict can span
- * multiple entry kinds (e.g. "an incident within 100m of a hospital" returns a hospitals group and an
- * incidents group). `summary` is a grounded headline the code produces deterministically.
+ * What a tracker's sandboxed `evaluateCode` returns, stored verbatim as the rule analysis's `data`
+ * and read back by the reducer. `members` groups matches by source entry, so a verdict can span
+ * several entry kinds. For example, "an incident within 100m of a hospital" returns a hospitals group
+ * and an incidents group. `summary` is a grounded headline the code produces deterministically.
  */
 type Verdict = {
   active: boolean;
   members: MemberRef[];
   summary: string;
 };
-/** Toast-worthy (`alert`) vs quietly-logged (`event`). One store; the type discriminates. */
+/** Toast-worthy (`alert`) or quietly-logged (`event`), discriminating events in one store. */
 type TrackerEventType = 'alert' | 'event';
-/** Rising edge (`opened`) vs falling edge (`resolved`). The only two statuses in the rising-edge model. */
+/** Rising edge (`opened`) or falling edge (`resolved`), the only two statuses in the rising-edge model. */
 type TrackerEventStatus = 'opened' | 'resolved';
-/** One thing that happened — a tracker crossing an edge. The durable record the feed + toasts render. */
+/** A tracker crossing an edge, kept as the durable record the feed and toasts render. */
 type TrackerEvent = {
   id: string;
-  /** Source-data sample time of the recompute that fired it (NOT wall-clock). */
+  /** Source-data sample time of the recompute that fired it, **not** wall-clock. */
   at: number;
   trackerId: string;
   trackerName: string;
@@ -1870,39 +1868,39 @@ type TrackerEvent = {
   kind: TrackerEventStatus;
   summary: string;
   members: MemberRef[];
-  /** Rising-edge time of the episode this closes — present on `resolved`. */
+  /** The rising-edge time of the episode this closes, present on `resolved`. */
   openedAt?: number;
 };
 /**
- * One tracker = one rule: an NL condition plus its rising-edge state. The compiled code lives on the
- * tracker's {@link Job}, not here. `affectedEntryIds` are the entries the rule watches; a verdict's
- * `members` are the ones that matched.
+ * A tracker is one rule, a natural-language condition plus its rising-edge state. The compiled code
+ * lives on the tracker's {@link Job}, not here. `affectedEntryIds` are the entries the rule watches,
+ * and a verdict's `members` are the ones that matched.
  */
 type Tracker = {
   id: string;
   name: string;
-  /** Natural-language condition (LLM-readable); the compiled code lives on the tracker's job. */
+  /** Natural-language condition (LLM-readable). The compiled code lives on the tracker's job. */
   rule: string;
-  /** Ids of every entry the rule reads — the per-entry lookup key ({@link EventsState.trackersForEntry}). */
+  /** The ids of every entry the rule reads, the per-entry lookup key ({@link EventsState.trackersForEntry}). */
   affectedEntryIds: readonly string[];
   enabled: boolean;
-  /** The one bit of memory: was the verdict active at the last recompute (rising-edge detection). */
+  /** Whether the verdict was active at the last recompute, the one bit of rising-edge memory. */
   wasActive: boolean;
   /** Rising-edge time of the current open episode, if active. */
   openedAt?: number;
 };
 /** Events emitted by {@link EventsState}. */
 type TrackerStateEvents = {
-  /** The tracker set or a tracker's live state changed (create / clear / enable / edge crossed). */
+  /** The tracker set or a tracker's live state changed (create, clear, enable, edge crossed). */
   'trackers-change': readonly Tracker[];
-  /** A tracker crossed an edge — the freshly-logged event (drives toasts + feed append). */
+  /** A tracker crossed an edge. The freshly-logged event drives toasts and feed appends. */
   'tracker-event': TrackerEvent;
 };
 /**
- * Generic tracker store + rising-edge reducer. Held on `ToolState` as `state.trackers`. Pure
- * storage + reaction: tools register/unregister trackers and register their rule jobs on the
- * {@link JobEngine}; each job's `run` feeds verdicts here via {@link ingestVerdict}. Keeps the
- * {@link Job} handle backing each tracker (`_jobs`) so pausing a tracker pauses its job.
+ * Generic tracker store and rising-edge reducer, held on `ToolState` as `state.trackers`. It only
+ * stores and reacts. Tools register and unregister trackers and register their rule jobs on the
+ * {@link JobEngine}, and each job's `run` feeds verdicts here via {@link ingestVerdict}. Keeps the
+ * {@link Job} handle backing each tracker (`_jobs`), so pausing a tracker pauses its job.
  *
  * @group Agent Toolkit
  */
@@ -1914,24 +1912,24 @@ declare class EventsState implements StateSlice {
   private _seq;
   readonly events: StateEvents<TrackerStateEvents>;
   /**
-   * Register a tracker. The caller (createTracker) registers it with the rising-edge bit clear
-   * (`wasActive: false`) and feeds the arm-time verdict via {@link ingestVerdict} AFTER this call, so a
-   * condition already live at creation crosses false→true and fires one `opened` alert. Emits
+   * Registers a tracker. The caller (createTracker) registers it with the rising-edge bit clear
+   * (`wasActive: false`) and feeds the arm-time verdict via {@link ingestVerdict} after this call. A
+   * condition already live at creation then crosses false→true and fires one `opened` alert. Emits
    * `trackers-change`.
    */
   register(tracker: Tracker): void;
-  /** Store the {@link Job} backing a tracker — the reference linking it to the engine. */
+  /** Stores the {@link Job} backing a tracker, which links it to the engine. */
   setJob(trackerId: string, job: Job): void;
-  /** Remove a tracker and tear down its job. */
+  /** Removes a tracker and tears down its job. */
   unregister(trackerId: string): void;
-  /** Pause/resume a tracker AND its job (a paused job never recomputes, so never crosses edges). */
+  /** Pauses or resumes a tracker and its job. A paused job never recomputes or crosses edges. */
   setEnabled(trackerId: string, enabled: boolean): boolean;
   /** Live trackers, as copies so external mutation can't corrupt the store. */
   get trackers(): readonly Tracker[];
   get(trackerId: string): Tracker | undefined;
   /**
-   * Trackers whose rule reads `entryId` — e.g. every tracker watching a given incidents area. Drives
-   * "show all trackers for this area" in the UI.
+   * The trackers whose rule reads `entryId`, such as every tracker watching a given incidents area.
+   * Drives "show all trackers for this area" in the UI.
    */
   trackersForEntry(entryId: string): readonly Tracker[];
   /**
@@ -1942,13 +1940,14 @@ declare class EventsState implements StateSlice {
     trackerId?: string;
     sinceMs?: number;
   }): readonly TrackerEvent[];
-  /** Clear all trackers + log + job handles. Walked automatically by `destroyState`. */
+  /** Clears all trackers, the log and job handles. `destroyState` calls it automatically. */
   reset(): void;
   /**
-   * Feed a freshly-computed verdict through the rising-edge reducer — called by the tracker's job `run`
-   * on each recompute (and once at arm time). Bails fast unless the tracker is live + enabled. A verdict
-   * flipping false→true logs `opened` (alert); true→false logs `resolved` (event). No change on
-   * active→active / inactive→inactive. `at` is the source-data sample time of the recompute.
+   * Feeds a freshly computed verdict through the rising-edge reducer. The tracker's job `run` calls it
+   * on each recompute and once at arm time. It bails fast unless the tracker is live and enabled. A
+   * verdict flipping false→true logs `opened` (alert), and true→false logs `resolved` (event).
+   * Active→active and inactive→inactive change nothing. `at` is the source-data sample time of the
+   * recompute.
    */
   ingestVerdict(trackerId: string, verdict: Verdict, at: number): void;
   private append;
@@ -2014,29 +2013,28 @@ type TrafficAreaAnalyticsEntry = BaseEntry<TrafficAreaAnalytics> & {
  */
 type TrafficAreaAnalyticsStateEvents = {
   /**
-   * History changed — entry added, removed, or cleared via `reset()`. `entries` is the full
-   * snapshot after the change; `changedIds` lists the ids of the entries this specific change
-   * added, replaced in place, or removed.
+   * An entry was added or removed, or `reset()` cleared the history. `entries` is the full
+   * snapshot after the change, and `changedIds` lists the ids of the entries this change added,
+   * replaced in place, or removed.
    */
   'entries-change': {
     entries: readonly TrafficAreaAnalyticsEntry[];
     changedIds: readonly string[];
   };
-  /** Set of entries currently rendered on the map changed. */
+  /** The set of entries rendered on the map changed. */
   'shown-change': ReadonlySet<string>;
-  /** Per-entry viz config changed (mode / metric / scaleMode / …). */
+  /** An entry's viz config (mode, metric, scaleMode, …) changed. */
   'config-change': {
     entryId: string;
     config: TrafficAreaAnalyticsModuleConfig | undefined;
   };
-  /** Display policy switched between `single` and `multiple`. */
+  /** The display policy switched between `single` and `multiple`. */
   'mode-change': EntryMode;
 };
 /**
- * Append-only history of traffic-area-analytics aggregations, with per-entry
- * rendering. Each entry owns a dedicated {@link TrafficAreaAnalyticsModule},
- * lazy-initialised on first show. Mirrors the per-entry pattern used by
- * `RoutingState` / `CustomGeometriesState`.
+ * An append-only history of traffic-area-analytics aggregations, with per-entry
+ * rendering. As in `RoutingState` and `CustomGeometriesState`, each entry owns a
+ * dedicated {@link TrafficAreaAnalyticsModule}, initialised lazily on first show.
  *
  * Live tile overlays (flow + incidents) live in {@link TrafficTilesState}.
  *
@@ -2046,7 +2044,7 @@ declare class TrafficAreaAnalyticsState implements ShownEntriesSlice, StateSlice
   private readonly _ttMap;
   private _entries;
   private _entryMode;
-  /** Subscribe to state changes — see {@link TrafficAreaAnalyticsStateEvents}. */
+  /** The state change events, listed in {@link TrafficAreaAnalyticsStateEvents}. */
   readonly events: StateEvents<TrafficAreaAnalyticsStateEvents>;
   constructor(_ttMap: TomTomMap);
   get entries(): readonly TrafficAreaAnalyticsEntry[];
@@ -2056,25 +2054,25 @@ declare class TrafficAreaAnalyticsState implements ShownEntriesSlice, StateSlice
   setEntryMode(mode: EntryMode): Promise<void>;
   findById(entryId: string): TrafficAreaAnalyticsEntry | undefined;
   /**
-   * Append a new entry. Auto-suffixes the id on collision. Under `single` mode the new entry
-   * replaces every older one (hidden + dropped from history).
+   * Appends a new entry and suffixes its id on collision. In `single` mode it replaces every
+   * older one, which is hidden and dropped from history.
    */
   addEntry(data: TrafficAreaAnalytics, label: string, params: TrafficAreaAnalyticsParams, explicitId?: string): Promise<string>;
   /**
-   * Lazy-init the entry's TrafficAreaAnalyticsModule, wiring per-entry config-change events.
-   * Throws on unknown id.
+   * Initialises the entry's TrafficAreaAnalyticsModule lazily, wiring its config-change
+   * events. Throws on unknown id.
    */
   getEntryModule(entryId: string): Promise<TrafficAreaAnalyticsModule>;
-  /** Render this entry's analytics on its own module. Under `single` mode, hides every other shown entry first. */
+  /** Renders the entry's analytics on its own module. In `single` mode, hides every other shown entry first. */
   showEntry(entryId: string): Promise<void>;
-  /** Hide the entry's analytics on its module. No-op when unknown or already hidden. */
+  /** Hides the entry's analytics on its module. Does nothing if unknown or already hidden. */
   hideEntry(entryId: string): Promise<void>;
-  /** Drop a single entry from history. Hides it first, then removes; emits `entries-change`. No-op on unknown id. */
+  /** Hides a single entry, then drops it from history and emits `entries-change`. Does nothing for an unknown id. */
   removeEntry(entryId: string): Promise<void>;
   private _requireEntry;
   /**
-   * Hide every traffic-area-analytics entry currently on the map. Map-only — history is kept.
-   * Implements {@link ClearableMapSlice}.
+   * Hides every traffic-area-analytics entry on the map but keeps the history. Implements
+   * {@link ClearableMapSlice}.
    */
   clearShown(): Promise<void>;
   reset(): void;
@@ -2095,7 +2093,7 @@ type IncidentsAnalysis = EntryAnalysis;
 //#region src/state/traffic-incidents/clustering.d.ts
 /** Direction a cluster's total delay is trending across recent snapshots. */
 type ClusterTrend = 'growing' | 'fading' | 'steady' | 'new';
-/** Tuneable parameters for {@link runClustering}. All optional with sensible defaults. */
+/** Tuneable parameters for {@link runClustering}, all optional with sensible defaults. */
 type ClusteringParams = {
   /** DBSCAN neighbourhood radius in km. Default: 0.5 */
   eps?: number;
@@ -2107,13 +2105,13 @@ type ClusteringParams = {
   preFilter?: {
     /** Categories to exclude entirely. Default: `['roadworks', 'road-closed']` */
     excludeCategories?: string[];
-    /** Incidents with `delayInSeconds` below this are excluded (within excludeCategories). Default: 1 (i.e. exclude 0-delay) */
+    /** Incidents in excludeCategories with `delayInSeconds` below this are excluded. Default: 1 (excludes 0-delay) */
     minDelaySeconds?: number;
   };
 };
 /** A single cluster produced by {@link runClustering}. */
 type ClusterResult = {
-  /** Stable identifier — reused across runs when member overlap >= 50%. */
+  /** A stable identifier, reused across runs when member overlap >= 50%. */
   id: string;
   /** Geographic centre of the cluster `[lng, lat]`. */
   centroid: [number, number];
@@ -2131,12 +2129,12 @@ type ClusterResult = {
   primaryRoads: string[];
   /** Most-frequent incident category across members (e.g. "jam"). */
   primaryCategory: string;
-  /** Trend across recent snapshots — see {@link classifyTrend}. */
+  /** Trend across recent snapshots (see {@link classifyTrend}). */
   trend: ClusterTrend;
   /**
-   * Rolling window of `totalDelaySeconds` across recent matched snapshots
-   * (bounded to {@link TREND_WINDOW}). Internal trend state threaded forward
-   * via the previous run; not display data.
+   * Rolling window of `totalDelaySeconds` across recent matched snapshots,
+   * bounded to {@link TREND_WINDOW}. Internal trend state threaded forward
+   * via the previous run, not display data.
    */
   delaySamples: number[];
 };
@@ -2146,7 +2144,7 @@ type ClusteringOutput = {
 };
 /**
  * {@link runClustering} output plus the moment it was computed. The extra `sampledAt` lets the sandbox
- * `cluster()` primitive thread the trend window forward without the caller juggling timestamps: it is
+ * `cluster()` primitive thread the trend window forward without the caller juggling timestamps. It is
  * stamped onto the result and read back off `previous` on the next call.
  *
  * @group Agent Toolkit
@@ -2178,8 +2176,8 @@ type IncidentSnapshot = {
   incidents: TrafficIncident[];
 };
 /**
- * Lifecycle state of a per-entry incidents monitor. `stopped-error` indicates the last
- * poll failed and the timer has been cleared — start the monitor again to retry.
+ * The lifecycle state of a per-entry incidents monitor. `stopped-error` means the last
+ * poll failed and the timer was cleared. To retry, start the monitor again.
  *
  * @group Agent Toolkit
  */
@@ -2187,13 +2185,13 @@ type PollingStatus = 'idle' | 'running' | 'stopped-error';
 //#endregion
 //#region src/state/traffic-incidents/monitor/monitor.d.ts
 /**
- * Dependency injection for an {@link IncidentMonitor}. Production code wires
- * `fetchIncidents` to `trafficIncidentDetails`; tests can pass a deterministic fake
+ * The injected dependencies of an {@link IncidentMonitor}. Production code wires
+ * `fetchIncidents` to `trafficIncidentDetails`. Tests can pass a deterministic fake
  * and override the timer.
  *
- * The fetcher returns just the incidents — the monitor stamps `takenAt` itself
- * so every consumer of one tick (entry data, derived analyses, sandbox `now`)
- * agrees on the same canonical moment.
+ * The fetcher returns only the incidents. The monitor stamps `takenAt` itself, so
+ * every consumer of one tick (entry data, derived analyses, sandbox `now`) agrees
+ * on the same canonical moment.
  *
  * @group Agent Toolkit
  */
@@ -2205,19 +2203,19 @@ type IncidentMonitorDeps = {
 };
 /**
  * Events fired by {@link IncidentMonitor}. The slice subscribes once and re-emits
- * translated copies (`monitor-tick` / `monitor-error`) keyed by entry id.
+ * translated copies (`monitor-tick`, `monitor-error`) keyed by entry id.
  */
 type IncidentMonitorEvents = {
   /** A poll succeeded. Payload: the fresh snapshot. */
   tick: IncidentSnapshot;
-  /** A poll failed — the monitor has cleared its timer and moved to `stopped-error`. */
+  /** A poll failed, so the monitor cleared its timer and moved to `stopped-error`. */
   error: string;
 };
 /**
- * One-shot polling loop scoped to a single bbox. Owns its timer, status, error,
- * and captured area. Re-starting after `stop()` is allowed and resets all state.
+ * A one-shot polling loop scoped to a single bbox. It owns its timer, status, error,
+ * and captured area. Restarting it after `stop()` resets all state.
  *
- * The monitor never knows about the entry that owns it — it surfaces ticks/errors
+ * The monitor never knows about the entry that owns it. It surfaces ticks and errors
  * through `events`, and the caller decides what to do with the snapshot.
  *
  * @group Agent Toolkit
@@ -2236,25 +2234,26 @@ declare class IncidentMonitor {
   get monitoredArea(): MonitoredArea | undefined;
   get error(): string | undefined;
   /**
-   * True when the monitor is *currently* polling. Distinct from {@link isActive},
-   * which also covers `stopped-error` — a state where the timer is gone but the
-   * monitor still carries an unacknowledged error. Use this for "is the entry
-   * being polled right now"; use `isActive` for "is there anything to clean up".
+   * Whether the monitor is *currently* polling. Unlike {@link isActive}, it excludes
+   * `stopped-error`, a state where the timer is gone but the monitor still carries an
+   * unacknowledged error. Use this to ask "is the entry being polled right now", and
+   * `isActive` to ask "is there anything to clean up".
    */
   get isRunning(): boolean;
-  /** True when the monitor has any polling activity (running or stopped-error). */
+  /** Whether the monitor has any polling activity (running or stopped-error). */
   get isActive(): boolean;
   /**
-   * Begin polling. Captures `deps` for the lifetime of the run, fires the first tick
-   * immediately (unless `skipInitialTick`), then schedules an interval. No-op when already running.
+   * Starts polling. It captures `deps` for the lifetime of the run, fires the first tick
+   * immediately unless `skipInitialTick` is set, then schedules an interval. Does nothing if
+   * already running.
    *
-   * `skipInitialTick` is for the caller that JUST fetched the data itself (e.g. getTrafficIncidents
-   * arming monitoring on the entry it just loaded): the entry is already fresh, so an eager first
-   * tick would be a redundant duplicate fetch. Standalone callers leave it false so the monitor
+   * Set `skipInitialTick` if you just fetched the data yourself, as getTrafficIncidents does
+   * when arming monitoring on the entry it just loaded. The entry is already fresh, so an eager
+   * first tick would duplicate that fetch. Standalone callers leave it false, so the monitor
    * produces an initial snapshot without waiting a full interval.
    */
   start(area: MonitoredArea, deps: IncidentMonitorDeps, intervalMs?: number, skipInitialTick?: boolean): void;
-  /** Stop polling and reset state. No-op when idle. */
+  /** Stops polling and resets state. Does nothing when idle. */
   stop(): void;
   private _tick;
   private _failed;
@@ -2263,12 +2262,12 @@ declare class IncidentMonitor {
 //#endregion
 //#region src/state/traffic-incidents/state.d.ts
 /**
- * Dedicated per-entry clustering state. Incident clustering is NOT a generic analysis — it is typed,
+ * Dedicated per-entry clustering state. Incident clustering is **not** a generic analysis. It is typed,
  * first-class incidents state with its own home here. `output` is the latest {@link SandboxClusteringOutput}
- * (the DBSCAN groups + the moment it was computed); `recipe` is how to recompute it (re-used by
- * `tools/state/clusters-runtime.ts` to re-run on each monitor tick so clusters stay live). `recipe`
- * is opaque here (a tools-layer `ClusterRecipe`) — the slice never interprets it, keeping the state layer
- * tools-agnostic.
+ * (the DBSCAN groups and the moment they were computed). `recipe` is how to recompute it, and
+ * `tools/state/clusters-runtime.ts` reuses it on each monitor tick so clusters stay live. `recipe` is
+ * opaque here (a tools-layer `ClusterRecipe`). The slice never interprets it, which keeps the state
+ * layer tools-agnostic.
  *
  * @group Agent Toolkit
  */
@@ -2327,7 +2326,7 @@ type TrafficIncidentsEntry = BaseEntry<TrafficIncident[]> & {
   _tick?: number;
 };
 /**
- * Snapshot of an entry's focus subset. Returned by `getFocus` / payload on `focus-change`.
+ * Snapshot of an entry's focus subset, returned by `getFocus` and carried by `focus-change`.
  *
  * @group Agent Toolkit
  */
@@ -2337,14 +2336,14 @@ type IncidentFocus = {
 };
 /**
  * Events fired by {@link TrafficIncidentsState}. Subscribe via
- * `state.trafficIncidents.events.on(type, handler)` — returns an unsubscribe function.
+ * `state.trafficIncidents.events.on(type, handler)`, which returns an unsubscribe function.
  *
  * @group Agent Toolkit
  */
 type TrafficIncidentsStateEvents = {
   /**
-   * History changed — entry added, replaced, removed, or cleared via `reset()`. `entries` is the
-   * full snapshot after the change; `changedIds` lists the ids of the entries this specific change
+   * An entry was added, replaced or removed, or `reset()` cleared the history. `entries` is the
+   * full snapshot after the change, and `changedIds` lists the ids of the entries this change
    * added, replaced in place, or removed. The {@link JobEngine} and the clustering re-run
    * match these against the entries they depend on.
    */
@@ -2352,46 +2351,46 @@ type TrafficIncidentsStateEvents = {
     entries: readonly TrafficIncidentsEntry[];
     changedIds: readonly string[];
   };
-  /** Set of entries currently rendered on the map changed. */
+  /** The set of entries rendered on the map changed. */
   'shown-change': ReadonlySet<TrafficIncidentsEntry['id']>;
-  /** Focus subset for an entry changed (or cleared, when `focus === null`). */
+  /** An entry's focus subset changed, or was cleared if `focus === null`. */
   'focus-change': {
     entryId: TrafficIncidentsEntry['id'];
     focus: IncidentFocus | null;
   };
-  /** Display policy switched between `single` and `multiple`. */
+  /** The display policy switched between `single` and `multiple`. */
   'mode-change': EntryMode;
-  /** A monitored entry produced a fresh snapshot (per-tick). */
+  /** A monitored entry's tick produced a fresh snapshot. */
   'monitor-tick': {
     entryId: TrafficIncidentsEntry['id'];
     snap: IncidentSnapshot;
   };
-  /** A monitored entry's poll failed — slice has cleared the timer. */
+  /** A monitored entry's poll failed, and the slice cleared the timer. */
   'monitor-error': {
     entryId: TrafficIncidentsEntry['id'];
     error: string;
   };
   /**
-   * Polling began on an entry (idle → running). Skipped when `startMonitoring`
-   * was a no-op against an already-running monitor.
+   * Polling began on an entry (idle → running). Skipped if `startMonitoring`
+   * found the monitor already running.
    */
   'monitor-start': {
     entryId: TrafficIncidentsEntry['id'];
   };
   /**
-   * Polling halted on an entry. `reason: 'manual'` covers explicit
-   * `stopMonitoring` and entry teardown (remove / single-mode trim / reset).
-   * `reason: 'error'` fires alongside `monitor-error` — error-only listeners
-   * keep using `monitor-error`; lifecycle listeners can rely on this alone.
+   * Polling halted on an entry. `reason: 'manual'` covers an explicit
+   * `stopMonitoring` and entry teardown (remove, single-mode trim, reset).
+   * `reason: 'error'` fires alongside `monitor-error`. Error-only listeners
+   * keep using `monitor-error`, and lifecycle listeners can rely on this alone.
    */
   'monitor-stop': {
     entryId: TrafficIncidentsEntry['id'];
     reason: 'manual' | 'error';
   };
   /**
-   * An entry's clustering result changed — set, recomputed on a tick, or cleared (`clusters === null`).
-   * UI that renders cluster pins re-derives off this (not `entries-change`): the clustering re-run is
-   * async to the monitor tick, so the fresh result lands here a step later.
+   * An entry's clustering result was set, recomputed on a tick, or cleared (`clusters === null`).
+   * UI that renders cluster pins re-derives from this, not from `entries-change`, because the
+   * clustering re-run is async to the monitor tick, so the fresh result lands here a step later.
    */
   'clusters-change': {
     entryId: TrafficIncidentsEntry['id'];
@@ -2399,11 +2398,11 @@ type TrafficIncidentsStateEvents = {
   };
 };
 /**
- * State for traffic incidents: entry history and map rendering via per-entry
- * TrafficIncidentDetailsModule. Each entry can be a separate area; under the default
+ * State for traffic incidents, with entry history and map rendering via per-entry
+ * TrafficIncidentDetailsModule. Each entry can be a separate area, and in the default
  * `multiple` mode several entries can render at once.
  *
- * Each entry owns its own module (lazy-init on first show) plus an optional per-entry
+ * Each entry owns its own module, initialised lazily on first show, plus an optional
  * background monitor. Subscribe to changes via `events.on('...')`.
  *
  * @group Agent Toolkit
@@ -2413,84 +2412,84 @@ declare class TrafficIncidentsState implements StateSlice {
   private _entries;
   private _entryMode;
   private readonly _clusters;
-  /** Subscribe to state changes — see {@link TrafficIncidentsStateEvents}. */
+  /** The state change events, listed in {@link TrafficIncidentsStateEvents}. */
   readonly events: StateEvents<TrafficIncidentsStateEvents>;
   constructor(_ttMap: TomTomMap);
   get entries(): readonly TrafficIncidentsEntry[];
   /**
-   * Display policy: `multiple` (default) keeps every history entry available to render
-   * simultaneously; `single` enforces "at most one entry on the map at a time" and trims
-   * the history down to the latest entry whenever it's set.
+   * The display policy. `multiple` (default) keeps every history entry available to render
+   * simultaneously. `single` allows at most one entry on the map at a time and trims the
+   * history to the latest entry whenever it's set.
    */
   get entryMode(): EntryMode;
   /**
-   * Switch the display policy. When moving from `multiple` → `single` we hide every entry
-   * older than the latest, drop them from history, and emit `entries-change`. No-op when the
-   * mode hasn't changed.
+   * Switches the display policy. Moving from `multiple` to `single` hides every entry older
+   * than the latest, drops them from history, and emits `entries-change`. Does nothing if
+   * the mode hasn't changed.
    */
   setEntryMode(mode: EntryMode): Promise<void>;
   /** Set of entries currently rendered on the map. */
   get shownEntryIds(): ReadonlySet<TrafficIncidentsEntry['id']>;
   /**
-   * Append a new entry to the history. Under `single` mode the new entry replaces every
-   * older one (and tears their modules + monitors down). `sampledAt` is the moment the
-   * data was captured — pass one canonical value per "moment" so future joins (entry
-   * data ↔ derived analyses) are byte-equal. Returns the assigned id.
+   * Appends a new entry to the history and returns its assigned id. In `single` mode the new
+   * entry replaces every older one and tears down their modules and monitors. `sampledAt` is
+   * the moment the data was captured. Pass one canonical value per "moment" so future joins
+   * (entry data ↔ derived analyses) are byte-equal.
    */
   addIncidentsEntry(data: TrafficIncident[], params: TrafficIncidentDetailsByBBoxParams & {
     bbox: BBox;
   }, label: string, sampledAt: number, explicitId?: string): Promise<string>;
   /**
-   * Replace an entry's data in place and repaint its module without moving the camera.
-   * Used by the per-entry monitor tick so incident geometries and any open detail
-   * panel stay in sync with the freshest snapshot. `sampledAt` is the canonical moment
-   * for this update — propagated to the entry timestamp before the `entries-change` emit.
-   * That emit is what drives analysis replay: the session-level {@link JobEngine} re-runs every
-   * job bound to this entry off the change, ASYNCHRONOUSLY (a microtask later) — the slice itself
-   * owns no analysis logic.
-   * Returns true on success, false when the entry is unknown.
+   * Replaces an entry's data in place and repaints its module without moving the camera.
+   * The per-entry monitor tick uses it so incident geometries and any open detail panel
+   * stay in sync with the freshest snapshot. `sampledAt` is the canonical moment for this
+   * update, propagated to the entry timestamp before the `entries-change` emit. That emit
+   * drives analysis replay. The session-level {@link JobEngine} re-runs every job bound to
+   * this entry off the change **asynchronously**, a microtask later. The slice itself owns
+   * no analysis logic.
+   * Returns true on success, false if the entry is unknown.
    */
   replaceEntryData(entryId: TrafficIncidentsEntry['id'], data: TrafficIncident[], sampledAt: number): Promise<boolean>;
   /**
-   * Lazy-init and return the entry's TrafficIncidentDetailsModule. Consumers subscribe to
-   * clicks directly on the returned module via `module.events.on('click', ...)`;
+   * Returns the entry's TrafficIncidentDetailsModule, created on first call. To handle
+   * clicks, subscribe on the returned module via `module.events.on('click', ...)`.
    * Throws on unknown entry id.
    */
   getEntryModule(entryId: TrafficIncidentsEntry['id']): Promise<TrafficIncidentDetailsModule>;
   /**
-   * Render an entry on the map. Lazy-inits its module, pushes the entry's incidents, and
-   * (when `fitBounds` is true) fits the camera to the entry's bbox. Emits `shown-change`
-   * once the entry transitions to shown.
+   * Renders an entry on the map. Lazy-inits its module, pushes the entry's incidents, and
+   * fits the camera to the entry's bbox if `fitBounds` is true. Emits `shown-change` once
+   * the entry transitions to shown.
    */
   showEntry(entryId: TrafficIncidentsEntry['id'], fitBounds?: boolean): Promise<void>;
   /**
-   * Hide an entry — clears its module + drops focus. The module reference stays on the
-   * entry for cheap re-show. No-op when the entry is unknown or already hidden.
+   * Hides an entry by clearing its module and dropping focus. The module reference stays
+   * on the entry for cheap re-show. Does nothing if the entry is unknown or already hidden.
    */
   hideEntry(entryId: TrafficIncidentsEntry['id']): Promise<void>;
   /**
-   * Drop an entry from history. Hides it from the map and stops its monitor if any.
-   * Emits `entries-change` and, when the entry was shown, `shown-change`. No-op when the
-   * id is unknown.
+   * Drops an entry from history, hiding it from the map and stopping any monitor. Emits
+   * `entries-change`, plus `shown-change` if the entry was shown. Does nothing if the id
+   * is unknown.
    */
   removeEntry(entryId: TrafficIncidentsEntry['id']): Promise<void>;
   /**
-   * Store (or replace) an entry's clustering record and emit `clusters-change`. No-op when the entry is
-   * unknown — clusters are entry-scoped, so an orphan record is meaningless. Called by `clusterIncidents`
-   * and its monitor-tick re-run (`tools/state/clusters-runtime.ts`).
+   * Stores or replaces an entry's clustering record and emits `clusters-change`. Does nothing if the
+   * entry is unknown, because clusters are entry-scoped and an orphan record is meaningless.
+   * `clusterIncidents` and its monitor-tick re-run (`tools/state/clusters-runtime.ts`) call it.
    */
   setClusters(entryId: TrafficIncidentsEntry['id'], record: ClustersRecord): void;
-  /** Latest clustering output for an entry, or undefined when none has been computed. */
+  /** The latest clustering output for an entry, or undefined if none was computed. */
   getClusters(entryId: TrafficIncidentsEntry['id']): SandboxClusteringOutput | undefined;
-  /** Full clustering record (recipe + output) for an entry — the re-run reads this back. */
+  /** The full clustering record (recipe and output) for an entry, which the re-run reads back. */
   getClustersRecord(entryId: TrafficIncidentsEntry['id']): ClustersRecord | undefined;
-  /** Drop an entry's clustering. Emits `clusters-change` with `null`. No-op when nothing is stored. */
+  /** Drops an entry's clustering and emits `clusters-change` with `null`. Does nothing if none is stored. */
   clearClusters(entryId: TrafficIncidentsEntry['id']): void;
-  /** Snapshot of an entry's focus subset, or null when no focus is active or the entry is unknown. */
+  /** Snapshot of an entry's focus subset, or null if no focus is active or the entry is unknown. */
   getFocus(entryId: TrafficIncidentsEntry['id']): IncidentFocus | null;
   /**
-   * Set the focus subset on a specific entry. Filters ids against the entry's current
-   * incidents (drops unknown ones) and pushes the result onto the entry's module.
+   * Sets the focus subset on a specific entry. Filters ids against the entry's current
+   * incidents, dropping unknown ones, and pushes the result onto the entry's module.
    * Returns the kept count and any dropped ids.
    */
   setFocus(entryId: TrafficIncidentsEntry['id'], ids: readonly string[], reason?: string): {
@@ -2499,46 +2498,46 @@ declare class TrafficIncidentsState implements StateSlice {
   };
   clearFocus(entryId: TrafficIncidentsEntry['id']): void;
   /**
-   * The focused incidents in the order passed to {@link setFocus}. Empty when no focus is
-   * active on the entry or when the entry is unknown. Used by UI layers that step through
-   * the focused subset (prev/next).
+   * The focused incidents in the order passed to {@link setFocus}, or empty if no focus is
+   * active on the entry or the entry is unknown. UI layers use it to step through the
+   * focused subset (prev/next).
    */
   focusedFeatures(entryId: TrafficIncidentsEntry['id']): TrafficIncident[];
   /**
-   * Fly the camera to the i-th focused incident on an entry (0-based). Wraps out-of-range
-   * indices so callers can pass raw prev/next counters. No-op when the entry has no active
-   * focus. Line geometries fitBounds; points flyTo with a sensible zoom.
+   * Flies the camera to the i-th focused incident on an entry (0-based). Wraps out-of-range
+   * indices, so callers can pass raw prev/next counters. Does nothing if the entry has no active
+   * focus. Line geometries use fitBounds, points flyTo with a sensible zoom.
    */
   navigateFocus(entryId: TrafficIncidentsEntry['id'], index: number): void;
   /**
-   * Walk entries newest-first to find which one currently holds an incident with this id.
-   * Useful for UI layers that hold an incident id without remembering which entry produced it.
+   * Walks entries newest-first to find the one that holds an incident with this id. UI layers
+   * use it when they hold an incident id without remembering which entry produced it.
    */
   findEntryWithIncident(incidentId: string): TrafficIncidentsEntry | undefined;
   /**
-   * Start polling for an entry. Lazy-creates an {@link IncidentMonitor}, wires its events
-   * once, then delegates to {@link IncidentMonitor.start}. No-op when polling is already
+   * Starts polling for an entry. Lazy-creates an {@link IncidentMonitor}, wires its events
+   * once, then delegates to {@link IncidentMonitor.start}. Does nothing if polling is already
    * running. Throws on unknown entry id.
    */
   startMonitoring(entryId: TrafficIncidentsEntry['id'], area: MonitoredArea, deps: IncidentMonitorDeps, opts?: {
     intervalMs?: number;
     skipInitialTick?: boolean;
   }): void;
-  /** Stop polling. No-op when idle or unknown. */
+  /** Stops polling. Does nothing if idle or unknown. */
   stopMonitoring(entryId: TrafficIncidentsEntry['id']): void;
   /**
-   * True when the entry is *currently* being polled. A monitor stuck in
-   * `stopped-error` returns false here so the start tool can report a truthful
+   * Whether the entry is *currently* being polled. A monitor stuck in
+   * `stopped-error` returns false here, so the start tool can report a truthful
    * `alreadyRunning` and a fresh `start` call actually re-arms the timer
-   * instead of silently being treated as a no-op.
+   * instead of silently doing nothing.
    */
   isMonitored(entryId: TrafficIncidentsEntry['id']): boolean;
   private _createMonitorForEntry;
   private _requireEntry;
   private _teardownEntry;
   /**
-   * Hide every traffic-incidents entry currently on the map. Map-only — history is kept.
-   * Implements {@link ClearableMapSlice}.
+   * Hides every traffic-incidents entry on the map but keeps the history. Implements
+   * {@link ClearableMapSlice}.
    */
   clearShown(): Promise<void>;
   reset(): void;
@@ -2546,9 +2545,9 @@ declare class TrafficIncidentsState implements StateSlice {
 //#endregion
 //#region src/state/traffic-tiles/state.d.ts
 /**
- * State for traffic tile overlays — flow tiles and incident overlay tiles. These are
- * raster/tile layers that the user toggles on top of the base map; result caching and
- * per-result rendering for incident *features* lives in {@link TrafficIncidentsState},
+ * State for traffic tile overlays, the flow tiles and incident overlay tiles. These are
+ * raster/tile layers that the user toggles on top of the base map. Result caching and
+ * per-result rendering for incident *features* live in {@link TrafficIncidentsState},
  * and analytics aggregations in {@link TrafficAreaAnalyticsState}.
  *
  * @group Agent Toolkit
@@ -2585,15 +2584,15 @@ export declare const hidePreviousShownEntries: (slice: ShownEntriesSlice, keepEn
  */
 export type QueryAs = 'poi' | 'place';
 /**
- * Resolves a query string to up to `limit` Places. POI search when `queryAs === 'poi'`, geocoding
- * otherwise. Optional `bias` narrows the search to a region.
+ * Resolves a query string to up to `limit` Places, using POI search when `queryAs === 'poi'`,
+ * otherwise geocoding. The optional `bias` narrows the search to a region.
  */
 export declare const locatePlaces: (query: string, queryAs: QueryAs, options: {
   limit: number;
   bias?: GeoBias;
 }, execOptions?: ToolExecuteOptions) => Promise<Place[]>;
 /**
- * The best match for a query, as the `locatePlace` tool resolves it, for a custom tool that needs one place.
+ * Finds the best match for a query as the `locatePlace` tool does, for a custom tool that needs one place.
  * A failed or cancelled request rejects, so catch it in `execute`.
  *
  * @param bias - Favours results near a position, such as the map centre from {@link getViewportBias}.
@@ -2616,7 +2615,7 @@ export declare const locatePlace: (query: string, queryAs: QueryAs, bias?: GeoBi
 //#region src/tools/shared/location-input.d.ts
 /** @ignore */
 export type ResolvedLocation = {
-  /** Resolved place: a Place (with address metadata) or a bare [lng, lat] tuple. */
+  /** A resolved Place with address metadata, or a bare [lng, lat] tuple. */
   place: WaypointLike;
   position: Position;
   name: string;
@@ -2749,8 +2748,8 @@ export type ResolvedEntries = {
   trafficAreaAnalytics: TrafficAreaAnalyticsEntry[];
   byod: BYODEntry[];
 };
-/** Newest `timestamp` across every resolved source entry, or undefined when none carry one. The
- * canonical `sampledAt` for a recurring sandbox run over these inputs. */
+/** Newest `timestamp` across every resolved source entry, or undefined when none carry one, as
+ * the canonical `sampledAt` for a recurring sandbox run over these inputs. */
 export declare const latestTimestamp: (resolved: ResolvedEntries) => number | undefined;
 /**
  * Sandbox-facing inputs. Each kind is exposed as a single `<kind>ByEntry` record keyed by the entry id
@@ -2775,9 +2774,9 @@ export type SandboxInputs = {
   incidentsByEntry: Record<string, TrafficIncident[]> | undefined;
   /**
    * Per-source polygons collected from every requested source (place / places / ranges / customGeometries).
-   * Keyed by the tagged source `${kind}:${id}` (NOT a bare id: the same id can recur across kinds, e.g. a
-   * `place` vs a `customGeometries` entry), so the kind stays unambiguous. Each feature also self-describes
-   * its origin in `properties._source` (`{ kind, id }`).
+   * The key is the tagged source `${kind}:${id}`, not a bare id, since the same id can recur across kinds
+   * (e.g. a `place` and a `customGeometries` entry). This keeps the kind unambiguous. Each feature also
+   * self-describes its origin in `properties._source` (`{ kind, id }`).
    */
   geometriesByEntry: Record<string, PolygonFeature[]> | undefined;
   /**
@@ -2787,7 +2786,7 @@ export type SandboxInputs = {
    */
   trafficAreaAnalyticsByEntry: Record<string, TrafficAreaAnalytics> | undefined;
   /**
-   * Per-entry BYOD, keyed by entry id. Each value is a FeatureCollection; mixed geometry types are normal
+   * Per-entry BYOD, keyed by entry id. Each value is a FeatureCollection. Mixed geometry types are normal
    * (BYOD layers can be Point / LineString / Polygon).
    */
   byodByEntry: Record<string, FeatureCollection$1> | undefined;
@@ -2835,21 +2834,20 @@ export declare const prepareMultiInputs: (ids: MultiInputIds, state: ToolState)
  */
 export declare const BY_ENTRY_VIEWS_DOC: string;
 /**
- * Names injected into the sandbox by analyseData / processData, in fixed order.
+ * Names injected into the sandbox by analyseData, processData, createTracker and clusterIncidents, in fixed order.
  *
  * @ignore
  */
 export declare const MULTI_INPUT_SANDBOX_PARAMS: readonly ["placesByEntry", "routesByEntry", "incidentsByEntry", "geometriesByEntry", "trafficAreaAnalyticsByEntry", "byodByEntry", "h3", "turf", "routeUtils", "cluster"];
 /**
  * Common "tools available in the sandbox" prompt section, shared verbatim by
- * analyseData and processData so the injected-library docs live in ONE place and the
- * two tools never drift. It documents the three function namespaces handed to every
- * sandbox body — `turf` / `h3` (base usage rules via {@link buildSandboxCodePrompt}),
- * the cross-kind turf cheat-sheet ({@link CROSS_KIND_OPS_DOC}), and `routeUtils`
- * ({@link ROUTE_UTILS_DOC}) — in a fixed order. The two scope-gated docs are appended
- * only when relevant: cross-kind when scope commits to more than one kind, routeUtils
- * when `routes` is in scope (matching the conditional `routeUtils` usefulness). Returns
- * a block ending in a blank line, ready to drop straight into either tool's `code` doc.
+ * analyseData, processData, clusterIncidents and createTracker so the injected-library docs
+ * live in ONE place and the tools never drift. It documents `turf` / `h3` (base usage rules
+ * via {@link buildSandboxCodePrompt}) and the per-entry input views. With `scoped`, the helper
+ * docs follow the active kinds: the cross-kind turf cheat-sheet ({@link CROSS_KIND_OPS_DOC})
+ * when more than one is active, `routeUtils` ({@link ROUTE_UTILS_DOC}) with `routes`, and
+ * `cluster` with `incidents`. Returns a block ending in a blank line, ready to drop straight
+ * into a tool's `code` doc.
  *
  * @ignore
  */
@@ -3224,7 +3222,7 @@ export declare const areaWhereSchema: z.ZodObject<{
     widthMeters: z.ZodNumber;
   }, z.core.$strip>>;
 }, z.core.$strip>;
-/** The `where` fields resolve-where.ts resolves — inferred from {@link areaWhereSchema}. */
+/** The `where` fields resolve-where.ts resolves, inferred from {@link areaWhereSchema}. */
 export type AreaWhere = z.infer<typeof areaWhereSchema>;
 //#endregion
 //#region src/tools/shared/resolve-where.d.ts
@@ -3255,8 +3253,8 @@ export declare const resolveGlobal: () => ResolvedBias;
 export type ResolvedArea = {
   bbox: BBox;
   polygon?: Polygon | MultiPolygon;
-  /** The GROUNDED match label — `freeformAddress, <countryCode>` for a `query` area — i.e. what the
-   * data was actually loaded for, NOT the query echo. Lets a consumer surface where a query really
+  /** The grounded match label (`freeformAddress, <countryCode>` for a `query` area), meaning what the
+   * data was actually loaded for, not the query echo. It lets a consumer surface where a query really
    * resolved. */
   label?: string;
   source: AreaSource;
@@ -3283,12 +3281,12 @@ export declare const isResolveError: (r: unknown) => r is ResolveError;
  * @module agent-toolkit-tools
  *
  * The `routeUtils` namespace injected into sandboxed model-authored code, so a routes input can be
- * sliced and measured without re-implementing it. Its own module because the worker entry
- * (`sandbox/sdk-utils-worker-entry.ts`) is bundled standalone at SDK build time, so importing it
+ * sliced and measured without re-implementing it. It has its own module because the worker entry
+ * (`sandbox/sdk-utils-worker-entry.ts`) is bundled standalone at SDK build time, and importing it
  * from `multi-input.ts` would pull that module's prompt text into the worker bundle.
  *
- * Every function here depends only on `@turf/turf` — available in the worker as `self.turf` — and
- * pure local helpers, which is what makes the set portable into the sandbox.
+ * Every function here depends only on `@turf/turf` (available in the worker as `self.turf`) and
+ * pure local helpers, which makes the set portable into the sandbox.
  */
 /**
  * @ignore
@@ -3308,8 +3306,8 @@ export declare const routeUtils: {
  *
  * Compact schema documentation for the `Route` properties shape, reused by
  * every tool whose LLM-authored code reads a Routes FeatureCollection
- * (`analyseData`, `processData`) — injected per entry as `routesByEntry[id]`.
- * Only the non-GeoJSON-standard bits are spelled out — `Route` is a LineString Feature.
+ * (`analyseData`, `processData`), injected per entry as `routesByEntry[id]`.
+ * Only the non-GeoJSON-standard bits are spelled out, since `Route` is a LineString Feature.
  */
 /** @ignore */
 export declare const ROUTES_SCHEMA_DOC: string;
@@ -3348,7 +3346,7 @@ export declare const showResultsOnMap: (state: ToolState, placesEntryIds: readon
 //#endregion
 //#region src/tools/shared/tool-state-where-context.d.ts
 /** Adapts the live `ToolState` to the narrow `WhereContext` the resolver depends on. Keeping this
- * mapping in one place is what lets resolveAreas stay testable without a ToolState. */
+ * mapping in one place lets resolveAreas stay testable without a ToolState. */
 export declare const toolStateToWhereContext: (state: ToolState, options?: ToolExecuteOptions) => WhereContext;
 //#endregion
 //#region src/tools/shared/viewport-bias.d.ts
@@ -3359,8 +3357,8 @@ export declare const toolStateToWhereContext: (state: ToolState, options?: ToolE
  */
 export declare const MIN_VIEWPORT_BIAS_ZOOM = 6;
 /**
- * The map centre, to favour search results in view: pass it as `{ position }` to a service's `geoBias` or to
- * {@link locatePlace}'s `bias`. Below `minZoom` the view spans too wide an area to say where the user means.
+ * Returns the map centre, to favour search results in view. Pass it as `{ position }` to a service's `geoBias`
+ * or to {@link locatePlace}'s `bias`. Below `minZoom`, the view is too wide to say where the user means.
  *
  * @param map - The agent's base-map slice, `state.baseMap` in a tool's `execute`.
  * @returns The centre as `[longitude, latitude]`, or `undefined` below `minZoom`.
@@ -3425,26 +3423,26 @@ type CustomGeometriesEntry = BaseEntry<PolygonFeature[]> & {
  */
 type CustomGeometriesStateEvents = {
   /**
-   * History changed — entry added or cleared via `reset()`. `entries` is the full snapshot after
-   * the change; `changedIds` lists the ids of the entries this specific change added, replaced in
+   * An entry was added, or `reset()` cleared the history. `entries` is the full snapshot after
+   * the change, and `changedIds` lists the ids of the entries this change added, replaced in
    * place, or removed.
    */
   'entries-change': {
     entries: readonly CustomGeometriesEntry[];
     changedIds: readonly string[];
   };
-  /** Set of entries currently rendered on the map changed. */
+  /** The set of entries rendered on the map changed. */
   'shown-change': ReadonlySet<string>;
-  /** Display policy switched between `single` and `multiple`. */
+  /** The display policy switched between `single` and `multiple`. */
   'mode-change': EntryMode;
 };
 /**
- * State for derived / custom geometries — output of `processData` and any future
+ * The state for derived or custom geometries, the output of `processData` and any future
  * polygon-producing tool whose result doesn't belong to a place or a reachable-range entry.
  *
- * Each entry owns a dedicated GeometriesModule, lazy-initialised on first show, mirroring
- * the per-entry display model used by {@link RangeState}. Provenance metadata captures the
- * input sources (tagged ids) and the operation that produced the polygons.
+ * As in {@link RangeState}, each entry owns a dedicated GeometriesModule, initialised lazily
+ * on first show. Provenance metadata captures the input sources (tagged ids) and the
+ * operation that produced the polygons.
  *
  * @group Agent Toolkit
  */
@@ -3452,7 +3450,7 @@ declare class CustomGeometriesState implements ShownEntriesSlice, StateSlice {
   private readonly _ttMap;
   private _entries;
   private _entryMode;
-  /** Subscribe to state changes — see {@link CustomGeometriesStateEvents}. */
+  /** The state change events, listed in {@link CustomGeometriesStateEvents}. */
   readonly events: StateEvents<CustomGeometriesStateEvents>;
   constructor(_ttMap: TomTomMap);
   get entries(): readonly CustomGeometriesEntry[];
@@ -3460,40 +3458,40 @@ declare class CustomGeometriesState implements ShownEntriesSlice, StateSlice {
   /** Set of custom-geometries entry ids currently rendered on the map. */
   get shownEntryIds(): ReadonlySet<string>;
   /**
-   * Display policy: `multiple` (default) lets several derived-geometry entries render side
-   * by side; `single` enforces "at most one entry on the map" — switching to it auto-hides
+   * The display policy. `multiple` (default) lets several derived-geometry entries render
+   * side by side. `single` allows at most one entry on the map, and switching to it hides
    * older entries.
    */
   get entryMode(): EntryMode;
   setEntryMode(mode: EntryMode): Promise<void>;
   findById(entryId: string): CustomGeometriesEntry | undefined;
   /**
-   * Append a new entry. If `explicitId` collides, the slice auto-suffixes (`-2`, `-3`, ...).
-   * Returns the assigned id. Under `single` mode the new entry replaces every older one.
+   * Appends a new entry and returns its assigned id. If `explicitId` collides, the slice adds a
+   * suffix (`-2`, `-3`, ...). In `single` mode the new entry replaces every older one.
    */
   addEntry(features: PolygonFeature<CommonPlaceProps>[], provenance: CustomGeometriesEntry['provenance'], label: string, explicitId?: string): Promise<string>;
-  /** Lazy-init the entry's GeometriesModule, applying / re-applying the requested fill style. */
+  /** Initialises the entry's GeometriesModule lazily and applies the requested fill style. */
   getEntryGeometriesModule(entryId: string, fillStyle?: GeometryFillStyle): Promise<GeometriesModule>;
   /**
-   * Render this entry's polygons. `mode` is scoped to this entry's own layer:
-   * - `'replace'` (default) — show exactly `entry.data`, clearing whatever the
-   *   entry's module had rendered before.
-   * - `'add'` — merge `entry.data` with the polygons currently shown on this entry's
-   *   layer (deduped by feature id). Mostly only meaningful when re-showing the same entry.
+   * Renders the entry's polygons. `mode` applies to this entry's own layer only:
+   * - `'replace'` (default) shows exactly `entry.data` and clears whatever the
+   *   entry's module rendered before.
+   * - `'add'` merges `entry.data` with the polygons shown on this entry's layer,
+   *   deduped by feature id. It matters mostly when re-showing the same entry.
    *
-   * Cross-entry visibility is handled separately: under `entryMode === 'single'` other
-   * shown entries are hidden first; otherwise the caller uses `hideEntry` / the
-   * tools' `hidePreviousEntries` option.
+   * Other entries are handled separately. With `entryMode === 'single'`, other shown
+   * entries are hidden first. Otherwise the caller uses `hideEntry` or the tools'
+   * `hidePreviousEntries` option.
    */
   showEntry(entryId: string, fillStyle?: GeometryFillStyle, mode?: 'add' | 'replace'): Promise<void>;
   private _hideOthersUnderSingleMode;
   hideEntry(entryId: string): Promise<void>;
-  /** Drop a single entry from history (clears its module first). No-op when unknown. */
+  /** Clears an entry's module, then drops the entry from history. Does nothing for an unknown id. */
   removeEntry(entryId: string): Promise<void>;
   private _requireEntry;
   /**
-   * Hide every custom-geometries entry currently on the map. Map-only — history is kept.
-   * Implements {@link ClearableMapSlice}.
+   * Hides every custom-geometries entry on the map but keeps the history. Implements
+   * {@link ClearableMapSlice}.
    */
   clearShown(): Promise<void>;
   reset(): void;
@@ -3501,16 +3499,16 @@ declare class CustomGeometriesState implements ShownEntriesSlice, StateSlice {
 //#endregion
 //#region src/state/state.d.ts
 /**
- * Per-slice display policy. With `multiple` (default) several history entries can be on the
- * map at once; with `single` only the most recent one stays. Switching from `multiple` to
- * `single` automatically drops every entry except the latest (and clears their modules) so
+ * The per-slice display policy. With `multiple` (default), several history entries can be on the
+ * map at once. With `single`, only the most recent one stays. Switching from `multiple` to
+ * `single` automatically drops every entry except the latest and clears their modules, so
  * the map matches the new policy immediately.
  *
  * @group Agent Toolkit
  */
 type EntryMode = 'single' | 'multiple';
 /**
- * State slice that owns a history of entries and can be driven into `single` or `multiple`
+ * A state slice that owns a history of entries and can be set to `single` or `multiple`
  * mode. Every {@link ToolState} slice with `setEntryMode` implements this shape, which lets
  * callers (the `setEntryMode` tool, `createMapAgent`'s `dataEntries` option, …) handle the
  * whole family uniformly without listing slice names.
@@ -3525,12 +3523,12 @@ interface EntryModeSlice {
   setEntryMode(mode: EntryMode): Promise<void>;
 }
 /**
- * Data-entry kind names — the vocabulary used by `dataEntries` on `createMapAgent`. Superset
- * of the analyse/process input kinds (`EntryDataKind`) — adds `ranges`, which has its own
+ * The data-entry kind names that `dataEntries` on `createMapAgent` uses. They extend the
+ * analyse/process input kinds (`EntryDataKind`) with `ranges`, which has its own
  * entry-mode-supporting slice but is not a top-level input kind for those tools.
  *
- * The kind names are LLM-facing (`routes`, `incidents`) rather than slice names (`routing`,
- * `trafficIncidents`); the slice mapping is internal — see {@link DATA_ENTRY_KIND_TO_SLICE}.
+ * The kind names are LLM-facing (`routes`, `incidents`) instead of slice names (`routing`,
+ * `trafficIncidents`). The slice mapping is internal (see {@link DATA_ENTRY_KIND_TO_SLICE}).
  *
  * @group Agent Toolkit
  */
@@ -3543,22 +3541,22 @@ type DataEntryKind = 'places' | 'routes' | 'incidents' | 'customGeometries' | 't
 type DataEntryConfig = {
   /**
    * When `false`, the kind is removed from the agent's tool surface entirely:
-   * - the kind disappears from `analyseData` / `processData` scope and input fields;
-   * - related recall / display / fetch tools are dropped from the registry
+   * - The kind disappears from the `analyseData` and `processData` scope and input fields.
+   * - Related recall, display and fetch tools are dropped from the registry
    *   (see {@link TOOLS_BY_DATA_ENTRY_KIND}).
    *
-   * Default: `true`.
+   * Defaults to `true`.
    */
   enabled?: boolean;
   /**
-   * Initial entry-display policy for the underlying slice. `single` keeps only the latest
-   * entry on the map (others auto-hide); `multiple` (default) lets several coexist.
+   * The initial entry-display policy for the underlying slice. `single` keeps only the latest
+   * entry on the map and hides the others. `multiple` (default) lets several coexist.
    */
   entryMode?: EntryMode;
 };
 /**
- * Mapping from {@link DataEntryKind} (LLM-facing name) to the {@link ToolState} slice key
- * that owns the entries for that kind. Used by `createMapAgent` to apply `entryMode` from
+ * Maps each {@link DataEntryKind} (LLM-facing name) to the {@link ToolState} slice key that
+ * owns its entries. `createMapAgent` uses it to apply `entryMode` from
  * `dataEntries[kind].entryMode` to the right slice.
  *
  * @group Agent Toolkit
@@ -3573,34 +3571,33 @@ export declare const DATA_ENTRY_KIND_TO_SLICE: {
   readonly ranges: "ranges";
 };
 /**
- * Compile-time union of {@link ToolState} keys whose slice supports {@link EntryMode}.
- * Names match the {@link ToolState} keys exactly — `routing` (not `routes`),
- * `customGeometries` (not `geometries`) — so the slice name in the tool API never drifts
+ * The compile-time union of {@link ToolState} keys whose slice supports {@link EntryMode}.
+ * Names match the {@link ToolState} keys exactly, such as `routing` (not `routes`) and
+ * `customGeometries` (not `geometries`), so the slice name in the tool API never drifts
  * from the property on `state`.
  *
- * Auto-grows when a new slice implements `setEntryMode`: the union picks up the new key,
- * and the runtime list {@link ENTRY_MODE_SLICE_NAMES} fails to type-check until the key
- * is added there too.
+ * When a new slice implements `setEntryMode`, the union picks up its key, and the runtime
+ * list {@link ENTRY_MODE_SLICE_NAMES} fails to type-check until the key is added there too.
  *
  * @group Agent Toolkit
  */
 type EntryModeSliceName = { [K in keyof ToolState]: ToolState[K] extends EntryModeSlice ? K : never; }[keyof ToolState];
 /**
- * Runtime enumeration of slice names that support entry mode. The `satisfies` clause
- * makes drift a compile error: when a new {@link ToolState} slice gains `setEntryMode`,
- * this constant has to be updated before the package will build.
+ * The runtime list of slice names that support entry mode. Its `satisfies` clause makes
+ * drift a compile error. When a new {@link ToolState} slice gains `setEntryMode`, the
+ * package won't build until this constant is updated.
  *
  * @group Agent Toolkit
  */
 export declare const ENTRY_MODE_SLICE_NAMES: readonly EntryModeSliceName[];
 /**
- * State slice that owns a set of "entries" (routes, ranges) where each entry can be hidden
- * individually by id and the slice exposes the currently-shown set. Implemented by
- * {@link RoutingState} and {@link RangeState}; consumed by helpers that need to hide
- * previously-shown entries before rendering a new one (see `hidePreviousShownEntries`).
+ * A state slice that owns a set of "entries" (routes, ranges), each of which can be hidden
+ * individually by id, and exposes the shown set. {@link RoutingState} and {@link RangeState}
+ * implement it. Helpers that hide previously-shown entries before rendering a new one
+ * consume it (see `hidePreviousShownEntries`).
  *
- * Not implemented by {@link PlacesState}, which uses a wider per-entry marker-type model
- * (`removeShownEntries(ids)` rather than `hideEntry(id)`).
+ * {@link PlacesState} doesn't implement it, because it uses a wider per-entry marker-type
+ * model (`removeShownEntries(ids)` instead of `hideEntry(id)`).
  *
  * @group Agent Toolkit
  */
@@ -3618,17 +3615,17 @@ interface ShownEntriesSlice extends StateSlice {
  */
 type BYODStateEvents = {
   /**
-   * History changed — entry added, removed, or cleared via `reset()`. `entries` is the full
-   * snapshot after the change; `changedIds` lists the ids of the entries this specific change
-   * added, replaced in place, or removed.
+   * An entry was added or removed, or `reset()` cleared the history. `entries` is the full
+   * snapshot after the change, and `changedIds` lists the ids of the entries this change added,
+   * replaced in place, or removed.
    */
   'entries-change': {
     entries: readonly BYODEntry[];
     changedIds: readonly string[];
   };
-  /** Set of entries currently rendered on the map changed. */
+  /** The set of entries rendered on the map changed. */
   'shown-change': ReadonlySet<string>;
-  /** Display policy switched between `single` and `multiple`. */
+  /** The display policy switched between `single` and `multiple`. */
   'mode-change': EntryMode;
 };
 /**
@@ -3638,9 +3635,9 @@ type BYODStateEvents = {
  */
 type AddBYODEntryOptions = {
   /**
-   * Explicit MapLibre layer specs. Layers are never derived automatically:
-   * when omitted the entry is created with no layers and renders nothing until
-   * they are set — by the agent via `setByodLayers`, or by passing them here.
+   * Explicit MapLibre layer specs, never derived automatically. You pass them here,
+   * or the agent sets them via `setByodLayers`. Until then the entry renders nothing.
+   * Either way they are only stored, and {@link BYODState.showEntry} renders them.
    */
   layers?: CustomGeoJSONLayerSpec[];
   /** Provenance for the data. Defaults to `{ kind: 'integrator' }`. */
@@ -3652,9 +3649,9 @@ type AddBYODEntryOptions = {
   explicitId?: string;
 };
 /**
- * Verdict returned by a {@link ByodSourceUrlValidator}: explicitly allow the fetch with
- * `{ valid: true }`, or block it with `{ valid: false, reason }` — the `reason` is surfaced
- * to the model as the tool error.
+ * The verdict a {@link ByodSourceUrlValidator} returns. `{ valid: true }` explicitly allows
+ * the fetch, and `{ valid: false, reason }` blocks it and surfaces the `reason` to the model
+ * as the tool error.
  *
  * @group Agent Toolkit
  */
@@ -3665,30 +3662,30 @@ type ByodSourceUrlValidation = {
   reason: string;
 };
 /**
- * App-supplied authorization hook for BYOD source URLs. Runs inside
- * `addByodSource` AFTER the built-in scheme / size / timeout policy and BEFORE
- * the network fetch. Return `{ valid: true }` to allow the fetch or
- * `{ valid: false, reason }` to block it (see {@link ByodSourceUrlValidation}).
- * May be sync or async — e.g. an allowlist lookup.
- *
- * The toolkit can't enforce SSRF guarantees the host itself can't, so it leaves
- * the URL surface open by default; this hook lets a deployment add its own
- * policy — refuse cloud-metadata endpoints (`169.254.169.254`), restrict to
- * known hosts, etc. — without the SDK prescribing one for everyone. Configure
- * via the `byod.validateSourceUrl` option on `createMapAgent`, or assign
+ * An app-supplied authorization hook for BYOD source URLs. `addByodSource` runs it
+ * after the built-in scheme, size and timeout policy and before the network fetch.
+ * Return `{ valid: true }` to allow the fetch or `{ valid: false, reason }` to
+ * block it (see {@link ByodSourceUrlValidation}). It may be sync or async, such as
+ * an allowlist lookup.
+ *
+ * The toolkit can't enforce SSRF guarantees the host itself can't, so by default it
+ * leaves the URL surface open. This hook lets a deployment add its own policy, such
+ * as refusing cloud-metadata endpoints (`169.254.169.254`) or allowing only known
+ * hosts, without the SDK prescribing one for everyone. Set it via the
+ * `byod.validateSourceUrl` option on `createMapAgent`, or assign
  * `state.byod.sourceUrlValidator` directly.
  *
  * @group Agent Toolkit
  */
 type ByodSourceUrlValidator = (url: URL) => ByodSourceUrlValidation | Promise<ByodSourceUrlValidation>;
 /**
- * State slice for BYOD (bring-your-own-data) GeoJSON layers — customer-owned
- * data that doesn't fit places / routes / ranges / custom-geometries. Each
- * entry wraps a {@link CustomGeoJSONModule} so the agent can render, query,
- * and pipe it through analyseData / processData.
+ * The state slice for BYOD (bring-your-own-data) GeoJSON layers, the customer-owned
+ * data that doesn't fit places, routes, ranges or custom geometries. Each entry
+ * wraps a {@link CustomGeoJSONModule} so the agent can render, query, and pipe it
+ * through analyseData or processData.
  *
- * Per-entry display model mirrors {@link CustomGeometriesState}: every entry
- * owns its own module, lazy-initialised on first show.
+ * As in {@link CustomGeometriesState}, every entry owns its own module, initialised
+ * lazily on first show.
  *
  * @group Agent Toolkit
  */
@@ -3696,12 +3693,12 @@ declare class BYODState implements ShownEntriesSlice, StateSlice {
   private readonly _ttMap;
   private _entries;
   private _entryMode;
-  /** Subscribe to state changes — see {@link BYODStateEvents}. */
+  /** The state change events, listed in {@link BYODStateEvents}. */
   readonly events: StateEvents<BYODStateEvents>;
   /**
-   * Optional authorization hook for `addByodSource` URL fetches — see
-   * {@link ByodSourceUrlValidator}. Unset = no restriction beyond the built-in
-   * scheme / size / timeout policy.
+   * The optional authorization hook for `addByodSource` URL fetches (see
+   * {@link ByodSourceUrlValidator}). If unset, only the built-in scheme, size
+   * and timeout policy applies.
    */
   sourceUrlValidator?: ByodSourceUrlValidator;
   constructor(_ttMap: TomTomMap);
@@ -3713,35 +3710,35 @@ declare class BYODState implements ShownEntriesSlice, StateSlice {
   setEntryMode(mode: EntryMode): Promise<void>;
   findById(entryId: string): BYODEntry | undefined;
   /**
-   * Append a new BYOD entry. Under `single` mode the new entry replaces every older one (hides
-   * + drops them before the new entry is pushed, so the caller never sees the new entry
-   * rendered on top of a still-visible old one). Returns the assigned id.
+   * Appends a new BYOD entry and returns its assigned id. In `single` mode the new entry
+   * replaces every older one. It hides and drops them before pushing the new entry, so the
+   * caller never sees it rendered on top of a still-visible old one.
    */
   addEntry(data: FeatureCollection$1, label: string, options?: AddBYODEntryOptions): Promise<string>;
   /**
-   * Replace the MapLibre layer specs an entry renders under. When the entry already owns a
-   * module (it has been shown at least once) the new specs are pushed live via the module's
-   * `applyConfig` runtime layer diff — no tear-down, no flicker. When no module exists yet the
-   * specs are stored and the next {@link showEntry} picks them up. Throws on an unknown id.
+   * Replaces the MapLibre layer specs an entry renders under. If the entry already owns a
+   * module because it was shown at least once, the module's `applyConfig` runtime layer diff
+   * pushes the new specs live, without tear-down or flicker. Otherwise the specs are stored
+   * and the next {@link showEntry} picks them up. Throws on an unknown id.
    */
   setEntryLayers(entryId: string, layers: CustomGeoJSONLayerSpec[]): void;
   /**
-   * Lazy-init the entry's CustomGeoJSONModule. The module is created with a
-   * single source named `data`, configured with this entry's `layers`. To swap
-   * layers after creation, call {@link setEntryLayers} — it pushes the new specs
-   * into this module via `applyConfig` rather than recreating it.
+   * Initialises the entry's CustomGeoJSONModule lazily. The module has a single
+   * source named `data`, configured with this entry's `layers`. To swap layers
+   * afterwards, call {@link setEntryLayers}, which pushes the new specs into this
+   * module via `applyConfig` instead of recreating it.
    */
   getEntryModule(entryId: string): Promise<CustomGeoJSONModule>;
-  /** Render this entry on the map. */
+  /** Renders the entry on the map. */
   showEntry(entryId: string): Promise<void>;
   private _hideOthersUnderSingleMode;
   hideEntry(entryId: string): Promise<void>;
-  /** Drop a single entry from history (clears its module first). No-op when unknown. */
+  /** Clears an entry's module, then drops the entry from history. Does nothing for an unknown id. */
   removeEntry(entryId: string): Promise<void>;
   private _requireEntry;
   /**
-   * Hide every BYOD layer currently on the map. Map-only — history is kept.
-   * Implements {@link ClearableMapSlice}.
+   * Hides every BYOD layer on the map but keeps the history. Implements
+   * {@link ClearableMapSlice}.
    */
   clearShown(): Promise<void>;
   reset(): void;
@@ -3751,15 +3748,15 @@ declare class BYODState implements ShownEntriesSlice, StateSlice {
 /**
  * @module agent-toolkit-system-prompt
  *
- * Behavioral contract: persona, tone, dual-response, cadence — lives here.
+ * The behavioural contract (persona, tone, dual-response, cadence) lives here.
  *
- * Tool mechanics: call shape, return shape, error handling, when-to-use vs.
- * which-tool-next — lives in the relevant tool's description string and Zod
- * schema. Each tool re-explains its own role; the LLM sees those alongside
- * this prompt. The intent classifier (see `utils/intent-classifier.ts`) also
- * scopes tools per step, so a tool's description is only in context when that
- * tool is active — keep cross-cutting safety rules here (always present), and
- * leave per-tool mechanics to the tool itself.
+ * Tool mechanics (call shape, return shape, error handling, when-to-use vs.
+ * which-tool-next) live in each tool's description string and Zod schema. Each
+ * tool re-explains its own role, and the LLM sees those alongside this prompt.
+ * The intent classifier (see `utils/intent-classifier.ts`) also scopes tools per
+ * step, so a tool's description is only in context while that tool is active.
+ * Keep cross-cutting safety rules here, where they are always present, and leave
+ * per-tool mechanics to the tool.
  *
  * If you find yourself adding lines here to fix an LLM mistake, ask first
  * whether the fix belongs in a tool description or a tool error message.
@@ -3775,14 +3772,14 @@ declare class BYODState implements ShownEntriesSlice, StateSlice {
  */
 type SystemPromptSection = 'identity' | 'capabilities' | 'rejectionRules' | 'responseFormatting' | 'dataConfidence' | 'toolExecution' | 'sessionState';
 /**
- * Per-section body overrides. Each key replaces that section's body; omitted
- * sections fall back to {@link SYSTEM_PROMPT_SECTIONS}. Accepted by
- * {@link composeSystemPrompt} and `MapAgentOptions.systemPrompt`.
+ * Per-section body overrides. Each key replaces that section's body, and omitted
+ * sections fall back to {@link SYSTEM_PROMPT_SECTIONS}. {@link composeSystemPrompt}
+ * and `MapAgentOptions.systemPrompt` accept them.
  *
  * @remarks
  * To *extend* rather than replace a section, read its current default from the
- * exported {@link SYSTEM_PROMPT_SECTIONS} map and override with a derived string
- * — e.g. append a rule, prepend a note, or hand the default to a coding agent to
+ * exported {@link SYSTEM_PROMPT_SECTIONS} map and override with a derived string,
+ * e.g. append a rule, prepend a note, or hand the default to a coding agent to
  * rewrite under some criteria:
  *
  * ```typescript
@@ -3796,35 +3793,35 @@ type SystemPromptSection = 'identity' | 'capabilities' | 'rejectionRules' | 'res
  */
 type SystemPromptSectionOverrides = Partial<Record<SystemPromptSection, string>>;
 /**
- * The default body text for each base-prompt section — heading excluded.
+ * The default body text for each base-prompt section, without its heading.
  *
  * @remarks
- * Each value is the section's content only; the structural heading (e.g.
- * `RESPONSE FORMATTING:`) is added by {@link composeSystemPrompt}. So an override
- * passes just the body — `composeSystemPrompt({ responseFormatting: 'Reply in Spanish.' })`
+ * Each value holds only the section's content. {@link composeSystemPrompt} adds the
+ * structural heading (e.g. `RESPONSE FORMATTING:`), so an override passes just the
+ * body. For example, `composeSystemPrompt({ responseFormatting: 'Reply in Spanish.' })`
  * still renders under the `RESPONSE FORMATTING:` heading.
  *
- * The behavioral prose is split so each concern is overridable on its own:
- * - `identity` — who the assistant is and its tone of voice; the natural hook to
+ * The behavioural prose is split so each concern is overridable on its own:
+ * - `identity` — who the assistant is and its tone of voice, the natural hook to
  *   rebrand or set a persona.
  * - `capabilities` — the map environment plus a compact summary of what the
- *   toolkit can do. Kept at the group level (not per-tool) so it does not drift
- *   as tools change; the exact mechanics live in each tool's description and the
- *   classifier prompt. It also gives `rejectionRules` something concrete to steer
- *   the user back toward.
+ *   toolkit can do. It stays at the group level (not per-tool) so it does not
+ *   drift as tools change. The exact mechanics live in each tool's description and
+ *   the classifier prompt. It also gives `rejectionRules` something concrete to
+ *   steer the user back toward.
  * - `rejectionRules` — how to handle in-scope / mixed / out-of-scope / illegal
  *   requests, and the requirement to always explain a rejection.
  * - `dataConfidence` — how to surface incomplete, partial, stale, or conflicting
  *   data instead of presenting it as complete.
  *
  * Location-reference routing ("near me" → getCurrentLocation, "here" →
- * getViewport) is intentionally NOT a section: it is a tool-selection rule
+ * getViewport) is intentionally **not** a section. It is a tool-selection rule
  * already owned by the classifier prompt and the two tools' cross-referencing
  * descriptions.
  *
- * This map is the canonical source of the default body text, exported so a
- * consumer can read a default and override with a derived value (extend, prefix,
- * or rewrite it) — see {@link SystemPromptSectionOverrides}.
+ * This map is the exported, canonical source of the default body text. A consumer
+ * can read a default and override it with a derived value (extend, prefix, or
+ * rewrite it). See {@link SystemPromptSectionOverrides}.
  *
  * @group Agent Toolkit
  */
@@ -3833,8 +3830,8 @@ export declare const SYSTEM_PROMPT_SECTIONS: Record<SystemPromptSection, string>
  * Composes the base system prompt from {@link SYSTEM_PROMPT_SECTIONS}, applying
  * any per-section overrides.
  *
- * @param overrides - Replacement **body** text keyed by section; omitted
- * sections fall back to the default. The section heading is added automatically,
+ * @param overrides - Replacement **body** text keyed by section. Omitted
+ * sections fall back to the default. It adds the section heading itself,
  * so an override does not repeat it. Pass the result to
  * `MapAgentOptions.systemPrompt`.
  * @returns The composed system prompt string.
@@ -3859,9 +3856,9 @@ export declare const composeSystemPrompt: (overrides?: SystemPromptSectionOverri
  * The base system prompt that teaches the LLM how to use the agent toolkit tools.
  *
  * @remarks
- * Equivalent to `composeSystemPrompt()` with no overrides. Export this constant
- * so consumers can reference or extend it when providing a custom system prompt
- * via `MapAgentOptions.systemPrompt`. To replace just one section, prefer
+ * Equivalent to `composeSystemPrompt()` with no overrides. It is exported so you
+ * can reference or extend it when you provide a custom system prompt via
+ * `MapAgentOptions.systemPrompt`. To replace just one section, use
  * {@link composeSystemPrompt} instead of rebuilding the whole string.
  *
  * @example
@@ -3915,12 +3912,12 @@ export declare const buildSystemPrompt: ({ customPrompt, prefix, suffix }?: Buil
 //#endregion
 //#region src/tools/tool-registry.d.ts
 /**
- * Default tool set for the agent toolkit. Each entry is a {@link ToolDefinition}
- * — either a static `ToolEntry` or a `ToolEntryBuilder` that tailors the tool to
+ * Default tool set for the agent toolkit. Each entry is a {@link ToolDefinition},
+ * either a static `ToolEntry` or a `ToolEntryBuilder` that tailors the tool to
  * {@link ToolBuildOptions} (e.g. feature flags) at agent-creation time.
  *
- * Included automatically by createMapAgent unless includeDefaultTools is false.
- * Use resolveTools() for manual composition outside createMapAgent.
+ * createMapAgent includes it automatically unless includeDefaultTools is false.
+ * For manual composition outside createMapAgent, use resolveTools().
  *
  * @group Agent Toolkit
  */
@@ -3961,11 +3958,8 @@ export declare const DEFAULT_TOOLS: {
   getStandardMapStyles: ToolDefinition;
   setMapStandardStyle: ToolDefinition;
   setLanguage: ToolDefinition;
-  toggleTilesPOIs: ToolDefinition;
-  toggleTilesBaseMapLayerGroups: ToolDefinition;
+  setGeopoliticalView: ToolDefinition;
   setMapStyling: ToolDefinition;
-  toggleTilesTrafficFlow: ToolDefinition;
-  toggleTilesTrafficIncidents: ToolDefinition;
   getMapStyleLayers: ToolDefinition;
   setLayoutProperties: ToolDefinition;
   setPaintProperties: ToolDefinition;
@@ -3995,12 +3989,12 @@ type ToolName = keyof typeof DEFAULT_TOOLS;
 export declare const TOOL_NAMES: ToolName[];
 /**
  * Default tool names that should be dropped from the registry when a {@link DataEntryKind}
- * is disabled. Only default-tool names are listed here — user-supplied custom tools are
- * never filtered automatically; integrators that want to gate their own tools on enabled
- * kinds can read `dataEntries` themselves.
+ * is disabled. Only default-tool names are listed here. User-supplied custom tools are
+ * never filtered automatically. To gate your own tools on enabled kinds, read
+ * `dataEntries` yourself.
  *
  * Tools that span multiple kinds (`clearMap`, `recallState`, `setEntryMode`, …) are
- * intentionally absent — they keep working regardless of which kinds are disabled.
+ * intentionally absent, since they keep working regardless of which kinds are disabled.
  *
  * @group Agent Toolkit
  */
@@ -4011,7 +4005,7 @@ export declare const TOOLS_BY_DATA_ENTRY_KIND: Record<DataEntryKind, readonly To
  * tool's default (full-surface) shape. Tools without prompts map to `[]`.
  *
  * Surface these in chat UIs to keep starter suggestions in sync with what the
- * tools can actually do — the registry stays the single source of truth.
+ * tools can actually do. The registry stays the single source of truth.
  *
  * @group Agent Toolkit
  */
@@ -4027,16 +4021,19 @@ type ClassificationResult = {
   /** Tool names selected by the classifier. */
   activeToolNames: string[];
   /**
-   * Optional per-tool scope. Keyed by tool name, value is the raw classifier
-   * output for that tool — validated against the tool's `scopeSchema` in
-   * `prepareStep` before any narrowing is applied. Tools without
-   * `scopeSchema`, or for which the classifier omitted a scope, retain
-   * their full description and inputSchema for the turn.
+   * The optional per-tool scope, keyed by tool name. Each value is the raw
+   * classifier output for that tool, which `prepareStep` validates against
+   * the tool's `scopeSchema` before applying any narrowing. Tools without
+   * `scopeSchema`, or with no scope from the classifier, keep their full
+   * description and inputSchema for the turn.
    */
   toolScopes?: Record<string, unknown>;
-  /** Wall-clock time in ms for the classification step only (not the agent response). */
+  /** The wall-clock time in ms of the classification step, excluding the agent response. */
   timeMs: number;
-  /** Token usage for the classification LLM call. */
+  /**
+   * Token usage of the classification, summed over its one LLM call, or two when the first
+   * answer fails validation.
+   */
   usage: {
     inputTokens: number;
     outputTokens: number;
@@ -4050,8 +4047,8 @@ type ClassificationResult = {
  */
 type ClassifierOptions = {
   /**
-   * Language model to use for structured generation.
-   * Ideally should be a fast, low-cost model (e.g. gpt-4o-mini).
+   * The language model for structured generation, ideally a fast, low-cost
+   * one such as gpt-4o-mini.
    */
   chatModel: LanguageModel;
   /** Per-tool metadata used to build the classifier prompt. */
@@ -4069,10 +4066,10 @@ type ConversationMessage = {
   content: string;
 };
 /**
- * Classify a user conversation to determine which tools to activate.
+ * Classifies a user conversation to pick the tools to activate.
  *
  * The `conversation` should contain the last user message plus a compaction
- * of the previous chat history (each truncated to save tokens).
+ * of the earlier chat history, each message truncated to save tokens.
  *
  * @example
  * ```typescript
@@ -4088,14 +4085,14 @@ type ConversationMessage = {
 export declare const classifyUserIntent: (conversation: ConversationMessage[], options: ClassifierOptions) => Promise<ClassificationResult>;
 /**
  * Extracts the text content of the last user message in a message array.
- * Returns null if no user message is found or if content has no text.
+ * Returns `null` if there is no user message or its content has no text.
  *
  * @group Agent Toolkit
  */
 export declare const extractLastUserText: (messages: ReadonlyArray<ModelMessage>) => string | null;
 /**
- * Creates the default LLM-based classifier. Uses structured generation to select
- * the minimal tool set for each user message.
+ * Creates the default LLM-based classifier, which selects the minimal tool set for each user
+ * message with structured generation.
  *
  * @param options.model - Language model for classification (ideally fast/cheap like gpt-4o-mini)
  * @param options.maxHistoryMessages - Max prior turns for context. Default: 8
@@ -4122,14 +4119,14 @@ type ProviderOptions = Record<string, Record<string, JSONValue | undefined>>;
  */
 export type ToolNameHint = ToolName | (string & {});
 /**
- * Tool-facing union of state slices that own analysable entries — the
+ * Tool-facing union of state slices that own analysable entries, the
  * vocabulary used by tools that read from multiple slices (`analyseData`,
  * `processData`) and by the classifier when proposing per-call scope.
  *
  * Distinct from {@link EntryModeSliceName}, which uses the literal state-slice
  * keys (`routing`, `trafficIncidents`, …) for state-level operations.
  *
- * `ranges` is intentionally excluded: it feeds the analysis/processing tools
+ * `ranges` is intentionally excluded. It feeds the analysis/processing tools
  * only via `geometriesEntryIDs` (its isochrone polygons), not as a direct
  * top-level input.
  *
@@ -4137,8 +4134,8 @@ export type ToolNameHint = ToolName | (string & {});
  */
 export type EntryDataKind = 'places' | 'routes' | 'incidents' | 'customGeometries' | 'trafficAreaAnalytics' | 'byod';
 /**
- * State passed to tool factory functions. Organized by feature area,
- * each sub-state mixes lazy module access with the current service data
+ * State passed to tool factory functions, organised by feature area.
+ * Each sub-state mixes lazy module access with the current service data
  * produced during the session.
  *
  * @group Agent Toolkit
@@ -4157,68 +4154,69 @@ export type EntryDataKind = 'places' | 'routes' | 'incidents' | 'customGeometrie
  * ```
  */
 export type ToolState = {
-  /** Places layer: PlacesModule plus an append-only search history. */
+  /** The places layer's PlacesModule and append-only search history. */
   places: PlacesState;
-  /** Map POI layer: visibility, filtering, and category management. */
+  /** Map POI layer visibility, filtering and category management. */
   mapPOIs: MapPOIsState;
   /** Route calculation, waypoint management, and planning parameter state. */
   routing: RoutingState;
-  /** Base map display: style, language, viewport and layers. */
+  /** The displayed base map's style, language, viewport and layers. */
   baseMap: BaseMapState;
-  /** Traffic tile overlays: flow tiles + incident overlay tiles. */
+  /** Traffic flow tiles and incident overlay tiles. */
   trafficTiles: TrafficTilesState;
-  /** Traffic area analytics: aggregation module + last result + viz config. */
+  /** Traffic area analytics aggregation module, last result and viz config. */
   trafficAreaAnalytics: TrafficAreaAnalyticsState;
-  /** Traffic incidents: fetched entry history and per-entry rendering. */
+  /** Fetched traffic incident entry history and per-entry rendering. */
   trafficIncidents: TrafficIncidentsState;
-  /** Reachable range results: origin, budgets, and bbox summaries. */
+  /** Reachable range results, with origin, budgets and bbox summaries. */
   ranges: RangeState;
-  /** Derived/custom polygon entries — output of `processData`. */
+  /** Derived/custom polygon entries that `processData` outputs. */
   customGeometries: CustomGeometriesState;
-  /** Bring-your-own-data GeoJSON layers — customer-authored data the agent can read and render. */
+  /** Bring-your-own-data GeoJSON layers, customer-authored data the agent can read and render. */
   byod: BYODState;
   /**
-   * Strategy used to run code-generation tools (`analyseData` / `processData`).
-   * Initialised to the main-thread executor by `createToolState`, and overridden
-   * by `createMapAgent` from {@link MapAgentOptions.codeExecution}. Tools read this
+   * Strategy used to run code-generation tools (`analyseData`, `processData`, `createTracker`,
+   * `clusterIncidents`). `createToolState` initialises it to the env-resolved executor, and
+   * `createMapAgent` re-resolves it with {@link MapAgentOptions.codeExecution}. Tools read this
    * to select where sandbox code runs.
    */
   codeExecution: SandboxExecutor;
   /**
    * The single recurrence engine. Owners (`analyses`, `trackers`) register entry-anchored jobs and keep
-   * the returned handles; the engine re-runs each active job when its source entries change. Generic —
-   * it never interprets a job's recipe (the tools layer builds the run closure). See {@link JobEngine}.
+   * the returned handles. The engine re-runs each active job when its source entries change. It is generic
+   * and never interprets a job's recipe (the tools layer builds the run closure). See {@link JobEngine}.
    */
   engine: JobEngine;
   /**
    * Single session-level registry of every analysis (one-shot + recurring) across all entry kinds.
    * Results live here, and per-entry views read them on demand via {@link Analyses.getAnalysesForEntry}.
-   * `analyseData` registers a record + a job on {@link JobEngine}; `monitorAnalysis` toggles the job's
+   * `analyseData` registers a record and a job on {@link JobEngine}. `monitorAnalysis` toggles the job's
    * active flag.
    */
   analyses: Analyses;
   /**
-   * Generic trackers — rising-edge reducers fed by their own {@link JobEngine} jobs. A tracker fires an
-   * alert/event when its rule's {@link Verdict} crosses an edge (`ingestVerdict`); owns the durable
-   * {@link TrackerEvent} log.
+   * Generic trackers, rising-edge reducers fed by their own {@link JobEngine} jobs. A tracker fires an
+   * alert/event when its rule's {@link Verdict} crosses an edge (`ingestVerdict`). The slice
+   * keeps the durable {@link TrackerEvent} log.
    */
   trackers: EventsState;
 };
 /**
- * Tunes `analyseData` / `processData` sandbox execution. **Where** the code runs is
- * not configurable: it is chosen by environment — a sandboxed, opaque-origin
- * iframe + Web Worker in the browser (no DOM/storage access, no network via CSP,
- * terminable on timeout), and the main thread in Node / SSR (where that boundary
- * has no equivalent). The options below only tune the isolated browser run.
+ * Tunes the sandbox execution of `analyseData`, `processData`, `createTracker` and
+ * `clusterIncidents` code. **Where** the code runs is
+ * not configurable, since the environment decides. In the browser, it is a
+ * sandboxed, opaque-origin iframe + Web Worker (no DOM/storage access, no network
+ * via CSP, terminable on timeout). In Node / SSR, where that boundary has no
+ * equivalent, it is the main thread. The options below only tune the isolated browser run.
  *
  * @group Agent Toolkit
  */
 export type CodeExecutionConfig = {
-  /** Wall-clock budget per isolated (browser) run, in ms. Default: 10000. */
+  /** Wall-clock budget per isolated (browser) run, in ms. Defaults to 10000. */
   timeoutMs?: number;
   /**
-   * Optional override of the worker's library source. By default the SDK loads its own
-   * inlined turf/h3 UMD (a separate lazy chunk), so this is rarely needed — supply it only
+   * Optional override of the worker's library source. By default, the SDK loads its own
+   * inlined turf/h3 UMD (a separate lazy chunk), so this is rarely needed. Supply it only
    * to pin a specific build or add libraries. Return UMD/IIFE JavaScript that defines
    * `self.turf` and `self.h3` (string or Promise of one).
    */
@@ -4227,11 +4225,11 @@ export type CodeExecutionConfig = {
 /**
  * Per-call options handed to a tool's `execute`, separate from its parsed input.
  *
- * `signal` is the AI SDK's own `abortSignal` for the tool call — it fires when the model's
+ * `signal` is the AI SDK's own `abortSignal` for the tool call, which fires when the model's
  * turn is cancelled. Forward it to any `@tomtom-org/maps-sdk/services` call the tool makes
- * (as `signal`) so a cancelled turn also cancels its in-flight HTTP requests.
+ * (as `signal`), so a cancelled turn also cancels its in-flight HTTP requests.
  *
- * Do NOT forward it into work that outlives the turn — a monitor's recurring tick, or any
+ * Do NOT forward it into work that outlives the turn, such as a monitor's recurring tick or any
  * deferred job. Those fire after the signal has aborted, and a monitor treats a rejected tick
  * as fatal (it clears its own interval), so a leaked signal kills the monitor rather than
  * cancelling a request.
@@ -4242,14 +4240,14 @@ export type ToolExecuteOptions = {
   signal?: AbortSignal;
 };
 /**
- * A tool definition — the universal format for both built-in and third-party tools.
- * Combines execution (inputSchema + execute) with classifier metadata.
+ * A tool definition, the universal format for both built-in and third-party tools.
+ * It combines execution (inputSchema + execute) with classifier metadata.
  *
  * @typeParam S - The ToolState shape this tool requires. Default: base `ToolState`.
  * @typeParam Scope - Optional per-tool scope shape. When set via `scopeSchema`, the
  *   classifier may emit a value of this shape per turn so the tool's `description`
  *   and `inputSchema` can be rebuilt narrower for that step. Tools without scope
- *   leave this at the default `unknown`; `scopeSchema` is then absent and no rebuild
+ *   leave this at the default `unknown`. `scopeSchema` is then absent and no rebuild
  *   ever runs for the tool.
  *
  * @group Agent Toolkit
@@ -4262,20 +4260,20 @@ export type ToolEntry<S extends ToolState = ToolState, Scope = unknown> = {
   /** Optional Zod schema describing the tool's structured output. */
   outputSchema?: z.ZodType;
   /**
-   * Function that executes the tool. Receives parsed input and the agent's state.
+   * Function that executes the tool. It receives the parsed input and the agent's state.
    *
    * If this calls a `@tomtom-org/maps-sdk/services` function directly, wrap its params with
-   * `withAgentToolkitHeaders` (`tools/shared/agent-headers.ts`) before passing them in — e.g.
+   * `withAgentToolkitHeaders` (`tools/shared/agent-headers.ts`) before passing them in, for example
    * `const requestParams = withAgentToolkitHeaders({ position }); await reverseGeocode(requestParams);`.
-   * This tags the request so TomTom's traffic analytics attribute it to agent-toolkit; an
-   * untagged call is picked up by the guard test in `tools/shared/tests/agent-headers.test.ts`.
+   * This tags the request so TomTom's traffic analytics attribute it to agent-toolkit. The guard
+   * test in `tools/shared/tests/agent-headers.test.ts` picks up an untagged call.
    */
   execute: (input: any, state: S, options?: ToolExecuteOptions) => Promise<any>;
   /** Compact one-liner for the intent classifier prompt. */
   classificationPrompt?: string;
   /** Category tags (e.g. 'location', 'routing'). */
   tags?: string[];
-  /** Usage examples (e.g. 'geocode("Amsterdam")'). */
+  /** Usage examples (e.g. 'geocode("Amsterdam")'), passed on in the metadata a custom classifier receives. */
   examples?: string[];
   /** Natural language prompts (e.g. 'Where is the Louvre?'). */
   examplePrompts?: string[];
@@ -4284,27 +4282,27 @@ export type ToolEntry<S extends ToolState = ToolState, Scope = unknown> = {
   /** Tool names that must run before this one. */
   dependsOn?: string[];
   /**
-   * Keep this tool active on every step regardless of the classifier's selection. Its name is
-   * unioned into the per-turn `activeTools` set, so the model can always reach it. Use sparingly —
+   * Whether this tool stays active on every step regardless of the classifier's selection. Its name is
+   * unioned into the per-turn `activeTools` set, so the model can always reach it. Use it sparingly,
    * for tools that may be needed to set up *any* request (e.g. asking the user to clarify intent).
-   * Has no effect on the fail-open path (when classification is skipped, every tool is active).
+   * It has no effect on the fail-open path (when classification is skipped, every tool is active).
    */
   alwaysActive?: boolean;
   /**
-   * Halt the agent loop on the SAME step that calls this tool, with no trailing step. Use for tools
-   * whose turn must be a single silent tool call (e.g. clarifyIntent rendering a form). Leave unset to
-   * let the model take one more step after the tool returns — e.g. to present the tool's result as text
-   * before the loop stops naturally on a no-tool-call step. A tool that semantically awaits the user
+   * Whether to halt the agent loop on the SAME step that calls this tool, with no trailing step. Use for
+   * tools whose turn must be a single silent tool call (e.g. clarifyIntent rendering a form). Leave unset
+   * to let the model take one more step after the tool returns, for example to present the tool's result
+   * as text before the loop stops naturally on a no-tool-call step. A tool that semantically awaits the user
    * conveys that through its own result (e.g. clarifyIntent's `status: 'awaiting_user_response'`), not
    * this flag.
    */
   endsTurnOnCall?: boolean;
   /**
    * Optional per-tool scope schema. When set, the classifier may emit a
-   * scope value (validated against this schema) and `prepareStep` will
-   * rebuild this tool's `description` + `inputSchema` by re-invoking its
+   * scope value (validated against this schema), and `prepareStep` then
+   * rebuilds this tool's `description` + `inputSchema` by re-invoking its
    * {@link ToolEntryBuilder} with the parsed scope. Tools without a builder
-   * cannot be scoped — `scopeSchema` is only meaningful on builder-produced
+   * cannot be scoped, so `scopeSchema` is only meaningful on builder-produced
    * entries.
    */
   scopeSchema?: z.ZodType<Scope>;
@@ -4323,13 +4321,13 @@ export type ToolEntry<S extends ToolState = ToolState, Scope = unknown> = {
 export type ToolMetadata = {
   /** Tool identifier, derived from the config key. */
   name: string;
-  /** Description of the tool's purpose. Used by the SDK's system prompt. */
+  /** Description of the tool's purpose, used by the SDK's system prompt. */
   description: string;
   /** Compact one-liner for the intent classifier prompt. */
   classificationPrompt?: string;
   /** Category tags used by the help tool for filtering (e.g. 'location', 'routing'). */
   tags?: string[];
-  /** Usage examples (e.g. 'geocode("Amsterdam")'). */
+  /** Usage examples (e.g. 'geocode("Amsterdam")'), for a custom classifier. The help tool does not show them. */
   examples?: string[];
   /** Natural language prompts shown by the help tool (e.g. 'Where is the Louvre?'). */
   examplePrompts?: string[];
@@ -4337,9 +4335,9 @@ export type ToolMetadata = {
   relatedTools?: ToolNameHint[];
   /** Tool names that must run before this one. */
   dependsOn?: ToolNameHint[];
-  /** Keep this tool active on every step regardless of the classifier's selection. */
+  /** Whether this tool stays active on every step regardless of the classifier's selection. */
   alwaysActive?: boolean;
-  /** Halt the agent loop on the step that calls this tool (no trailing step) — e.g. clarifyIntent rendering a form. */
+  /** Whether to halt the agent loop on the step that calls this tool (no trailing step), e.g. clarifyIntent rendering a form. */
   endsTurnOnCall?: boolean;
   /** When set, the classifier may emit `toolScopes[name]` for this tool to narrow per-turn. */
   scopePrompt?: string;
@@ -4363,9 +4361,9 @@ export type ClassifierContext = {
  */
 export type Classifier = (context: ClassifierContext) => Promise<ClassificationResult | null>;
 /**
- * Feature-flag bag for {@link createMapAgent}. Toggles in-flight or
- * opt-in agent-toolkit behaviour. Individual flags vary in stability —
- * some may graduate to stable public options, others are internal-only
+ * Feature-flag bag for {@link createMapAgent}. It toggles in-flight or
+ * opt-in agent-toolkit behaviour. Individual flags vary in stability.
+ * Some may graduate to stable public options, and others are internal-only
  * experiments that can change or disappear without notice. Check each
  * flag's own doc for its current status.
  *
@@ -4385,7 +4383,7 @@ export type FeatureFlags = {
   readonly [flag: string]: never;
 };
 /**
- * Build-time options passed to a {@link ToolEntryBuilder}. Lets each tool
+ * Build-time options passed to a {@link ToolEntryBuilder}. They let each tool
  * tailor its description, schema, or executor to flags or per-turn scope
  * resolved by the classifier.
  *
@@ -4400,8 +4398,8 @@ export type ToolBuildOptions<Scope = unknown> = {
   featureFlags?: FeatureFlags;
   /**
    * Per-turn scope emitted by the classifier (already validated against the
-   * tool's {@link ToolEntry.scopeSchema}). `undefined` at agent-creation time
-   * or when the classifier omits a scope for this tool — builders should
+   * tool's {@link ToolEntry.scopeSchema}). It is `undefined` at agent-creation
+   * time or when the classifier omits a scope for this tool. Builders should
    * treat `undefined` as "produce the full surface".
    */
   scope?: Scope;
@@ -4409,8 +4407,8 @@ export type ToolBuildOptions<Scope = unknown> = {
    * Subset of {@link EntryDataKind} the agent is configured to expose, derived
    * from `createMapAgent`'s `dataEntries` option. Builders for `analyseData`
    * and `processData` use this to narrow their static (unscoped) input surface
-   * to the agent's enabled kinds. `undefined` means "no agent-level filtering —
-   * every kind stays available".
+   * to the agent's enabled kinds. `undefined` means no agent-level filtering, so
+   * every kind stays available.
    */
   enabledDataKinds?: readonly EntryDataKind[];
 };
@@ -4430,8 +4428,8 @@ export type ToolEntryBuilder<S extends ToolState = ToolState, Scope = unknown> =
 /**
  * A registered tool definition: either a static {@link ToolEntry} or a
  * {@link ToolEntryBuilder} that builds one from {@link ToolBuildOptions} at
- * agent-creation time. Used wherever the tool registry, resolver, and
- * setup pipeline accept either form interchangeably.
+ * agent-creation time. The tool registry, resolver and setup pipeline
+ * accept either form interchangeably.
  *
  * @typeParam S - The ToolState shape this tool requires. Default: base `ToolState`.
  * @typeParam Scope - Optional per-tool scope shape (only relevant for builder
@@ -4450,7 +4448,7 @@ export type ToolExecutionInfo = {
   toolName: string;
   /** Wall-clock duration of `execute`, in milliseconds (includes any network/IO). */
   durationMs: number;
-  /** True if the tool threw or returned the standardized `{ error: string }` shape. */
+  /** Whether the tool threw or returned the standardized `{ error: string }` shape. */
   isError: boolean;
   /** Error message when `isError` is true (the thrown message or the returned `error`). */
   errorMessage?: string;
@@ -4492,19 +4490,19 @@ export type MapAgentOptions<CS extends ToolState = ToolState> = {
    * the exported `SYSTEM_PROMPT_SECTIONS` map and override with a derived value
    * (e.g. ``responseFormatting: `${SYSTEM_PROMPT_SECTIONS.responseFormatting}\n- Answer in Spanish.` ``).
    *
-   * A full string ignores `systemPromptPrefix` and `systemPromptSuffix`;
-   * section overrides still honor both.
+   * A full string ignores `systemPromptPrefix` and `systemPromptSuffix`.
+   * Section overrides still honour both.
    */
   systemPrompt?: string | SystemPromptSectionOverrides;
   /**
    * Text prepended above the whole prompt as a preamble, separated by a blank
-   * line and carrying no heading. Applied on top of the base prompt or section
-   * overrides; ignored only when `systemPrompt` is a full replacement string.
+   * line and carrying no heading. It applies on top of the base prompt or section
+   * overrides, unless `systemPrompt` is a full replacement string.
    */
   systemPromptPrefix?: string;
   /**
    * Additional text appended under an `ADDITIONAL INSTRUCTIONS` heading.
-   * Applied on top of the base prompt or section overrides; ignored only when
+   * It applies on top of the base prompt or section overrides, unless
    * `systemPrompt` is a full replacement string.
    */
   systemPromptSuffix?: string;
@@ -4540,19 +4538,19 @@ export type MapAgentOptions<CS extends ToolState = ToolState> = {
   tools?: { [K in ToolNameHint]?: ToolDefinition<CS> | false | undefined; };
   /**
    * Custom state slices merged alongside built-in state.
-   * Only custom slices need to be provided — built-in slices are created automatically.
-   * Accessible in custom tool `execute` via the state parameter.
+   * Only custom slices need to be provided, since built-in slices are created automatically.
+   * Custom tools read them in `execute` via the state parameter.
    */
   state?: Omit<CS, keyof ToolState>;
   /**
    * Per-kind data-entry configuration. Each {@link DataEntryKind} accepts
    * `{ enabled?, entryMode? }`. Setting `enabled: false` removes the kind from the
-   * agent's tool surface entirely — it disappears from `analyseData` / `processData`
+   * agent's tool surface entirely. It disappears from `analyseData` / `processData`
    * scope and input fields, and its slice-specific display / fetch tools
-   * ({@link TOOLS_BY_DATA_ENTRY_KIND}) are dropped from the registry; `recallState` stays.
-   * `entryMode` is applied to the underlying slice right after the agent state is built — before any tool runs.
+   * ({@link TOOLS_BY_DATA_ENTRY_KIND}) are dropped from the registry. `recallState` stays.
+   * `entryMode` is applied to the underlying slice right after the agent state is built, before any tool runs.
    *
-   * Keys are LLM-facing kind names (`routes`, `incidents`) — not slice names
+   * Keys are LLM-facing kind names (`routes`, `incidents`), not slice names
    * (`routing`, `trafficIncidents`). The slice mapping is internal.
    *
    * @example
@@ -4588,17 +4586,17 @@ export type MapAgentOptions<CS extends ToolState = ToolState> = {
    */
   byod?: {
     /**
-     * Authorize each `addByodSource` URL before it is fetched — see
-     * {@link ByodSourceUrlValidator}. Return `{ valid: true }` to allow or
-     * `{ valid: false, reason }` to block (sync or async). Runs in addition
+     * Authorises each `addByodSource` URL before it is fetched (see
+     * {@link ByodSourceUrlValidator}). Return `{ valid: true }` to allow or
+     * `{ valid: false, reason }` to block (sync or async). It runs in addition
      * to the built-in scheme / size / timeout policy.
      */
     validateSourceUrl?: ByodSourceUrlValidator;
   };
   /**
-   * Tunes `analyseData` / `processData` sandbox execution — see {@link CodeExecutionConfig}.
-   * Where the code runs is chosen by environment (off-thread iframe-worker in the browser,
-   * main thread in Node/SSR), not configured here; these options only adjust the isolated
+   * Tunes the data tools' sandbox execution (see {@link CodeExecutionConfig}).
+   * The environment, not this option, chooses where the code runs (off-thread iframe-worker
+   * in the browser, main thread in Node/SSR). These options only adjust the isolated
    * browser run (`timeoutMs`, `loadWorkerLibrarySource`).
    *
    * @experimental
@@ -4632,11 +4630,11 @@ export type MapAgentOptions<CS extends ToolState = ToolState> = {
    * Defaults to `true`. Set to `false` for providers that don't support structured tool outputs.
    */
   outputSchemas?: boolean;
-  /** Max multi-step tool loop iterations. Default: 10. */
+  /** Maximum multi-step tool loop iterations. Defaults to 10. */
   maxSteps?: number;
   /**
    * Opt into in-flight or experimental agent-toolkit behaviour. Stability
-   * varies per flag — see {@link FeatureFlags} and each flag's own doc.
+   * varies per flag (see {@link FeatureFlags} and each flag's own doc).
    *
    * @experimental
    */
@@ -4645,8 +4643,8 @@ export type MapAgentOptions<CS extends ToolState = ToolState> = {
    * Provider-specific options forwarded to the AI SDK on every step. Keyed by
    * provider id (`openai`, `azure`, `anthropic`, ...).
    *
-   * Use this to enable reasoning summaries for gpt-5.x via the Responses API
-   * — without `reasoningSummary` the model thinks but returns no reasoning text:
+   * Use this to enable reasoning summaries for gpt-5.x via the Responses API.
+   * Without `reasoningSummary`, the model thinks but returns no reasoning text.
    *
    * @example
    * ```typescript
@@ -4661,7 +4659,7 @@ export type MapAgentOptions<CS extends ToolState = ToolState> = {
   providerOptions?: ProviderOptions;
   /**
    * Per-step `providerOptions` override. Called once per step with the
-   * classifier-narrowed active toolset; the returned object is merged on top
+   * classifier-narrowed active toolset. The returned object is merged on top
    * of `providerOptions` for that step. Use it to bump reasoning effort on
    * turns that include a code-execution tool without paying the cost on
    * simple fetch/toggle turns.
@@ -4680,15 +4678,15 @@ export type MapAgentOptions<CS extends ToolState = ToolState> = {
   }) => ProviderOptions | undefined;
 };
 /**
- * The return type of createMapAgent().
- * A real ToolLoopAgent instance with state access and cleanup.
+ * The return type of createMapAgent(), a real ToolLoopAgent instance
+ * with state access and cleanup.
  *
  * @group Agent Toolkit
  */
 export type MapAgentInstance<CS extends ToolState = ToolState> = ToolLoopAgent & {
   /** Live agent state (built-in + custom slices). */
   readonly state: CS;
-  /** Tear down: resets all state slices that have a reset() method. */
+  /** Tears down by resetting all state slices that have a reset() method. */
   destroy(): void;
 };
 //#endregion
@@ -4696,13 +4694,12 @@ export type MapAgentInstance<CS extends ToolState = ToolState> = ToolLoopAgent &
 /**
  * Creates a conversational agent toolkit that gives an LLM control over a TomTom map.
  *
- * Returns a ToolLoopAgent instance (compatible with DirectChatTransport) with
+ * It returns a ToolLoopAgent instance (compatible with DirectChatTransport) with
  * `state` and `destroy` attached. Classification runs transparently inside
- * `prepareStep` — no wrapper type needed.
+ * `prepareStep`, so you need no wrapper type.
  *
- * @param map - The TomTomMap instance to control
- * @param options - Agent configuration options
- * @returns A ToolLoopAgent with state access and cleanup
+ * @param map - The map to control.
+ * @returns A ToolLoopAgent with state access and cleanup.
  *
  * @example Basic usage
  * ```typescript
@@ -4739,11 +4736,11 @@ export declare const createMapAgent: <CS extends ToolState = ToolState>(map: Tom
  *
  * - `ToolEntry` (or builder) values add or replace tools in `defaults`.
  * - `false` values remove tools from `defaults`.
- * - Returns a new object — `defaults` is never mutated.
+ * - It returns a new object and never mutates `defaults`.
  *
  * Default entries may be {@link ToolEntryBuilder builders} that produce
  * their {@link ToolEntry} from build-time options. Builders pass through
- * untouched and are materialized later by `setupTools`.
+ * untouched, and `setupTools` materializes them later.
  *
  * @param defaults - Base tool record (typically DEFAULT_TOOLS or empty).
  * @param overrides - User-provided additions, replacements, and exclusions.
@@ -4761,7 +4758,7 @@ export declare const questionSchema: z.ZodObject<{
   options: z.ZodArray<z.ZodString>;
   multiSelect: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
-/** One clarification question — the unit a host UI renders. */
+/** One clarification question, the unit a host UI renders. */
 type ClarifyIntentQuestion = z.infer<typeof questionSchema>;
 /**
  * Input schema for {@link executeClarifyIntent}.
@@ -4778,8 +4775,8 @@ export declare const clarifyIntentSchema: z.ZodObject<{
 /**
  * Output schema for {@link executeClarifyIntent}. The tool resolves immediately, echoing back the
  * `intro` + `questions` (so a host can render the whole form) plus an `awaiting_user_response` status.
- * No "stop and wait" directive is echoed here: the description-level usage contract already carries it
- * (CLARIFY_FORM_PROMPT and CLARIFY_PROSE_PROMPT both tell the agent to STOP and wait), so repeating it
+ * No "stop and wait" directive is echoed, because the description-level usage contract already carries
+ * it. CLARIFY_FORM_PROMPT and CLARIFY_PROSE_PROMPT both tell the agent to STOP and wait, so repeating it
  * in the result would be redundant.
  */
 export declare const clarifyIntentOutputSchema: z.ZodObject<{
@@ -4794,7 +4791,7 @@ export declare const clarifyIntentOutputSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** Usage contract appended to the description when the host renders the form: silent turn, questions not restated in prose. */
 export declare const CLARIFY_FORM_PROMPT: string;
-/** Usage contract appended to the description when there is no form: the model also writes the questions as prose so any UI shows them. */
+/** Usage contract appended to the description when there is no form. The model also writes the questions as prose so any UI shows them. */
 export declare const CLARIFY_PROSE_PROMPT: string;
 /** Per-call overrides accepted by {@link createClarifyIntentTool}. */
 type ClarifyIntentToolOptions = {
@@ -4807,19 +4804,19 @@ type ClarifyIntentToolOptions = {
   /** Replace the default natural-language example prompts. */
   examplePrompts?: string[];
   /**
-   * Keep the tool active on every step regardless of the classifier (so the agent can always ask
-   * to clarify, even mid-task). Defaults to `true`; set `false` to leave activation to the classifier.
+   * Whether the tool stays active on every step regardless of the classifier, so the agent can always
+   * ask to clarify, even mid-task. Defaults to `true`. `false` leaves activation to the classifier.
    */
   alwaysActive?: boolean;
   /**
-   * Does your host render the clarifyIntent form? `true` → silent form contract; `false` (default) →
-   * the agent narrates the questions as prose so they reach a form-less UI.
+   * Whether your host renders the clarifyIntent form. `true` uses the silent form contract. With
+   * `false` (default), the agent narrates the questions as prose so they reach a form-less UI.
    */
   rendersForm?: boolean;
 };
 /**
- * Build a clarifyIntent {@link ToolEntry}, optionally overriding its description and examples for a
- * specific domain. The schema and `execute` are fixed; only the classifier-facing metadata is
+ * Builds a clarifyIntent {@link ToolEntry}, optionally overriding its description and examples for a
+ * specific domain. The schema and `execute` are fixed. Only the classifier-facing metadata is
  * customizable. Pass the result to `createMapAgent`'s `tools` option to replace the built-in default:
  *
  * ```typescript
@@ -4839,14 +4836,14 @@ export declare const createClarifyIntentTool: (options?: ClarifyIntentToolOption
 //#region src/tools/utilities/get-current-location.d.ts
 type GetCurrentLocationToolOptions = {
   /**
-   * Send the exact position, the device's accuracy and the fix's timestamp to the model, from a
-   * fresh high-accuracy fix. Defaults to `false`: the position is rounded to 3 decimals (about
+   * Whether the model gets the exact position, the device's accuracy and the fix's timestamp, from a
+   * fresh high-accuracy fix. By default (`false`), the position is rounded to 3 decimals (about
    * 100 m) from a fix up to a minute old, with no timestamp.
    */
   fullPrecision?: boolean;
 };
 /**
- * Build a getCurrentLocation {@link ToolEntry}. Pass the result to `createMapAgent`'s `tools` option
+ * Builds a getCurrentLocation {@link ToolEntry}. Pass the result to `createMapAgent`'s `tools` option
  * to replace the built-in default, for example to send the exact position:
  *
  * ```typescript