@arcgis/ai-components 5.2.0-next.71 → 5.2.0-next.73

package/dist/chunks/adapter10.js

@@ -0,0 +1,21 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import t from "zod";
+import { tool as m } from "@langchain/core/tools";
+import { f as i } from "./fetchAgentContext.js";
+async function r(o, e) {
+  return await e.goTo({ zoom: o }), { text: `Successfully zoomed to: ${o}` };
+}
+async function a({ zoom: o }, e) {
+  const { mapView: n } = i(e, ["mapView"]);
+  return await r(o, n);
+}
+const c = t.object({
+  zoom: t.number().min(1).max(20).describe("The zoom level of the view to go to.")
+}), l = m(a, {
+  name: "goToZoom",
+  description: 'Go to the specified zoom level. If input is generic (e.g. "zoom in", then only zoom to the next appropriate level - increase level for zooming in and decrease for zooming out.).',
+  schema: c
+});
+export {
+  l as goToZoomTool
+};

package/dist/chunks/adapter11.js

@@ -0,0 +1,30 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { tool as n } from "@langchain/core/tools";
+import s from "zod";
+import { f as c } from "./fetchService.js";
+const y = (i, r) => {
+  const t = Array.from(i.values()).find(
+    ({ layerItem: e }) => e.title?.toLowerCase().includes(r.toLowerCase())
+  );
+  if (!t) {
+    const e = Array.from(i.values()).map((o) => o.layerItem.title).join(", ");
+    return `Could not find a layer matching "${r}". Available layers: ${e}`;
+  }
+  const l = Array.from(t.fieldRegistry.values()), a = l.map((e) => `- **${e.alias || e.name}** (\`${e.name}\`, ${e.type})${e.description ? `: ${e.description}` : ""}`).join(`
+`);
+  return `**${t.layerItem.title}** has ${l.length} field(s):
+
+${a}`;
+}, d = ({ layerTitle: i }, r) => {
+  const t = c(r, "layersAndFieldsRegistry");
+  return y(t, i);
+}, u = n(d, {
+  name: "listLayerFields",
+  description: "Lists all fields for a given layer by title. Use ONLY when the user explicitly asks to see fields, columns, or attributes of a specific named layer. Do NOT call this tool for general help questions, capability overviews, or layer listing.",
+  schema: s.object({
+    layerTitle: s.string().describe("The title or partial title of the layer to list fields for.")
+  })
+});
+export {
+  u as listLayerFieldsTool
+};

package/dist/chunks/adapter12.js

@@ -0,0 +1,22 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { tool as l } from "@langchain/core/tools";
+import o from "zod";
+import { f } from "./fetchAgentContext.js";
+const i = (a) => {
+  const r = a.map?.allLayers.filter((t) => t.type === "feature");
+  let e = 0;
+  return r?.forEach((t) => {
+    const s = t;
+    s.featureEffect && (s.featureEffect = null, e++);
+  }), e > 0 ? `Cleared filters from ${e} layer(s). View unchanged.` : "No active filters to clear. View unchanged.";
+}, n = async (a, r) => {
+  const { mapView: e } = f(r, ["mapView"]);
+  return i(e);
+}, p = l(n, {
+  name: "clearFilters",
+  description: "Clears all feature effects/filters from the map but does NOT change the current view. Use when user says 'clear filters', 'reset filters', 'remove filters', 'show all features', or wants to remove emphasis without navigating anywhere.",
+  schema: o.object({})
+});
+export {
+  p as clearFiltersTool
+};

package/dist/chunks/adapter13.js

@@ -0,0 +1,22 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { tool as n } from "@langchain/core/tools";
+import i from "zod";
+import { f as l } from "./fetchAgentContext.js";
+const f = async (e) => {
+  e.map?.allLayers.filter((t) => t.type === "feature")?.forEach((t) => {
+    const s = t;
+    s.featureEffect && (s.featureEffect = null);
+  });
+  const o = e.map.initialViewProperties?.viewpoint?.targetGeometry;
+  return o ? (await e.goTo(o), "Cleared all filters and returned to home extent.") : "Cleared all filters. Could not determine home extent.";
+}, p = async (e, r) => {
+  const { mapView: a } = l(r, ["mapView"]);
+  return await f(a);
+}, h = n(p, {
+  name: "resetMap",
+  description: "Clears all feature effects/filters from the map AND zooms to the home extent (initial map view). Use when user says 'reset map', 'reset the map', 'start over', or wants to both clear filters and return to the initial view.",
+  schema: i.object({})
+});
+export {
+  h as resetMapTool
+};

