[mattpodwysocki]

Part 4 of #289. The server had no elevation at all, so "how hilly is this bike route?" or "how high is this town?" had no answer from Mapbox data.

What it does

elevation_tool takes one of:

• points: up to 25 places, returns each one's ground elevation
• path: a line of up to 1,000 coordinates
• directions_ref: the mapboxRender.ref from a directions_tool result, which the tool turns back into the full route with directionsRequestFromRef (feat(utils): export directionsRequestFromRef for routes by reference #276), so the model never copies route geometry

For a line it returns distance, climb, descent, start, end, highest and lowest points, and a profile of up to 50 points (12 in the text). It also returns a map ref with the line and ▲/▼ markers at the high and low points.

Why DEM tiles and not Tilequery

Tilequery can't read mapbox.mapbox-terrain-dem-v1 (422), and Terrain v2 contours come in 10 m steps or coarser:

Point	Terrain v2 contours	DEM tiles
Near Twin Peaks, SF	240 m	249.5 m
Civic Center, SF	10 m	20.9 m
Longs Peak summit		4,346 m (surveyed 4,346 m)

So the server fetches the DEM's .pngraw tiles (terrain-RGB) and decodes heights, with bilinear interpolation between pixels. The PNG decoder is ~100 lines on Node's zlib (8-bit RGB/RGBA, not interlaced), so no new dependency.

Cost

• A path is sampled at up to 500 points, never closer than one DEM pixel.
• Samples share tiles, and each tile is fetched once per call.
• On long paths the zoom drops until the path needs at most 48 tiles. The result reports zoom and resolution_m so the model can say how rough it is.
• Swings under 2 m don't count toward climb, so DEM noise on flat ground doesn't add up.

Live:

Call	Result
Ferry Building to Twin Peaks by bike	274 m climb, 1 tile, 7.5 m resolution, 0.6 s
SF to LA by car	high point 1,276 m near Tejon Pass, ~120 m resolution, 1.3 s

Open on #289

Whether describe_tileset_tool and tilequery_tool come next, and whether they're on by default, is waiting on the team (comment on #289). This tool is narrow, so it's on by default.

Testing

• A PNG encoder in the tests covers all five row filters, RGB and RGBA, and bad input (not a PNG, 16-bit, palette, truncated).
• Synthetic terrain tiles test point heights, interpolation, climb along a path, a directions ref, the zoom choice for a long route, the noise threshold, a refused token, and that -0 m never prints.
• npm test: 1102 pass. Not yet tried in Claude Desktop or ChatGPT.

🤖 Generated with Claude Code