fix: steer map display to render_map_tool via server instructions

[mattpodwysocki]

Problem

In Claude Desktop, after a successful isochrone_tool call, the model loaded static_map_image_tool to show the result and never loaded render_map_tool. When asked why, the model said it had loaded static_map_image_tool "because the name looked like the right fit for 'show a map'" and never saw render_map_tool's description.

Cause

Claude Desktop lists only tool names until the model loads a tool. render_map_tool's description says "ALWAYS use this tool to display maps", but nothing the model could see before choosing said so.

Fix

• Server instructions: the server now returns MCP instructions from initialize, which hosts show up front:

  • use render_map_tool to show anything on a map;
  • pass mapboxRender.ref values unchanged and never write one by hand (this also targets the ChatGPT cause behind fix(render_map_tool): reject isochrone selffetch refs without contours #267);
  • use static_map_image_tool only when the user explicitly asks for an image file.

  The instructions name only enabled tools, and are omitted when render_map_tool is disabled.

• static_map_image_tool description: now says to use render_map_tool to show a map.

• Hint on tool results: the hint appended to results that carry a mapboxRender.ref now names render_map_tool over static_map_image_tool and says to pass the ref unchanged.

Testing

• New tests cover the instruction text with all tools enabled, without static_map_image_tool, and without render_map_tool.
• Full suite passes (961 tests), plus lint.
• Against the built server over stdio: initialize returns the instructions, and tools/list shows the updated static_map_image_tool description.
• I haven't yet confirmed that the model follows the instructions in Claude Desktop.

🤖 Generated with Claude Code