package/dist/chunks/adapter14.js

@@ -0,0 +1,109 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import e from "zod";
+import { tool as h } from "@langchain/core/tools";
+import m from "@arcgis/core/layers/support/FeatureEffect.js";
+import b from "@arcgis/core/layers/support/FeatureFilter.js";
+import { g as y, d } from "./types.js";
+import { f as w } from "./fetchAgentContext.js";
+const g = async (t, o, u, n, r, c) => {
+  const a = t.map?.allLayers.find((i) => i.id === o);
+  if (!a)
+    return { success: !1, error: `Layer '${o}' not found.` };
+  const s = a.createQuery();
+  s.where = u ?? "1=1", n && (s.geometry = n, s.spatialRelationship = "intersects", r && (s.distance = r), c && (s.units = c));
+  try {
+    const { extent: i, count: l } = await a.queryExtent(s);
+    return !i || l === 0 ? {
+      success: !1,
+      error: `No features found for filter (where: ${s.where}${n ? ", spatial filter used" : ""})`
+    } : (await t.goTo(i), { success: !0 });
+  } catch (i) {
+    return {
+      success: !1,
+      error: i instanceof Error ? i.message : String(i)
+    };
+  }
+}, I = async (t, o, u, n, r, c) => {
+  const a = o.map?.allLayers.find(
+    (f) => f.id === t.layerId
+  );
+  if (!a)
+    return `Could not find target layer with ID: ${t.layerId}`;
+  let s;
+  if (r) {
+    const f = await y(r, o);
+    if ("error" in f)
+      return f.error;
+    s = f.geometry;
+  }
+  if (a.featureEffect = null, a.featureEffect = new m({
+    filter: new b({
+      ...t.objectIds?.length ? { objectIds: t.objectIds } : { where: t.where },
+      geometry: s,
+      spatialRelationship: "intersects",
+      distance: r?.distance,
+      units: r?.units
+    }),
+    includedEffect: u,
+    excludedEffect: n
+  }), a.visible = !0, c)
+    return `Applied feature effects to "${a.title ?? t.layerId}" within current map extent.`;
+  const i = t.objectIds?.length ? `${a.objectIdField} IN (${t.objectIds.join(",")})` : t.where, l = await g(
+    o,
+    t.layerId,
+    i,
+    s,
+    r?.distance,
+    r?.units
+  ), p = a.title ?? t.layerId;
+  return l.success ? `Applied feature effects to target layer "${a.title ?? t.layerId}"${r && "layerId" in r ? ` using geometry from layer "${r.layerId}"` : ""}.` : `Applied filter to "${p}" but no features matched. ${l.error}`;
+}, v = async ({
+  targetLayer: t,
+  geometryFilter: o,
+  useCurrentExtent: u,
+  includedEffect: n = "drop-shadow(2px, 2px, 2px, gray)",
+  excludedEffect: r = "grayscale(100%) opacity(60%) blur(2px)"
+}, c) => {
+  const { mapView: a } = w(c, ["mapView"]);
+  return await I(t, a, n, r, o, u);
+}, x = e.object({
+  layerId: e.string().describe("The layerId of the layer containing the geometry by which to filter."),
+  where: e.string().describe("The SQL-92 where clause representing the features from which to filter."),
+  distance: e.number().optional().describe("The buffer distance around the geometry."),
+  units: d.optional().describe("The units for the distance buffer.")
+}), j = e.object({
+  point: e.object({
+    x: e.number().describe("X coordinate (longitude) from navigation result"),
+    y: e.number().describe("Y coordinate (latitude) from navigation result"),
+    spatialReference: e.object({
+      wkid: e.number().describe("Spatial reference WKID (e.g., 4326 for WGS84)")
+    }).optional().describe("Spatial reference. Defaults to map's spatial reference if not provided.")
+  }).describe("Point coordinates from a previous navigation/geocoding result"),
+  distance: e.number().optional().describe("Optional buffer distance around the point."),
+  units: d.optional().describe("The units for the distance buffer.")
+}), E = e.object({
+  targetLayer: e.object({
+    layerId: e.string().describe("The layerId of the layer on which to set a feature effect."),
+    where: e.string().describe("The SQL-92 where clause representing the features to emphasize."),
+    objectIds: e.array(e.number()).optional().describe(
+      "Array of objectIds from a previous query result. Use this instead of a where clause when the query returned objectIds (e.g. top N results). If provided, takes precedence over where clause."
+    )
+  }),
+  geometryFilter: e.union([x, j]).optional().describe("Optional geometry-based filtering parameters for spatial queries."),
+  useCurrentExtent: e.boolean().optional().describe(
+    "Set to true when the previous query used the current map extent as a spatial filter. This ensures the feature effect applies only to features visible in the current view. Default is false."
+  ),
+  includedEffect: e.string().default("drop-shadow(2px, 2px, 2px, gray)").describe(
+    "The effect applied to features that meet the filter requirements. Valid effects include: bloom, blur, brightness, contrast, drop-shadow, grayscale, hue-rotate, invert, opacity, saturate, and sepia. Prefer default unless specified."
+  ),
+  excludedEffect: e.string().default("grayscale(100%) opacity(60%) blur(2px)").describe(
+    "The effect applied to features that do not meet the filter requirements. Valid effects include: bloom, blur, brightness, contrast, drop-shadow, grayscale, hue-rotate, invert, opacity, saturate, and sepia. Prefer default unless specified."
+  )
+}), A = h(v, {
+  name: "setFeatureEffect",
+  description: "Sets a feature effect on a given layer with given filter parameters and feature effects to emphasize certain features that meet a filter requirement. If no feature effect information is provided, then use the default effect provided.",
+  schema: E
+});
+export {
+  A as setFeatureEffectTool
+};

