describe_layer

The describe_layer tool returns the metadata of a single layer or table inside a feature service or map service. AI agents typically call it as a preparatory step before running a query_data operation, so that they know which fields exist, what types those fields use, and what realistic values look like.

Tool Name

describe_layer

Tool Alias

Describe Layer

Objective

Inspect the metadata of a specific layer or table inside a feature service or map service, including field definitions, semantic field classifiers, and example field values.

Description

describe_layer inspects metadata about a specific layer or table inside a feature service or map service. The response combines structural metadata with optional example values for each field, giving an agent everything it needs to construct a valid follow-up query.

For each field, the response includes:

  • Field name
  • Esri field type — for example, esriFieldTypeString, esriFieldTypeDate, or esriFieldTypeOID
  • Alias
  • Description
  • Sample values drawn from real records in the layer
  • fieldValueType — when available, a semantic classifier that hints at the field's intent (for example, nameOrTitle, countOrAmount, or dateAndTime)

The response also returns the layer's extent and spatial reference.

describe_layer is most useful when a client needs more information about a specific layer or table within a feature or map service—particularly as a required precursor before constructing WHERE clauses or selecting fields with query_data. Calling query_data without first inspecting the layer's fields is the single most common cause of failed or empty queries.

Inputs

describe_layer takes two required inputs:

  • serviceUrl — The URL of the service that contains the layer—not the URL of the layer itself.
  • layerId — The numeric ID of the layer or table within the service.

The layerId may come from prior conversation context, from a direct request that includes a layer URL, or from describe_item's service definition. If the layer ID is not readily apparent, call describe_item first on the parent service to enumerate the available layers and tables.

When to use

  • The client wants to inspect metadata about a specific layer or table within a feature service or map service.
  • The agent needs to know the layer's fields and example values before invoking query_data to filter the data.

When not to use

  • The request requires complex geoprocessing that goes beyond what a simple feature-layer query could provide. Use a geoprocessing tool instead.
  • The target item is not a feature or map service layer or table. Use describe_item for general item metadata.

Tip Always pass the service URL, not the layer URL. A common mistake is to copy a URL ending in /0 (the layer endpoint) into serviceUrl. Strip the trailing /<layerId> and pass the layer ID separately in layerId.

Schema

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

Input schema

The input schema describes the required serviceUrl and layerId parameters.

Download or view DescribeLayerToolInputSchema.json

Output schema

The output schema describes the response object, which includes the layer's name, type, description, extent, spatial reference, and a fields array containing per-field metadata and sample values.

Download or view DescribeLayerToolOutputSchema.json

Sample prompts to test the tool

Send any of the prompts below to your MCP-compatible AI client to verify that describe_layer is working correctly. The prompts are grouped to exercise different ways an agent might invoke the tool—from direct schema inspection to implicit field discovery, query setup, ambiguous multi-step requests, and edge cases.

Direct schema inspection

  • Show me the schema for the New Jersey Preserved Farms layer.
  • List all the attributes available on the DE Development Applications service, with sample values.
  • Describe layer 0 of the SampleWorldCities map service.
  • Inspect the California feature service—what columns can I query on?

Implicit (field-discovery) prompts

  • What date range does the New Jersey Preserved Farms dataset cover?
  • Are there any status or category fields I can group SanFrancisco features by?

Query setup

  • List all cities in SampleWorldCities with population over 1 million.

Ambiguous and multi-step

  • Tell me what's interesting about the veg data.
  • I want to make a query against the California service—what should I know first?

Edge cases

  • Compare the schemas of California and SanFrancisco.