fix: align skill tool names with actual MCP names (#52)

* fix: align skill tool names with actual MCP names + add API limitations

Tool names in all skill files now match actual MCP registration:
- `geocode` → `maps_geocode`, `search-along-route` → `maps_search_along_route`, etc.
- This was causing AI agents to fail to discover tools during testing

Also added:
- Known API Limitations section (weather unsupported in Japan/China/Korea,
  distance-matrix transit nulls in Japan)
- Removed outdated "Future Composite Tools" section (all three are built)
- Updated Recipe 7 to prefer maps_search_along_route over manual midpoint search

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add GOOGLE_MAPS_ENABLED_TOOLS env var to filter registered tools

Users can set GOOGLE_MAPS_ENABLED_TOOLS to a comma-separated list of
tool names to limit which tools are registered with the MCP client,
reducing context window usage for agents that only need a subset.

- Not set or "*" = all 17 tools enabled (default)
- "maps_geocode,maps_directions" = only those 2 tools registered
- If no tools match, falls back to all tools with an error log

Usage in MCP client config:
  "env": { "GOOGLE_MAPS_ENABLED_TOOLS": "maps_geocode,maps_directions" }

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: env var double prefix bug + update README/tests to match codebase

Fixes:
- GOOGLE_MAPS_GOOGLE_MAPS_ENABLED_TOOLS → GOOGLE_MAPS_ENABLED_TOOLS
  (replace_all accidentally doubled the prefix)
- cli.ts startup log listed nonexistent tools (echo, get_place_details)
- smoke.test.ts expectedTools missing 3 composite tools (147 tests now)
- SKILL.md version 0.0.37 → 0.0.38 to match package.json
- README Roadmap: removed skipped items (validate_address, isochrone),
  added recently completed tools and planned features

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cablate

README.md

@@ -93,6 +93,19 @@ Works with Claude Desktop, Cursor, VS Code, and any MCP client that supports std
 }
 ```
 
+**Reduce context usage** — If you only need a subset of tools, set `GOOGLE_MAPS_ENABLED_TOOLS` to limit which tools are registered:
+
+```json
+{
+  "env": {
+    "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY",
+    "GOOGLE_MAPS_ENABLED_TOOLS": "maps_geocode,maps_directions,maps_search_places"
+  }
+}
+```
+
+Omit or set to `*` for all 17 tools (default).
+
 ### Method 2: HTTP Server
 
 For multi-session deployments, per-request API key isolation, or remote access:
@@ -117,7 +130,7 @@ Then configure your MCP client:
 ### Server Information
 
 - **Transport**: stdio (`--stdio`) or Streamable HTTP (default)
-- **Tools**: 16 Google Maps tools (14 atomic + 3 composite)
+- **Tools**: 17 Google Maps tools (14 atomic + 3 composite) — filterable via `GOOGLE_MAPS_ENABLED_TOOLS`
 
 ### CLI Exec Mode (Agent Skill)
 
@@ -282,22 +295,26 @@ For enterprise security reviews, see [Security Assessment Clarifications](./SECU
 
 ## Roadmap
 
-### New Tools
+### Recent Additions
 
-| Tool | What it unlocks | Status |
+| Tool / Feature | What it unlocks | Status |
 |------|----------------|--------|
-| `maps_static_map` | Return map images with pins/routes — multimodal AI can "see" the map | **Done** |
-| `maps_air_quality` | AQI, pollutants — health-aware travel, outdoor planning, real estate | **Done** |
-| `maps_validate_address` | Standardize and verify addresses — logistics/e-commerce | Planned |
-| `maps_isochrone` | "Show me everything within 30 min drive" — reachability analysis | Planned |
-| `maps_batch_geocode` | Geocode hundreds of addresses in one call — data enrichment | **Done** (CLI) |
+| `maps_static_map` | Map images with pins/routes — multimodal AI can "see" the map | **Done** |
+| `maps_air_quality` | AQI, pollutants — health-aware travel, outdoor planning | **Done** |
+| `maps_batch_geocode` | Geocode up to 50 addresses in one call — data enrichment | **Done** |
+| `maps_search_along_route` | Find places along a route ranked by detour time — trip planning | **Done** |
+| `maps_explore_area` | One-call neighborhood overview (composite) | **Done** |
+| `maps_plan_route` | Optimized multi-stop itinerary (composite) | **Done** |
+| `maps_compare_places` | Side-by-side place comparison (composite) | **Done** |
+| `GOOGLE_MAPS_ENABLED_TOOLS` | Filter tools to reduce context usage | **Done** |
 
-### Capabilities
+### Planned
 
 | Feature | What it unlocks | Status |
 |---------|----------------|--------|
-| Spatial Context | Agent remembers "the area we were just looking at" across turns | Research |
-| Geo Agent Template | One command to spin up a full geo-aware AI agent | Research |
+| `maps_place_photo` | Place photos for multimodal AI — "see" the restaurant ambiance | Planned |
+| Language parameter | Multi-language responses (ISO 639-1) across all tools | Planned |
+| MCP Prompt Templates | `/travel-planner`, `/neighborhood-scout` slash commands in Claude Desktop | Planned |
 | Geo-Reasoning Benchmark | 10-scenario test suite measuring LLM geospatial reasoning accuracy | Research |
 
 ### Use Cases We're Building Toward

skills/google-maps/SKILL.md

@@ -2,7 +2,7 @@
 name: google-maps
 description: Geospatial query capabilities — geocoding, nearby search, routing, place details, elevation. Trigger when the user mentions locations, addresses, coordinates, navigation, "what's nearby", "how to get there", distance/duration, or any question that inherently involves geographic information — even if they don't explicitly say "map". Update when new tools are added or tool parameters change.
 license: MIT
-version: 0.0.25
+version: 0.0.38
 compatibility:
   - claude-code
   - cursor
@@ -40,39 +40,49 @@ Without this Skill, the agent can only guess or refuse when asked "how do I get
 ### Place Discovery
 | Tool | When to use | Example |
 |------|-------------|---------|
-| `geocode` | Have an address/landmark, need coordinates | "What are the coordinates of Tokyo Tower?" |
-| `reverse-geocode` | Have coordinates, need an address | "What's at 35.65, 139.74?" |
-| `search-nearby` | Know a location, find nearby places by type | "Coffee shops near my hotel" |
-| `search-places` | Natural language place search | "Best ramen in Tokyo" |
-| `place-details` | Have a place_id, need full info | "Opening hours and reviews for this restaurant?" |
-| `batch-geocode` | Geocode multiple addresses at once (max 50) | "Get coordinates for all these offices" |
+| `maps_geocode` | Have an address/landmark, need coordinates | "What are the coordinates of Tokyo Tower?" |
+| `maps_reverse_geocode` | Have coordinates, need an address | "What's at 35.65, 139.74?" |
+| `maps_search_nearby` | Know a location, find nearby places by type | "Coffee shops near my hotel" |
+| `maps_search_places` | Natural language place search | "Best ramen in Tokyo" |
+| `maps_place_details` | Have a place_id, need full info | "Opening hours and reviews for this restaurant?" |
+| `maps_batch_geocode` | Geocode multiple addresses at once (max 50) | "Get coordinates for all these offices" |
 
 ### Routing & Distance
 | Tool | When to use | Example |
 |------|-------------|---------|
-| `directions` | How to get from A to B | "Route from Taipei Main Station to the airport" |
-| `distance-matrix` | Compare distances across multiple points | "Which of these 3 hotels is closest to the airport?" |
-| `search-along-route` | Find places along a route (meals, stops) ranked by detour time | "Restaurants between Fushimi Inari and Kiyomizu-dera" |
+| `maps_directions` | How to get from A to B | "Route from Taipei Main Station to the airport" |
+| `maps_distance_matrix` | Compare distances across multiple points | "Which of these 3 hotels is closest to the airport?" |
+| `maps_search_along_route` | Find places along a route (meals, stops) ranked by detour time | "Restaurants between Fushimi Inari and Kiyomizu-dera" |
 
 ### Environment
 | Tool | When to use | Example |
 |------|-------------|---------|
-| `elevation` | Query altitude | "Elevation profile along this hiking trail" |
-| `timezone` | Need local time at a destination | "What time is it in Tokyo?" |
-| `weather` | Weather at a location (current or forecast) | "What's the weather in Paris?" |
-| `air-quality` | AQI, pollutants, health recommendations | "Is the air safe for jogging?" |
+| `maps_elevation` | Query altitude | "Elevation profile along this hiking trail" |
+| `maps_timezone` | Need local time at a destination | "What time is it in Tokyo?" |
+| `maps_weather` | Weather at a location (current or forecast) | "What's the weather in Paris?" |
+| `maps_air_quality` | AQI, pollutants, health recommendations | "Is the air safe for jogging?" |
 
 ### Visualization
 | Tool | When to use | Example |
 |------|-------------|---------|
-| `static-map` | Show locations/routes on a map image | "Show me these places on a map" |
+| `maps_static_map` | Show locations/routes on a map image | "Show me these places on a map" |
 
 ### Composite (one-call shortcuts)
 | Tool | When to use | Example |
 |------|-------------|---------|
-| `explore-area` | Overview of a neighborhood | "What's around Tokyo Tower?" |
-| `plan-route` | Multi-stop optimized itinerary | "Visit these 5 places efficiently" |
-| `compare-places` | Side-by-side comparison | "Which ramen shop near Shibuya?" |
+| `maps_explore_area` | Overview of a neighborhood | "What's around Tokyo Tower?" |
+| `maps_plan_route` | Multi-stop optimized itinerary | "Visit these 5 places efficiently" |
+| `maps_compare_places` | Side-by-side comparison | "Which ramen shop near Shibuya?" |
+
+---
+
+## Known API Limitations
+
+| Tool | Limitation | Workaround |
+|------|-----------|------------|
+| `maps_weather` | Unsupported regions: Japan, China, South Korea, Cuba, Iran, North Korea, Syria | Use web search for weather in these regions |
+| `maps_distance_matrix` | Transit mode returns null in some regions (notably Japan) | Fall back to `driving` or `walking` mode, or use `maps_directions` for transit |
+| `maps_air_quality` | Works globally including Japan (unlike weather) | — |
 
 ---
 
@@ -85,6 +95,8 @@ npx @cablate/mcp-google-map exec <tool> '<json_params>' [-k API_KEY]
 - **API Key**: `-k` flag or `GOOGLE_MAPS_API_KEY` environment variable
 - **Output**: JSON to stdout, errors to stderr
 - **Stateless**: each call is independent
+- **Tool names**: CLI accepts both `maps_geocode` and `geocode` short forms
+- **Tool filtering**: Set `GOOGLE_MAPS_ENABLED_TOOLS` env var to a comma-separated list of tool names to limit registered tools (reduces MCP client context usage). Omit or set to `*` for all tools.
 
 ---