package/dist/chunks/adapter15.js

@@ -0,0 +1,40 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { tool as f } from "@langchain/core/tools";
+import i from "zod";
+import { f as h, g } from "./formatFeatureAttributes.js";
+import { f as y } from "./fetchAgentContext.js";
+const b = (a, e, o) => {
+  const t = a.createQuery();
+  return t.outFields = [e], t.where = o || "1=1", t.num = 1, t;
+}, d = async (a, e, o, t) => {
+  const r = t.map?.allLayers.find((m) => m.id === a), n = b(r, e, o.where), u = (await r.queryFeatures(n)).features[0], c = u ? u.attributes[e] : null, l = h(r, e, c, t.timeZone), s = g(r, e);
+  return {
+    tool: "getAttribute",
+    layerName: r.title ?? a,
+    summary: `${s} = ${l}`,
+    details: {
+      fieldName: e,
+      fieldAlias: s !== e ? s : void 0,
+      value: l,
+      where: o.where
+    }
+  };
+};
+async function p({ layerId: a, fieldName: e, query: o }, t) {
+  const { mapView: r } = y(t, ["mapView"]), n = await d(a, e, o, r);
+  return JSON.stringify(n, null, 2);
+}
+const w = i.object({
+  layerId: i.string().describe("The layerId of the layer containing the field from which to get a value."),
+  fieldName: i.string().describe("The name of the field/attribute from which to get a field value."),
+  query: i.object({
+    where: i.string().describe("The SQL-92 where clause representing the feature from which to get an attribute value.")
+  })
+}), Q = f(p, {
+  name: "getAttribute",
+  description: "Returns an attribute value for a given feature.",
+  schema: w
+});
+export {
+  Q as getAttributeTool
+};

package/dist/chunks/adapter16.js

