docs: sync all tool references to 13 tools + add tool change checklist (#45)

Update all documentation to reflect current 13 tools (10 atomic + 3 composite):

- README: tool count (4 places), Available Tools table, vs Grounding Lite
  table, project structure, exec mode tool list
- SKILL.md: Tool Map table — add Environment and Composite categories
- tools-api.md: add timezone, weather, explore-area, plan-route,
  compare-places parameter docs
- CLAUDE.md: add Tool Change Checklist (9-file update list)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: cablate

CLAUDE.md

@@ -4,3 +4,21 @@
 
 - **永遠不要直接推 main**。所有變更都要先開 feature branch、推上去、建 PR，等審核通過後才合併。
 - Commit 完成後走 `git checkout -b feat/xxx` → `git push -u origin feat/xxx` → `gh pr create` 流程。
+
+## Tool 變更 Checklist
+
+每次新增、刪除、或重新命名 tool 時，以下所有檔案都必須同步更新：
+
+| # | 檔案 | 更新內容 |
+|---|------|---------|
+| 1 | `src/tools/maps/*.ts` | Tool 定義（NAME, DESCRIPTION, SCHEMA, ACTION） |
+| 2 | `src/config.ts` | 註冊 tool + annotations |
+| 3 | `src/cli.ts` | EXEC_TOOLS 列表 + switch case |
+| 4 | `tests/smoke.test.ts` | expectedTools 陣列 + tool count assertions |
+| 5 | `README.md` | tool 數量（header、vs Grounding Lite 表、Server Info、exec mode）+ Available Tools 表格 + Project Structure |
+| 6 | `skills/google-maps/SKILL.md` | Tool Map 表格 |
+| 7 | `skills/google-maps/references/tools-api.md` | 參數文件 + chaining patterns |
+| 8 | `server.json` | description（如有提到 tool 數量） |
+| 9 | `package.json` | description（如有提到 tool 數量） |
+
+漏更任何一個都會造成文件和實際行為不一致。PR 提交前請逐一確認。

README.md

@@ -6,22 +6,23 @@
 
 Give your AI agent the ability to understand the physical world — geocode, route, search, and reason about locations.
 
-- **10 tools** — geocode, reverse-geocode, search-nearby, search-places, place-details, directions, distance-matrix, elevation, timezone, weather
+- **13 tools** — 10 atomic + 3 composite (explore-area, plan-route, compare-places)
 - **3 modes** — stdio, StreamableHTTP, standalone exec CLI
 - **Agent Skill** — built-in skill definition teaches AI how to chain geo tools ([`skills/google-maps/`](./skills/google-maps/))
 
 ### vs Google Grounding Lite
 
 | | This project | [Grounding Lite](https://cloud.google.com/blog/products/ai-machine-learning/announcing-official-mcp-support-for-google-services) |
 |---|---|---|
-| Tools | **10** | 3 |
+| Tools | **13** | 3 |
 | Geocoding | Yes | No |
 | Step-by-step directions | Yes | No |
 | Elevation | Yes | No |
 | Distance matrix | Yes | No |
 | Place details | Yes | No |
 | Timezone | Yes | No |
 | Weather | Yes | Yes |
+| Composite tools (explore, plan, compare) | Yes | No |
 | Open source | MIT | No |
 | Self-hosted | Yes | Google-managed only |
 | Agent Skill | Yes | No |
@@ -56,7 +57,11 @@ Special thanks to [@junyinnnn](https://github.com/junyinnnn) for helping add sup
 | `maps_directions` | Get step-by-step navigation between two points with route details. |
 | `maps_elevation` | Get elevation (meters above sea level) for geographic coordinates. |
 | `maps_timezone` | Get timezone ID, name, UTC/DST offsets, and local time for coordinates. |
-| `maps_weather` | Get current weather conditions — temperature, humidity, wind, UV, precipitation. |
+| `maps_weather` | Get current weather conditions or forecast — temperature, humidity, wind, UV, precipitation. |
+| **Composite Tools** | |
+| `maps_explore_area` | Explore what's around a location — searches multiple place types and gets details in one call. |
+| `maps_plan_route` | Plan an optimized multi-stop route — geocodes, finds best order, returns directions. |
+| `maps_compare_places` | Compare places side-by-side — searches, gets details, and optionally calculates distances. |
 
 All tools are annotated with `readOnlyHint: true` and `destructiveHint: false` — MCP clients can auto-approve these without user confirmation.
 
@@ -106,7 +111,7 @@ Then configure your MCP client:
 ### Server Information
 
 - **Transport**: stdio (`--stdio`) or Streamable HTTP (default)
-- **Tools**: 10 Google Maps tools
+- **Tools**: 13 Google Maps tools (10 atomic + 3 composite)
 
 ### CLI Exec Mode (Agent Skill)
 
@@ -117,7 +122,7 @@ npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
 npx @cablate/mcp-google-map exec search-places '{"query":"ramen in Tokyo"}'
 ```
 
-All 10 tools available: `geocode`, `reverse-geocode`, `search-nearby`, `search-places`, `place-details`, `directions`, `distance-matrix`, `elevation`, `timezone`, `weather`. See [`skills/google-maps/`](./skills/google-maps/) for the agent skill definition and full parameter docs.
+All 13 tools available: `geocode`, `reverse-geocode`, `search-nearby`, `search-places`, `place-details`, `directions`, `distance-matrix`, `elevation`, `timezone`, `weather`, `explore-area`, `plan-route`, `compare-places`. See [`skills/google-maps/`](./skills/google-maps/) for the agent skill definition and full parameter docs.
 
 ### API Key Configuration
 
@@ -209,7 +214,10 @@ src/
 │       ├── directions.ts         # maps_directions tool
 │       ├── elevation.ts          # maps_elevation tool
 │       ├── timezone.ts           # maps_timezone tool
-│       └── weather.ts            # maps_weather tool
+│       ├── weather.ts            # maps_weather tool
+│       ├── exploreArea.ts        # maps_explore_area (composite)
+│       ├── planRoute.ts          # maps_plan_route (composite)
+│       └── comparePlaces.ts      # maps_compare_places (composite)
 └── utils/
     ├── apiKeyManager.ts          # API key management
     └── requestContext.ts         # Per-request context (API key isolation)

skills/google-maps/SKILL.md

@@ -35,7 +35,7 @@ Without this Skill, the agent can only guess or refuse when asked "how do I get
 
 ## Tool Map
 
-8 tools in three categories — pick by scenario:
+13 tools in four categories — pick by scenario:
 
 ### Place Discovery
 | Tool | When to use | Example |
@@ -52,10 +52,19 @@ Without this Skill, the agent can only guess or refuse when asked "how do I get
 | `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?" |
 
-### Terrain
+### 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?" |
+
+### 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?" |
 
 ---
 

skills/google-maps/references/tools-api.md

@@ -160,6 +160,95 @@ Response:
 
 ---
 
+## timezone
+
+Get timezone and local time for coordinates.
+
+```bash
+exec timezone '{"latitude": 35.6586, "longitude": 139.7454}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| latitude | number | yes | Latitude |
+| longitude | number | yes | Longitude |
+| timestamp | number | no | Unix timestamp in ms (defaults to now) |
+
+Response:
+```json
+{ "timeZoneId": "Asia/Tokyo", "timeZoneName": "Japan Standard Time", "utcOffset": 32400, "dstOffset": 0, "localTime": "2026-03-14T16:19:16.000" }
+```
+
+---
+
+## weather
+
+Get current weather or forecast. Coverage: most regions, but China, Japan, South Korea, Cuba, Iran, North Korea, Syria are unsupported.
+
+```bash
+exec weather '{"latitude": 37.4220, "longitude": -122.0841}'
+exec weather '{"latitude": 37.4220, "longitude": -122.0841, "type": "forecast_daily", "forecastDays": 3}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| latitude | number | yes | Latitude |
+| longitude | number | yes | Longitude |
+| type | string | no | `current` (default), `forecast_daily`, `forecast_hourly` |
+| forecastDays | number | no | 1-10, for forecast_daily (default: 5) |
+| forecastHours | number | no | 1-240, for forecast_hourly (default: 24) |
+
+---
+
+## explore-area (composite)
+
+Explore a neighborhood in one call. Internally chains geocode → search-nearby (per type) → place-details (top N).
+
+```bash
+exec explore-area '{"location": "Tokyo Tower", "types": ["restaurant", "cafe"], "topN": 2}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| location | string | yes | Address or landmark |
+| types | string[] | no | Place types to search (default: restaurant, cafe, attraction) |
+| radius | number | no | Search radius in meters (default: 1000) |
+| topN | number | no | Top results per type to get details for (default: 3) |
+
+---
+
+## plan-route (composite)
+
+Plan an optimized multi-stop route. Internally chains geocode → distance-matrix → nearest-neighbor → directions.
+
+```bash
+exec plan-route '{"stops": ["Tokyo Tower", "Shibuya Station", "Shinjuku Station", "Ueno Park"], "mode": "driving"}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| stops | string[] | yes | Addresses or landmarks (min 2) |
+| mode | string | no | driving, walking, bicycling, transit (default: driving) |
+| optimize | boolean | no | Auto-optimize visit order (default: true) |
+
+---
+
+## compare-places (composite)
+
+Compare places side-by-side. Internally chains search-places → place-details → distance-matrix.
+
+```bash
+exec compare-places '{"query": "ramen near Shibuya", "limit": 3}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| query | string | yes | Search query |
+| userLocation | object | no | `{ latitude, longitude }` — adds distance/drive time |
+| limit | number | no | Max places to compare (default: 5) |
+
+---
+
 ## Chaining Patterns
 
 ### Basic Patterns