preview_map

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

Beyond the readOnly/idempotent annotations, the description discloses projection to EPSG:4326, simplified geometry, capped feature counts, provenance summaries, and verification status. It also states that datasets of record stay on disk, reinforcing the read-only characterization. No contradiction with annotations.

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?

The description is front-loaded with the core purpose and structured into input, rendering behavior, safety, and fallback. Every sentence adds meaningful eligibility or behavioral context, with no redundant or filler content.

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?

The description covers input types, projection, simplification, feature limits, layer-card content, safety, and the no-MCP-Apps fallback. The only meaningful omission is explicit semantics for max_features, which is minor because the parameter has a sensible default and the cap is described behaviorally.

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?

The description thoroughly explains the paths parameter as MapSmith outputs/source datasets, vector or GeoTIFF. However, max_features is never explicitly named; 'capped feature counts sized to fit client limits' only indirectly hints at it, and schema description coverage is 0%, so the agent gets no direct documentation of how to control the cap.

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 action ('Show datasets') and a concrete resource ('interactive in-chat map panel'), and clarifies it is a read-only preview. It effectively distinguishes this tool from transformation/analysis siblings like buffer_layer or run_sql without needing to inspect schemas.

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?

It gives clear eligibility guidance: paths of MapSmith outputs or source datasets, vector or GeoTIFF, plus fallback behavior on clients without MCP Apps support. However, it does not explicitly name sibling alternatives or state when not to use this tool, so it falls short of full routing guidance.

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