@@ -0,0 +1,154 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { tool as L } from "@langchain/core/tools";
+import t from "zod";
+import V from "@arcgis/core/smartMapping/statistics/summaryStatistics.js";
+import E from "@arcgis/core/smartMapping/statistics/uniqueValues.js";
+import O from "@arcgis/core/layers/support/FeatureFilter.js";
+import { c as x, m as b } from "./mergeWhereClauses.js";
+import { g as N, i as v, a as C, d as S } from "./types.js";
+import { f as R } from "./fetchAgentContext.js";
+import { f as U } from "./fetchService.js";
+const W = async (h) => {
+  const { targetLayer: r, fieldName: n, statisticType: l, mapView: a, layersAndFieldsRegistry: p, geometryFilter: e } = h, s = a.map?.allLayers.find((i) => i.id === r.layerId);
+  if (!s)
+    throw new Error(`Layer '${r.layerId}' not found.`);
+  const T = await a.whenLayerView(s), o = p.get(r.layerId)?.fieldRegistry.get(n), I = o?.alias;
+  if (!o)
+    throw new Error(`Field '${n}' not found.`);
+  let w, u;
+  if (e) {
+    const i = await N(e, a);
+    if ("error" in i)
+      throw new Error(i.error);
+    if (!i.geometry)
+      throw v(e) ? new Error(`No features found matching: ${e.where}`) : new Error("Failed to create geometry");
+    if (v(e)) {
+      const g = a.map?.allLayers.find((f) => f.id === e.layerId);
+      w = {
+        geometryLayerName: g?.title ?? g?.id,
+        geometryLayerId: e.layerId,
+        geometryWhere: e.where,
+        distance: e.distance,
+        units: e.units,
+        applied: !0
+      };
+    } else C(e) && (w = {
+      point: e.point,
+      distance: e.distance,
+      units: e.units,
+      applied: !0
+    });
+    u = new O({
+      geometry: i.geometry,
+      distance: e.distance,
+      units: e.units,
+      spatialRelationship: "intersects"
+    });
+  }
+  const y = x(T, [n], !1);
+  let d = null, m = null;
+  const F = 10;
+  if (o.type !== "geometry" && o.type !== "oid" && o.type !== "global-id")
+    try {
+      const i = {
+        layer: s,
+        useFeaturesInView: y,
+        view: y ? a : void 0,
+        field: n,
+        sqlWhere: b(s.definitionExpression, r.where),
+        ...u && { filter: u },
+        outStatisticTypes: { include: [l] }
+      };
+      d = await V(i);
+      const g = ["string", "small-integer", "integer"], f = o.domain?.type === "coded-value" ? o.domain : null;
+      (g.includes(o.type) || f) && (m = (await E({
+        layer: s,
+        useFeaturesInView: y,
+        view: y ? a : void 0,
+        field: n,
+        sqlWhere: b(s.definitionExpression, r.where),
+        ...u && { filter: u }
+      })).uniqueValueInfos.sort((c, q) => q.count - c.count).slice(0, F)), m && o.domain?.type === "coded-value" && (m = m.map((c) => ({
+        ...c,
+        value: f ? f.getName(c.value) ?? c.value : c.value
+      })));
+    } catch (i) {
+      console.error("Statistics error:", i);
+    }
+  return {
+    tool: "getStatistics",
+    layerName: s.title ?? r.layerId,
+    summary: `${l} = ${typeof d?.[l] == "number" ? d[l] : "N/A"}`,
+    details: {
+      fieldName: n,
+      fieldAlias: I,
+      statisticType: l,
+      statistic: d?.[l] ?? null,
+      summaryStatistics: d,
+      uniqueValues: m,
+      where: r.where,
+      spatialFilterInfo: w
+    }
+  };
+};
+async function j({
+  targetLayer: h,
+  fieldName: r,
+  statisticType: n,
+  geometryFilter: l
+}, a) {
+  const p = U(a, "layersAndFieldsRegistry"), { mapView: e } = R(a, ["mapView"]), s = await W({
+    targetLayer: h,
+    fieldName: r,
+    statisticType: n,
+    mapView: e,
+    layersAndFieldsRegistry: p,
+    geometryFilter: l
+  });
+  return JSON.stringify(s, null, 2);
+}
+const A = t.object({
+  layerId: t.string().describe("The layerId of the layer containing the geometry by which to filter."),
+  where: t.string().describe("The SQL-92 where clause representing the features from which to filter."),
+  distance: t.number().optional().describe("The buffer distance around the geometry."),
+  units: S.optional().describe("The units for the distance buffer.")
+}), G = t.object({
+  point: t.object({
+    x: t.number().describe("X coordinate (longitude) from navigation result"),
+    y: t.number().describe("Y coordinate (latitude) from navigation result"),
+    spatialReference: t.object({
+      wkid: t.number().describe("Spatial reference WKID (e.g., 4326 for WGS84)")
+    }).optional().describe("Spatial reference. Defaults to map's spatial reference if not provided.")
+  }).describe("Point coordinates from a previous navigation/geocoding result"),
+  distance: t.number().optional().describe("Optional buffer distance around the point."),
+  units: S.optional().describe("The units for the distance buffer.")
+}), D = t.object({
+  targetLayer: t.object({
+    layerId: t.string().describe("The layerId of the layer containing the field from which to get a value."),
+    where: t.string().describe("The SQL-92 where clause representing the feature from which to get an attribute value.")
+  }),
+  geometryFilter: t.union([A, G]).optional().describe(
+    "Geometry filter for spatial queries. Use 'point' option with x/y coordinates from navigation results to find features at that location (point-in-polygon). Use 'layerId/where' option to filter by features from another layer."
+  ),
+  fieldName: t.string().describe("The name of the field for which to get statistics. STRICTLY DO NOT use OBJECTID. Use any other field"),
+  statisticType: t.enum(["avg", "max", "median", "min", "stddev", "sum", "variance", "nullcount", "count"]).describe("The statistic type to calculate.")
+}), M = L(j, {
+  name: "getStatistics",
+  description: `Computes a single aggregate statistic (max, min, avg, sum, median, stddev, variance) for a numeric field across matching features. Also returns frequency analysis for categorical fields.
+
+USE THIS TOOL FOR:
+- "What is the average/maximum/minimum/total [field]?" — aggregate computations
+- "Most common/frequent value of [field]?" — frequency analysis
+- Questions requiring a mathematical aggregation across many features
+
+DO NOT USE FOR:
+- "How many features match X?" — use queryFeatures instead (it returns totalCount)
+- "Show / list / find features" — use queryFeatures instead
+- Simple counts of features matching a condition — use queryFeatures instead
+
+Only call this tool when the answer requires computing an aggregate (avg, max, min, sum, median, stddev) over a field's values, not just counting or listing features.`,
+  schema: D
+});
+export {
+  M as getStatisticsTool
+};

