fix(location-grounding): correct what ground_location_tool actually returns

[mattpodwysocki]

Description

The mapbox-location-grounding skill made two claims about ground_location_tool that are not true:

• Nearby POIs with distances, ratings, price levels, and popularity (when available)

Do not call reverse_geocode_tool, category_search_tool, place_details_tool, or isochrone_tool separately — they are already composed inside this tool.

GroundLocationOutputSchema's PoiSchema defines only name, address, longitude, latitude, category, and distance_meters. No rating, price, or popularity field exists, and the tool makes no Place Details call at any point. It also claimed to return "a static map image", where it actually returns a mapboxRender reference.

Why it matters: a model following this skill is told enrichment has already happened, finds no ratings in the result, and is left to fill the gap — from training data, which is the precise failure this skill exists to prevent. The skill's own anti-pattern list says "Hallucinating business names, hours, or ratings" two screens below the instruction that sets that up.

What changed

• The Returns list now describes the real payload, including mapbox_id / external_ids per POI and the map render reference.
• The "do not call separately" line now names only the three tools actually composed inside (reverse_geocode_tool, category_search_tool, isochrone_tool), with place_details_tool called out as the deliberate exception and given an explicit follow-up step.
• Two caveats on that step: a POI without a mapbox_id can't be enriched, and an OpenStreetMap-sourced id (decodes to urn:mbxpoi-osm: rather than urn:mbxpoi:) is rejected by the details endpoint. Both instruct the model to describe the place from the grounding data rather than from training data.
• Three other passages that credited ratings and prices to the wrong tool are now consistent: the query-parameter guidance, the grounded-response template, and the anti-patterns list.

---

Type of Change

• Bug fix (correction in examples, guidance, or docs)
• Skill improvement/update

---

Skill Details

Skill name: mapbox-location-grounding

What domain expertise does this skill provide?
Composing Mapbox MCP tools into grounded, cited location answers instead of answering from training data.

When should this skill be used?
"What's near X?", neighborhood/area description, and travel-time questions — anywhere place accuracy or recency matters.

---

Testing

Local validation:

• npm run check passes
• Spell check passes
• Markdown linting passes
• Skills validation passes

AI assistant testing:

• Tested with Claude Code
• Verified skill activates in relevant scenarios
• Confirmed guidance is actionable and accurate

Testing evidence:

The claims were checked against a live ground_location_tool call through mcp.mapbox.com, not against documentation. Grounding on Anacostia Park, DC returned:

{
  "place": "Anacostia Park",
  "nearby_pois": [
    {
      "name": "Grounded: Plant Shop, Cafe, & Wellness Studio",
      "address": "1913 Martin Luther King Jr Ave SE, Washington, DC 20020",
      "longitude": -76.98891203, "latitude": 38.86712324,
      "category": "café", "distance_meters": 253
    }
  ],
  "isochrone": { "profile": "mapbox/walking", "contours_minutes": [15, 10, 5] },
  "citations": ["Mapbox Geocoding API", "Mapbox Isochrone API", "Mapbox Search API"]
}

No rating, price, popularity, or hours on any POI, and no Place Details request in the call. npm run check output ends ✅ All skills are valid.

---

Checklist

• YAML frontmatter is correct (name matches directory) — unchanged
• Content includes actionable guidance with examples
• Anti-patterns (❌) and solutions (✅) are provided where applicable — anti-patterns list updated for consistency
• Decision matrices or thresholds included for choices
• Real-world scenarios are covered
• All technical information is accurate — the point of this PR
• References to official Mapbox documentation included
• New domain-specific terms added to cspell.config.json — mbxpoi

---

Additional Notes

Merge order is not a blocker, but worth knowing. The enrichment step tells the model to take mapbox_id off each POI. ground_location_tool doesn't return mapbox_id today — mapbox/mcp-server#263 adds it. I wrote the step to degrade safely rather than gate this PR on that one: before #263 lands, a model following it finds no ids and simply skips enrichment, which is the correct behavior anyway, and the "cannot be enriched → don't invent it" caveat covers that case explicitly. After #263, it works as written.

Everything else here — the false "already composed inside" claim, the non-existent ratings/price/popularity fields, the static map image — is wrong today and independent of #263.

Not addressed here: whether ground_location_tool should compose Place Details server-side so the original claim becomes true. That's a real option now that mapbox/mcp-server#262 has built batched Place Details enrichment for the render panel, but it's a design call for that repo, and it would change this tool's latency and cost profile. This PR makes the skill match the tool as it is.

🤖 Generated with Claude Code