elevation-mcp-server

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

Goes well beyond the readOnly/idempotent annotations by disclosing model limitations (buildings and vegetation not modeled, a ridge narrower than the sample spacing can be missed), the three-valued verdict, and the sea-floor/negative-elevation handling rules for Mapzen vs USGS 3DEP. This is exactly the behavioral context an agent needs before trusting the result.

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?

Front-loads what the tool does and what it returns before dropping into edge cases and caveats. The text is dense and lengthy, but nearly every sentence carries distinct operational information; only the return-value recitation is mildly redundant given the output schema exists.

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 9-parameter, nested-object, enums-bearing tool, the description covers sampling caveats, source-specific edge cases, water handling, and the sibling escape hatch. With an output schema present, it does not need to enumerate return fields, and its coverage of gotchas is complete enough to call the tool correctly.

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 coverage is 100%, so the baseline is 3, but the description adds genuine interaction semantics the schema alone does not convey (frequency_mhz should be paired with earth_model radio; water_surface_m replaces the default Mapzen-only lift; the 60% free-space bar). It largely restates rather than extends the earth_model coefficients, keeping it short of a 5.

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?

States a specific verb and resource ('check whether terrain blocks the straight sightline between an observer and a target'), including the height/curvature/refraction scope. It explicitly distinguishes itself from the sibling elevation_get_profile and its output vocabulary (clear/blocked/indeterminate) sets it apart from the other elevation tools.

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?

Gives explicit conditional usage for optional parameters ('With frequency_mhz, it also reports... pair it with earth_model radio', 'Set it where the line crosses water') and routes the agent to elevation_get_profile when the terrain between points is wanted. It lacks an explicit when-not-to-use statement, but the alternative is named clearly.

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

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

Annotations already declare readOnly, idempotent, open-world behavior, yet the description adds substantive semantics: values are point samples at nodes (not cell averages) so an inter-node summit is missed, and over open water Mapzen cells are sea-floor depths. These caveats materially change interpretation of results; only auth/rate-limit behavior is absent.

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?

Front-loaded with what the tool returns, then the sampling caveat, the refinement tip, and the water/limit notes. Every sentence carries information, though the output enumeration is somewhat redundant given an output schema exists.

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?

With an output schema present, the description need not restate return values, yet it covers the sampling model, the water interpretation, the iterative refinement path, and the size cap. An agent has everything needed to call this correctly and interpret the result.

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 schema already documents rows, cols, edges, source aliasing, and the 250-cell cap. The description largely repeats the rows×cols limit and source behavior already in the schema, adding little beyond the baseline.

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?

States a specific verb (sample) and resource (regular grid of terrain elevations) with the scope (across a bounding box) and the outputs (high/low/mean/relief plus full matrix). This clearly distinguishes it from the point, profile, and line-of-sight siblings without needing to name them.

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?

Gives an explicit refinement workflow: 'to refine a candidate high or low point, call again with a smaller box around it.' It does not explicitly compare against the sibling tools (get_points, get_profile, check_line_of_sight), so the agent must infer when a grid is preferable to those, but the practical usage context is clear.

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

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

Adds substantial behavior beyond the readOnly/openWorld/idempotent annotations: the automatic dataset fallback chain, per-dataset resolutions and geographic coverage limits, negative values meaning sea-floor depth over ocean, and that a point with no data returns status no_data rather than failing the whole call. That last detail is exactly the kind of error-semantics disclosure annotations cannot carry.

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?

One dense paragraph, front-loaded with the core action and batch limit, then progressively less essential coverage detail. Every sentence carries information, though the dataset/resolution inventory is heavy relative to the space it occupies.

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?

With an output schema present, the description need not explain return shapes, and it instead covers the things the schema cannot: coverage regions, resolution differences, fallback behavior, and per-point failure semantics. Nothing needed to call it correctly is missing.

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 coverage is 100% and the source enum is already documented in detail, so the baseline is 3. The description goes further by explaining what each source actually yields (3DEP 1–30 m; SRTM ~30 m land; Mapzen beyond SRTM and over ocean), giving the agent a reason to pick a non-auto source rather than just an accepted value list.

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?

States a specific verb and resource ('look up ground elevation'), plus scope ('up to 100 coordinates in one call'), returned units (meters and feet), and provenance (dataset and resolution per point). The batch-of-points framing distinguishes it from the sibling path/grid/profile tools without needing to name them.

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?

Gives clear conditions for the source behavior (3DEP inside US coverage, Open Topo Data elsewhere, SRTM latitude band, Mapzen fallback) and the no_data outcome. It stops short of explicitly naming an alternative among elevation_get_grid / elevation_get_profile / elevation_check_line_of_sight, so the agent must infer the batch-of-discrete-points use case.

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

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

With readOnly/idempotent/openWorld annotations already covering the safety profile, the description goes well beyond: it discloses that ascent/descent depend on sample spacing, that denser sampling captures more small climbs down to source resolution, that Mapzen over water yields sea-floor depths, and that each USGS 3DEP sample is a separate upstream request costing roughly 10–30 s for 250 samples.

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?

It is a single dense paragraph, but front-loaded with purpose then return values, and nearly every sentence carries operative detail (sampling dependence, water depths, latency). Minor redundancy by restating output fields that the output schema already covers.

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 4-parameter tool with a full output schema and annotations, the agent has everything needed: what it computes, how sampling affects the numbers, source fallbacks, and runtime expectations. No material gap remains.

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% and the schema already documents path, source aliases, samples range/default, and include_samples behavior in detail. The description adds only the behavioral consequence of sampling density, so the baseline 3 for a fully-documented schema is appropriate.

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 precise verb+resource: sampling terrain elevation at evenly spaced points along a route polyline, and summarizing it. The route-polyline scope cleanly separates it from elevation_get_points, elevation_get_grid, and elevation_check_line_of_sight without naming them.

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?

Usage is implied by the route/polyline framing and by notes like 'for a large count where only the summary matters, set include_samples to false', which guides a calling pattern. However, it never states when to choose this over the sibling tools (points vs grid vs line-of-sight), leaving that routing decision to inference.

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