describe_layer

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It discloses the operation's nature ('Inspect'), the specific return contents, and a subtle pitfall about layer 0. It does not explicitly state read-only behavior or error handling, but 'Inspect' strongly implies a non-mutating operation and the output list adds meaningful transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Everything is front-loaded: purpose, output detail, input modes, then a crucial caveat. The three sentences are dense but each earns its place, with no filler or repetition of schema text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 3 optional parameters and no output schema, the description does well: it states what is returned, how to address catalog vs non-catalog layers, and a common domain trap. The main gap is a slight ambiguity about whether layer_id can ever be used alone or must always accompany service_path, and what happens if both layer_key and service_path are supplied.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the relationship between parameters: layer_key is the curated path from search_layers, while service_path + layer_id together reach non-catalog layers. This interaction semantics is not captured in the individual parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Inspect one layer's schema', then enumerates exact outputs (fields, geometry type, feature count, capabilities). This clearly distinguishes it from siblings like search_layers (catalog search), query_layer (data access), and list_service_layers (layer enumeration).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives concrete input-mode guidance: use a curated layer_key from search_layers, or use service_path + layer_id for layers not in the catalog. It also warns that many Yerevan layers are NOT layer 0, which prevents a common mistake. It does not explicitly state when to prefer describe_layer over query_layer or count_features, but the 'inspect schema' framing makes that mostly implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.