package/dist/chunks/adapter17.js

@@ -0,0 +1,141 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { tool as T } from "@langchain/core/tools";
+import e from "zod";
+import S from "@arcgis/core/rest/support/TopFeaturesQuery.js";
+import B from "@arcgis/core/rest/support/TopFilter.js";
+import { m as C, c as v } from "./mergeWhereClauses.js";
+import { a as I } from "./formatFeatureAttributes.js";
+import { g as q, d as y } from "./types.js";
+import { f as N } from "./fetchAgentContext.js";
+const k = (i) => i.flatMap((t) => t.split(",")).map((t) => t.trim()).map((t) => t.split(/\s+/u)[0]?.replace(/^"|"$/gu, "")).filter((t) => !!t), x = async (i, t, a, s, l) => {
+  const n = a.map?.allLayers.find((o) => o.id === i.layerId), d = await a.whenLayerView(n), c = n.title ?? i.layerId;
+  let u;
+  if (s) {
+    const o = await q(s, a);
+    if ("error" in o)
+      return {
+        tool: "getTopFeatures",
+        layerName: c,
+        summary: "Geometry lookup failed",
+        details: { error: o.error }
+      };
+    if (!o.geometry)
+      return {
+        tool: "getTopFeatures",
+        layerName: c,
+        summary: "No features found for geometry filter",
+        details: {
+          error: `No features found matching: ${"where" in s ? s.where : "unknown criteria"}`
+        }
+      };
+    u = o.geometry;
+  } else l && (u = a.extent.clone());
+  const h = t.groupByFields && t.groupByFields.length > 0, f = n.objectIdField, p = i.outFields.includes("*") ? ["*"] : [.../* @__PURE__ */ new Set([...i.outFields, f])];
+  try {
+    let o;
+    if (h) {
+      const r = new S({
+        where: i.where || "1=1",
+        outFields: p,
+        orderByFields: i.orderByFields,
+        geometry: u,
+        spatialRelationship: u ? "intersects" : void 0,
+        distance: s?.distance,
+        units: s?.units,
+        topFilter: new B({
+          topCount: t.topCount,
+          groupByFields: t.groupByFields,
+          orderByFields: t.orderByFields
+        })
+      });
+      o = await n.queryTopFeatures(r);
+    } else {
+      const r = n.createQuery();
+      r.where = C(n.definitionExpression, i.where || "1=1"), r.outFields = p.length ? p : ["*"], r.orderByFields = t.orderByFields, r.returnGeometry = !1, r.num = t.topCount, u && (r.geometry = u, r.spatialRelationship = "intersects"), s?.distance && (r.distance = s.distance), s?.units && (r.units = s.units), r.outSpatialReference = a.spatialReference;
+      const m = [
+        .../* @__PURE__ */ new Set([...i.outFields, ...k(t.orderByFields)])
+      ], w = v(d, m, l ?? !1);
+      try {
+        o = w ? await d.queryFeatures(r) : await n.queryFeatures(r);
+      } catch (F) {
+        console.warn("Client-side query failed, falling back to server:", F), o = await n.queryFeatures(r);
+      }
+    }
+    const g = o.features.map((r) => r.attributes[f]), { attributes: b } = I(n, o, a.timeZone);
+    return {
+      tool: "getTopFeatures",
+      layerName: c,
+      summary: `Top ${t.topCount} features extracted`,
+      details: {
+        topCount: t.topCount,
+        attributes: b,
+        objectIds: g,
+        objectIdField: f,
+        where: i.where,
+        orderByFields: t.orderByFields,
+        ...h && { groupByFields: t.groupByFields }
+      }
+    };
+  } catch (o) {
+    return {
+      tool: "getTopFeatures",
+      layerName: c,
+      summary: "Query failed",
+      details: { error: o instanceof Error ? o.message : String(o) }
+    };
+  }
+}, j = async ({
+  targetLayer: i,
+  topFilter: t,
+  geometryFilter: a,
+  useCurrentExtent: s
+}, l) => {
+  const { mapView: n } = N(l, ["mapView"]), d = await x(i, t, n, a, s);
+  return JSON.stringify(d, null, 2);
+}, G = e.object({
+  layerId: e.string().describe("The layerId of the layer containing the geometry by which to filter."),
+  where: e.string().describe("The SQL-92 where clause representing the features from which to filter."),
+  distance: e.number().optional().describe("The buffer distance around the geometry."),
+  units: y.optional().describe("The units for the distance buffer.")
+}), R = e.object({
+  point: e.object({
+    x: e.number().describe("X coordinate (longitude) from navigation result"),
+    y: e.number().describe("Y coordinate (latitude) from navigation result"),
+    spatialReference: e.object({
+      wkid: e.number().describe("Spatial reference WKID (e.g., 4326 for WGS84)")
+    }).optional().describe("Spatial reference. Defaults to map's spatial reference if not provided.")
+  }).describe("Point coordinates from a previous navigation/geocoding result"),
+  distance: e.number().optional().describe("Optional buffer distance around the point."),
+  units: y.optional().describe("The units for the distance buffer.")
+}), Q = e.object({
+  targetLayer: e.object({
+    layerId: e.string().describe("The layerId of the layer containing the field from which to get a value."),
+    where: e.string().describe("The SQL-92 where clause representing the feature from which to get an attribute value."),
+    orderByFields: e.array(e.string().describe("The field(s) and order for which to sort the resulting features.")),
+    outFields: e.array(
+      e.string().describe(
+        'The fields to include in the output that will be presented to the user. This should include identifying information about the resulting features, like a name or id, along with the values desired in the output. If unsure, choose all fields ("*").'
+      ).default("*")
+    )
+  }),
+  geometryFilter: e.union([G, R]).optional().describe(
+    "Geometry filter for spatial queries. Use 'point' option with x/y coordinates from navigation results to find features at that location (point-in-polygon). Use 'layerId/where' option to filter by features from another layer."
+  ),
+  topFilter: e.object({
+    topCount: e.number().describe("Number of top features to return per group."),
+    orderByFields: e.array(
+      e.string().describe("Field(s) to rank by with ASC/DESC. Must be existing field names, not aggregate functions.")
+    ),
+    groupByFields: e.array(e.string().describe("Field(s) to group results by. Returns top N per group."))
+  }).required(),
+  useCurrentExtent: e.boolean().optional().describe(
+    "Set to true ONLY when user explicitly asks about features 'in my view', 'on my map', 'I am looking at'. Default is false (queries entire layer)."
+  )
+}), z = T(j, {
+  name: "getTopFeatures",
+  description: 'Returns top N features ranked by an existing field value. Use for "highest", "lowest", "top N" questions where ranking is based on a field that already exists in the data (e.g., population, value, date, depth). orderByFields must be actual field names with ASC/DESC. Do NOT use aggregate functions like COUNT(), SUM(), AVG() - those require getStatistics.',
+  schema: Q
+});
+export {
+  z as getTopFeaturesTool
+};