query_data

The query_data tool queries a feature layer or table for records or aggregations. It must always be called after describe_layer, which provides the field metadata required to construct a valid query.

Tool Name

query_data

Tool Alias

Query Data

Objective

Query a feature layer or table inside a feature service or map service for records or aggregations using SQL WHERE clauses, spatial filters, pagination, sorting, and statistical aggregations.

Description

query_data provides an interface for querying a feature layer or table for records or aggregations, after the layer's metadata has been retrieved via describe_layer.

Important: call describe_layer first

query_data must only be used after describe_layer has been invoked on the target layer. The layer reference may come from a content search, a direct URL, or other context. Calling query_data before describe_layer is considered a failed run. Use the metadata returned by describe_layer to build a valid SQL-92 WHERE clause and to identify legal field names—otherwise hallucinated field names will cause empty or failed queries.

Default behavior

  • The default response returns all attributes but not the geometry for matching records, capped at the top 100 matching records. This default keeps responses small and avoids overwhelming clients.
  • Both the page size and the geometry behavior can be overridden via the inputs below—for example, when paginating, or when the client explicitly asks for geometries.
  • Clients can paginate to retrieve the full result set, but be cautious: large result sets can be slow to process, and a geoprocessing tool may be a better fit for very large queries.
  • When no aggregations are provided, the tool performs an additional total-count query so it can tell the client whether more records are available beyond the first page.

Inputs

The tool exposes 13 input parameters. Required parameters are marked; everything else is optional.

  1. Layer URL (required) — the URL of the layer or table to query.
  2. where — a SQL WHERE clause to filter results by attribute. Use only the field names returned by describe_layer to avoid hallucinated columns.
  3. geometry — a JSON-formatted Esri geometry string used to filter results spatially. Pass it as a JSON string representing a valid Esri JSON geometry object. Keep the geometry as simple as possible and derive it directly from a tool call or other conversational context. The geometry's spatial reference must be included in the JSON string. Example schemas:
  4. Multipoint: {"hasM": <bool>, "hasZ": <bool>, "points": [[x1,y1,z1,m1], …, [xn,yn,zn,mn]], "ids": [[id1, id2, …, idn]], "spatialReference": {…}}
  5. Polygon: {"hasZ": <bool>, "hasM": <bool>, "rings": [[[x11,y11,z11,m11], …, [x1N,y1N,z1N,m1N]], …, [[xk1,yk1,zk1,mk1], …, [xkM,ykM,zkM,mkM]]], "ids": [[id11, …, id1N], …, [idk1, …, idkM]], "spatialReference": {…}}
  6. geometryType — required when a geometry is supplied; defaults to esriGeometryEnvelope if omitted while a geometry is provided. Valid values: esriGeometryPoint, esriGeometryMultipoint, esriGeometryPolyline, esriGeometryPolygon, esriGeometryEnvelope.
  7. spatialRel — the spatial relationship to apply between the input geometry and the layer features. Defaults to esriSpatialRelIntersects. Valid values:
  8. esriSpatialRelIntersects — the default; features sharing any part of their geometry with the input geometry. Use for intersects or distance-from queries.
  9. esriSpatialRelContains — features fully contained within the input geometry.
  10. esriSpatialRelWithin — features that fully contain the input geometry.
  11. esriSpatialRelCrosses — features that cross the input geometry.
  12. esriSpatialRelOverlaps — features that overlap the input geometry.
  13. esriSpatialRelTouches — features that touch the boundary of the input geometry.
  14. esriSpatialRelEnvelopeIntersects — features whose envelope intersects the input envelope. Cheaper than a full intersects.
  15. esriSpatialRelIndexIntersects — features whose envelope intersects the input geometry's index entry. Cheaper still and approximate.
  16. Buffer distance — a distance to buffer the supplied geometry by before applying the spatial filter.
  17. Buffer distance units — required when a buffer distance is specified. Valid values: esriSRUnit_Foot, esriSRUnit_Meter, esriSRUnit_Kilometer, esriSRUnit_StatuteMile, esriSRUnit_NauticalMile, esriSRUnit_USNauticalMile.
  18. Statistical aggregations — a list of aggregations for advanced analysis of the layer's data. Provide them only when explicitly requested, or when the layer's describe_layer output makes it obvious the client is asking for statistics (counts, min, max, etc.). Each statistic specifies:
  19. A statistic type — one of count, min, max, avg, sum, stddev, var.
  20. A field to compute on—must be a field returned by describe_layer.

The output attribute name for each statistic is auto-generated as <statistic_type>_<statistic_field> (for example, avg_pop for the average of pop). Use this naming convention when reading the statistics array of the response and when referencing a statistic from orderByFields. 9. Group-by field — a field used to group statistical results. Do not use unless statistics are requested. Must be a field returned by describe_layer. 10. Order-by fields — a list of fields to sort by. Each entry specifies a sort order plus either a field name (from describe_layer) or a statistic name in the <statistic_type>_<statistic_field> form (most useful when a group-by is specified). 11. Page size — pagination size for non-aggregation queries. Defaults to 100, maximum 1000. Be cautious about increasing this—larger pages can cause client-side errors due to very large tool responses. 12. Record offset — pagination offset, used together with page size to retrieve later pages. Only works when the layer supports pagination. 13. Return geometry flag — whether to include geometries on matching features. Defaults to false to keep responses lightweight.

When to use

  • The client wants to query a specific layer or table within a feature service or map service, and the agent has already called describe_layer on it.
  • The client only needs the first 1000–2000 results (a few pages), or is asking exploratory questions that involve filtering.

When not to use

  • The request requires complex geoprocessing beyond what a simple feature-layer query can provide. Use a geoprocessing tool instead.
  • The agent has not yet called describe_layer on the target layer. Always call describe_layer first.

Schema

The full JSON Schema definitions for the input parameters accepted by query_data and the output payload it returns are provided as separate files alongside this document.

Input schema

The input schema describes the required layerOrTableUrl and every optional parameter—the where clause, the spatial filter (geometry, geometryType, spatialRelationship, bufferDistance, bufferUnits), the aggregation block (statistics, group-by field, orderByFields), pagination (pageSize, recordOffset), and the returnGeometry flag.

Download or view QueryDataToolInputSchema.json

Output schema

The output schema describes the response object: geometryType and spatialReference for the layer, a resultRecords array of returned records (each with attributes and—when requested—geometry), the totalMatchingRecords count for non-aggregation queries, and a statistics array for aggregation queries (each statistic's attribute name follows the <statistic_type>_<statistic_field> convention).

Download or view QueryDataToolOutputSchema.json

Sample prompts to test the tool

Send any of the prompts below to your MCP-compatible AI client to verify that query_data is working correctly. Each prompt targets a different combination of the tool's inputs—attribute filters, sorting, pagination, statistics, group-by, geometry filters, buffer distances, and spatial-relationship modes.

Basic attribute filter with sorting and pagination

  • Show me the first 10 counties in California with a population greater than 500,000, sorted by population in descending order. Then show me the next page of results.

Statistics with group-by and ordered results

  • For each road classification type in the San Francisco Streets layer, what is the average travel speed, minimum speed, maximum speed, and total count of street segments? Sort by average speed descending.

Spatial filter using a polygon geometry

  • Find all hospitals and fire stations in San Francisco that fall within the bounding box of downtown SF (roughly between -122.42, 37.77 and -122.39, 37.80). Return their geometries too.

Point geometry with buffer distance

  • Which parks in San Francisco are within 1 kilometer of coordinates longitude -122.4194, latitude 37.7749 (City Hall)? Return their names and geometries.

Global statistics without group-by

  • Across all US cities in the USA map service with a population over 100,000, what is the total population sum, average population, and the standard deviation of population values?

Spatial relationship — within with geometry plus attribute filter

  • Which California cities are completely within the bounding box of Southern California (longitude -118.9 to -116.9, latitude 32.5 to 34.5) and have a population over 50,000? Sort them by name alphabetically.

Statistics + group-by + where + buffer (full coverage)

  • Within 5 miles of San Francisco City Hall (longitude -122.4194, latitude 37.7749), group the street segments by road classification and give me the count, average speed, and max speed for each group—only include segments with a travel speed greater than 0. Order by count descending.