@cablate/mcp-google-map 0.0.36 → 0.0.38

package/skills/google-maps/references/travel-planning.md

@@ -0,0 +1,136 @@
+# Travel Planning Best Practices
+
+## Core Principle
+
+Real travel planning is **directional exploration**, not point collection.
+
+A human plans: "Start south at Fushimi Inari, walk up to Kiyomizu-dera, eat lunch somewhere along the way in Gion, then head west to Arashiyama for evening."
+
+An algorithm plans: "Here are the top 10 rated places. Optimizing shortest path..."
+
+The difference is **arc thinking** — one direction per day, discovering things along the way.
+
+---
+
+## The 6-Layer Decision Model
+
+Human travel planners think in layers. Each layer constrains the next.
+
+### Layer 1: Anchor Discovery
+**What:** Find 4-6 must-visit landmarks spread across the city.
+**Tool:** `search_places("top attractions in {city}")`
+**Why it works:** Google's algorithm returns geographically diverse results. Kyoto → Fushimi(south), Kiyomizu(east), Kinkaku-ji(north), Arashiyama(west) — natural 8km×10km spread.
+
+### Layer 2: Arc Design
+**What:** Connect anchors into one-directional arcs per day. Edge landmarks go at start/end of a day.
+**Tool:** `distance_matrix` between anchors to understand spatial relationships.
+**Rule:** Never backtrack. Each day sweeps one direction (south→north, east→west).
+
+Example:
+```
+Day 1: Fushimi(south) → Kiyomizu(east) → Gion → Pontocho(center)   [south→center arc]
+Day 2: Nishiki(center) → Nijo Castle → train → Arashiyama(west)     [center→west arc]
+```
+
+### Layer 3: Time-Slot Matching
+**What:** Assign anchors to times based on **experience quality**, not distance.
+**Tool:** None — this is AI knowledge.
+**Examples:**
+- Fushimi Inari = **early morning** (fewer crowds, best light for photos, hiking needs fresh legs)
+- Outdoor temples = **morning to afternoon** (natural light)
+- Shopping districts = **afternoon** (all stores open)
+- Scenic areas = **late afternoon** (golden hour light)
+- Fine dining = **evening at the final stop** (no rush to next destination)
+
+### Layer 4: Along-Route Filling
+**What:** Between two anchors, find what's **on the way** — not at the destination.
+**Tool:** `search_along_route(textQuery, origin, destination)`
+**This is the key differentiator.** Results are ranked by minimal detour time, not proximity to a point.
+
+```
+search_along_route("restaurant", "Fushimi Inari, Kyoto", "Kiyomizu-dera, Kyoto", "walking")
+→ Finds restaurants ALONG the 4km walking route, not clustered at either end
+```
+
+### Layer 5: Meal Embedding
+**What:** Meals appear where the traveler **will be** at mealtime, not where the "best restaurant" is.
+**Logic:**
+1. Estimate what time the traveler reaches each arc segment
+2. Lunch (~12:00) → search_along_route("lunch restaurant", previous_stop, next_stop)
+3. Dinner (~18:00) → search_nearby at the day's final area (no rush)
+
+**Anti-pattern:** "I searched for the best restaurant in the whole city" → it's 3km off the route.
+**Correct:** "You'll be near Gion around noon — here are options along the way."
+
+### Layer 6: Rhythm Validation
+**What:** Check the itinerary feels human, not robotic.
+**Tool:** `plan_route(stops, optimize: false)` to get actual times, `weather` for conditions.
+**Checklist:**
+- [ ] Not 5 temples in a row (alternate: temple → food → walk → shrine → cafe)
+- [ ] Major temples get 90-120 min, not 30 min
+- [ ] Walking per day < 10km (suggest transit for >2km gaps)
+- [ ] Lunch 11:30-13:00, dinner 17:30-19:30
+- [ ] 5-7 stops per day max (including meals)
+- [ ] Final stop: call `static_map` with markers + path to visualize
+
+---
+
+## Tool Call Sequence
+
+```
+Phase 1 — Skeleton (2-3 calls)
+  search_places("top attractions in {city}")        → anchors
+  distance_matrix(all anchors)                       → spatial relationships
+
+Phase 2 — Arc + Fill (2-4 calls per day)
+  search_along_route("restaurant", stop_A, stop_B)  → along-route meals
+  search_along_route("cafe", stop_B, stop_C)         → along-route breaks
+
+Phase 3 — Environment (2 calls)
+  weather(city coords)                               → rain → move indoor activities
+  air_quality(city coords)                           → bad AQI → reduce outdoor time
+
+Phase 4 — Validate + Visualize (2 calls per day)
+  plan_route(day_stops, optimize: false)             → verify times/distances
+  static_map(markers + path)                         → map for each day
+
+Total: ~12-16 calls for a 2-day trip
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Symptom | Fix |
+|-------------|---------|-----|
+| Single-point explosion | `explore_area("Kyoto")` → all within 1km | search_places for anchors first |
+| Backtracking | east→west→east→west | One direction per day |
+| No along-route search | Meals at endpoints only | `search_along_route` between stops |
+| Distance-optimal ordering | Ignores time-of-day quality | AI assigns time slots before routing |
+| No map output | Text/JSON only | Always `static_map` after each day's route |
+| Over-scheduling | 12 stops in one day | Max 5-7 stops including meals |
+| Same-type clustering | 5 temples consecutively | Alternate activity types |
+
+---
+
+## Time Budget
+
+| Activity | Duration |
+|----------|----------|
+| Major temple/shrine | 60-120 min |
+| Small shrine / photo spot | 15-30 min |
+| Museum | 90-180 min |
+| Market / shopping street | 60-90 min |
+| Sit-down meal | 60-120 min |
+| Quick meal / street food | 20-40 min |
+| Cafe break | 30-45 min |
+| Walking <1km | 10-15 min |
+| Transit between areas | 20-40 min |
+
+---
+
+## When to Read This
+
+- User says "plan a trip", "create an itinerary", "plan X days in Y"
+- Trip plan clusters all stops in one area
+- Building multi-day travel content

package/skills/project-docs/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: mcp-google-map-project
+description: Project knowledge for developing and maintaining @cablate/mcp-google-map. Architecture, Google Maps API guide, GIS domain knowledge, and design decisions. Read this skill to onboard onto the project or make informed development decisions.
+version: 0.0.1
+compatibility:
+  - claude-code
+  - cursor
+  - vscode-copilot
+---
+
+# mcp-google-map — Project Knowledge
+
+## Overview
+
+This skill contains everything needed to develop, maintain, and extend the `@cablate/mcp-google-map` MCP server. Reading these files gives you full context on architecture, API specifics, domain knowledge, and the reasoning behind design decisions.
+
+For the **agent skill** (how to USE the tools), see `skills/google-maps/SKILL.md`.
+
+---
+
+## Quick Orientation
+
+| Aspect | Summary |
+|--------|---------|
+| **What** | MCP server providing Google Maps tools for AI agents |
+| **Stack** | TypeScript, Node.js, Express, MCP SDK, Zod |
+| **Tools** | 17 tools (14 atomic + 3 composite) |
+| **Transports** | stdio, Streamable HTTP, standalone exec CLI |
+| **APIs** | Places API (New), Directions, Geocoding, Elevation, Timezone, Weather, Air Quality, Static Maps, Search Along Route |
+
+---
+
+## Reference Files
+
+| File | Content | When to read |
+|------|---------|--------------|
+| `references/architecture.md` | System architecture, 3-layer design, transport modes, tool registration flow, 9-file checklist, code map | **Start here** when onboarding. Also read when adding new tools. |
+| `references/google-maps-api-guide.md` | All Google Maps API endpoints used, pricing, coverage limits, rate limits, common gotchas, Places New vs Legacy | When debugging API errors, evaluating new APIs, or checking costs |
+| `references/geo-domain-knowledge.md` | GIS fundamentals — coordinates, distance, geocoding, place types, spatial search, map projection, Japan-specific knowledge | When making tool design decisions that involve geographic concepts |
+| `references/decisions.md` | 10 Architecture Decision Records (ADR) with context and rationale | When asking "why was X built this way?" or considering changes to existing design |
+
+---
+
+## How to Add a New Tool
+
+See `references/architecture.md` § "9-File Tool Change Checklist" for the complete procedure. Summary:
+
+1. Create `src/tools/maps/<toolName>.ts` (NAME, DESCRIPTION, SCHEMA, ACTION)
+2. Register in `src/config.ts`
+3. Add exec case in `src/cli.ts`
+4. Add to `tests/smoke.test.ts` (expectedTools + API call test)
+5. Update `README.md` (count + table + exec list + project structure)
+6. Update `skills/google-maps/SKILL.md` (Tool Map)
+7. Update `skills/google-maps/references/tools-api.md` (params + chaining)
+8. Check `server.json` and `package.json` descriptions
+
+---
+
+## When to Update This Skill
+
+| Trigger | What to update |
+|---------|----------------|
+| Architecture change | `references/architecture.md` |
+| New Google Maps API integrated | `references/google-maps-api-guide.md` |
+| New design decision made | `references/decisions.md` (add ADR) |
+| New GIS concept relevant to tools | `references/geo-domain-knowledge.md` |

package/skills/project-docs/references/architecture.md

@@ -0,0 +1,135 @@
+# Architecture Reference
+
+## System Architecture Overview
+
+Three-layer architecture with a shared entry point:
+
+```
+CLI / HTTP / stdio
+       |
+  BaseMcpServer          <- MCP protocol layer (tool registration, transport)
+       |
+  Tool ACTION()          <- thin dispatch, calls PlacesSearcher
+       |
+  PlacesSearcher         <- service facade (composition, filtering, response shaping)
+      / \
+GoogleMapsTools    NewPlacesService
+(Legacy REST SDK)  (Places API New gRPC/REST client)
+```
+
+| Layer | Files | Responsibility |
+|---|---|---|
+| Entry | `src/cli.ts` | Parse CLI args, select transport mode, instantiate server |
+| Protocol | `src/core/BaseMcpServer.ts` | Register tools, handle MCP sessions, route HTTP/stdio |
+| Tool | `src/tools/maps/*.ts` | Declare NAME, DESCRIPTION, SCHEMA, ACTION |
+| Config | `src/config.ts` | Assemble ToolConfig[], attach MAPS_TOOL_ANNOTATIONS |
+| Facade | `src/services/PlacesSearcher.ts` | Orchestrate multi-step / composite tools |
+| API client (legacy) | `src/services/toolclass.ts` | Wrap `@googlemaps/google-maps-services-js` SDK |
+| API client (new) | `src/services/NewPlacesService.ts` | Wrap `@googlemaps/places` gRPC client |
+| Auth | `src/utils/apiKeyManager.ts` | API key priority resolution |
+| Context | `src/utils/requestContext.ts` | Per-request AsyncLocalStorage propagation |
+
+---
+
+## Transport Modes
+
+| Mode | Entry | How to activate | Notes |
+|---|---|---|---|
+| **HTTP (Streamable)** | `cli.ts` → `BaseMcpServer.startHttpServer()` | default, or `--port` | Listens on `/mcp` (POST/GET/DELETE); sessions tracked by UUID header `mcp-session-id` |
+| **stdio** | `cli.ts` → `BaseMcpServer.startStdio()` | `--stdio` flag | Used by Claude Desktop, Cursor; stdout reserved for JSON-RPC, all logs go to stderr |
+| **exec CLI** | `cli.ts` → `execTool()` | `mcp-google-map exec <tool> '<json>'` | No MCP protocol; directly calls `PlacesSearcher` method and prints JSON to stdout; used for scripting/piping |
+
+### HTTP Session Lifecycle
+
+```
+POST /mcp (no session-id, isInitializeRequest)
+  -> create StreamableHTTPServerTransport
+  -> create new McpServer, connect transport
+  -> store in sessions[uuid]
+
+POST /mcp (mcp-session-id header)
+  -> reuse existing session context
+  -> update apiKey if header present
+
+DELETE /mcp (mcp-session-id header)
+  -> terminate session, clean up transport
+```
+
+---
+
+## Tool Registration Flow
+
+```
+src/tools/maps/weather.ts          exports Weather.{NAME, DESCRIPTION, SCHEMA, ACTION}
+          |
+src/config.ts                      builds ToolConfig[] array, attaches MAPS_TOOL_ANNOTATIONS
+          |
+src/cli.ts                         passes config.tools[] to new BaseMcpServer(name, tools)
+          |
+BaseMcpServer.createMcpServer()    calls server.registerTool(name, {description, inputSchema, annotations}, action)
+          |
+@modelcontextprotocol/sdk          exposes tool to MCP client
+```
+
+`MAPS_TOOL_ANNOTATIONS` applied to all tools:
+
+```ts
+{ readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+```
+
+---
+
+## API Key Management
+
+Priority order (highest to lowest):
+
+| Priority | Source | Header / Variable |
+|---|---|---|
+| 1 | HTTP request header | `X-Google-Maps-API-Key` |
+| 2 | HTTP Authorization header | `Authorization: Bearer <key>` |
+| 3 | Session-specific key | stored per `mcp-session-id` |
+| 4 | CLI argument | `--apikey` / `-k` |
+| 5 | Environment variable | `GOOGLE_MAPS_API_KEY` |
+| 6 | `.env` file | loaded by `dotenv` at startup from `cwd` or package dir |
+
+**Flow in HTTP mode**: `ApiKeyManager.getApiKey(req)` resolves key → stored in `SessionContext.apiKey` → propagated via `runWithContext()` (AsyncLocalStorage) → tool action reads from context or `process.env`.
+
+**Flow in exec mode**: `--apikey` arg → directly passed to `new PlacesSearcher(apiKey)` constructor.
+
+---
+
+## Adding a New Tool — 9-File Checklist
+
+From `CLAUDE.md`:
+
+| # | File | What to update |
+|---|---|---|
+| 1 | `src/tools/maps/<toolName>.ts` | Define NAME, DESCRIPTION, SCHEMA, ACTION |
+| 2 | `src/config.ts` | Add to `tools[]` array with annotations |
+| 3 | `src/cli.ts` | Add to `EXEC_TOOLS` const + `switch` case in `execTool()` |
+| 4 | `tests/smoke.test.ts` | Add to `expectedTools` array + update tool count assertions |
+| 5 | `README.md` | Update tool count (header, comparison table, Server Info, exec mode) + Available Tools table + Project Structure |
+| 6 | `skills/google-maps/SKILL.md` | Add row to Tool Map table |
+| 7 | `skills/google-maps/references/tools-api.md` | Add parameter docs + chaining patterns |
+| 8 | `server.json` | Update description if it mentions tool count |
+| 9 | `package.json` | Update description if it mentions tool count |
+
+Missing any file causes doc/behavior mismatch. Verify all before opening a PR.
+
+---
+
+## Code Map
+
+| File | Purpose |
+|---|---|
+| `src/cli.ts` | CLI entry point — parses args, selects transport, dispatches exec mode |
+| `src/config.ts` | Assembles ToolConfig[] array from all tool modules |
+| `src/core/BaseMcpServer.ts` | MCP server core — tool registration, HTTP session management, stdio transport |
+| `src/index.ts` | Package entry — exports Logger and re-exports public API |
+| `src/services/PlacesSearcher.ts` | Service facade — orchestrates multi-step composite tools (planRoute, exploreArea, comparePlaces, searchAlongRoute) |
+| `src/services/toolclass.ts` | Legacy Google Maps SDK wrapper — geocode, directions, distanceMatrix, elevation, timezone, weather, airQuality, staticMap |
+| `src/services/NewPlacesService.ts` | Places API (New) client — searchNearby, searchText, getPlaceDetails via gRPC |
+| `src/tools/maps/*.ts` | Individual tool definitions (17 files) — each exports NAME, DESCRIPTION, SCHEMA, ACTION |
+| `src/utils/apiKeyManager.ts` | Singleton — resolves API key priority from headers / session / env |
+| `src/utils/requestContext.ts` | AsyncLocalStorage — propagates API key within a single request lifecycle |
+| `tests/smoke.test.ts` | Integration smoke tests — validates tool list, basic API calls |

package/skills/project-docs/references/decisions.md

@@ -0,0 +1,149 @@
+# Architecture Decision Records — mcp-google-map
+
+> Format: Decision / Context / Rationale
+> Sources: dev-roadmap-spec.md, CLAUDE.md, project history
+
+---
+
+## ADR-001: Unified `maps_` Prefix for All Tool Names
+
+**Decision**: All tools are named with the `maps_` prefix (e.g., `maps_geocode`, `maps_search_nearby`). This was applied as a breaking change when the namespace was standardized.
+
+**Context**: Early tool names were inconsistent — some had prefixes, some did not. As the tool count grew and the server was listed on MCP registries, namespace collisions with other MCP servers became a concern. Claude's tool selection also benefits from a clear namespace signal.
+
+**Rationale**:
+- Consistent namespace prevents collision when multiple MCP servers are active simultaneously.
+- The `maps_` prefix gives Claude a strong disambiguation signal — it knows these tools are geospatial without reading descriptions.
+- Breaking change was accepted early (pre-stable) to avoid accumulating technical debt. All 9 files in the Tool Change Checklist must be updated together on any rename.
+
+---
+
+## ADR-002: `compare_places` Retained as a Composite Tool
+
+**Decision**: `maps_compare_places` is a single tool that internally fetches details for multiple places and returns a structured comparison. It is not decomposed into atomic `place_details` calls that the AI chains together.
+
+**Context**: An alternative design would have the AI call `maps_place_details` N times and synthesize the comparison itself. During testing, this produced inconsistent output quality and required users to explicitly orchestrate the chain.
+
+**Rationale**:
+- Users ask "compare these restaurants" and expect a comparison table, not raw data to synthesize.
+- Composite tools reduce chaining overhead and produce deterministic, structured output.
+- The Geo-Reasoning Benchmark (GRB) validates this: Composite Efficiency Score (CES) rewards using 1 call instead of N calls. `compare_places` is the reference case for this metric.
+- User preference confirmed: users do not want to manually chain atomic calls for comparison tasks.
+
+---
+
+## ADR-003: `maps_weather` and `maps_air_quality` as Separate Tools
+
+**Decision**: Weather and air quality are exposed as two independent tools, not combined into a single `maps_environment` tool.
+
+**Context**: A natural grouping might combine weather and air quality into one "environmental conditions" call. Both return ambient data about a location.
+
+**Rationale**:
+- **Different APIs**: Weather uses one endpoint; Air Quality uses `POST https://airquality.googleapis.com/v1/currentConditions:lookup` — a completely separate Google service requiring separate API enablement.
+- **Different geographic coverage**: Weather API does not support Japan. Air Quality API fully supports Japan (including AEROS local index). Combining them would require complex conditional logic and mislead users about availability.
+- **Different data structures and use cases**: Weather is for planning (will it rain?). Air quality is for health decisions (should I wear a mask? can elderly parents go outside?). The 7-demographic health recommendation field in air quality has no analogue in weather.
+- **Independent billing**: Separate pricing makes cost attribution cleaner.
+
+---
+
+## ADR-004: `maps_isochrone` Not Built
+
+**Decision**: Isochrone generation (travel-time polygons) is excluded from the roadmap, marked as "Skip for now."
+
+**Context**: Isochrones are a commonly requested GIS feature — "show me everywhere I can reach in 30 minutes." They are valuable for real estate analysis, event planning, and accessibility research.
+
+**Rationale**:
+- **Google has no native isochrone API.** All alternative implementations have disqualifying problems:
+  - Mapbox Isochrone API: mature, but introduces a second vendor (Mapbox key) alongside Google — breaks the single-provider positioning.
+  - OpenRouteService: free but rate-limited and stability uncertain for production use.
+  - Distance Matrix grid approximation: 24+ API calls per isochrone at ~$0.12/request; prohibitively expensive and low-accuracy.
+- **Core value is visual**: An isochrone polygon is only meaningful when rendered on a map. Without `maps_static_map` to display it, returning raw GeoJSON coordinates is not useful to AI or users. The feature was deprioritized until static map rendering was in place.
+- **Revisit path**: If built later, the best approach is Distance Matrix 8-direction probing + `maps_static_map` to render an approximated polygon. Estimated effort: 8 hours.
+
+---
+
+## ADR-005: `maps_validate_address` Not Built
+
+**Decision**: Address validation (checking if a postal address is deliverable) is excluded from the tool set.
+
+**Context**: Google's Address Validation API provides USPS CASS-certified validation, deliverability flags, and address correction. It could theoretically be useful for any tool that takes address inputs.
+
+**Rationale**:
+- **Cost**: $17 per 1,000 requests — 3.4× the cost of standard geocoding. This is prohibitive for conversational AI use where users make casual address queries.
+- **Wrong use case**: Address validation is designed for backend pipelines (e-commerce checkout, CRM deduplication, bulk mailing). It requires structured postal input and returns structured postal corrections — not a natural fit for natural-language AI conversations.
+- **Coverage gap**: Only 38 countries supported; excludes most of Asia and Africa. A tool that silently fails for Tokyo or Mumbai addresses would create confusing UX.
+- **Existing alternative**: `maps_geocode` already handles 60% of "is this address valid?" scenarios by returning whether a geocode succeeded and providing the `formatted_address` canonical form.
+
+---
+
+## ADR-006: Spatial Context / Session Memory Not Built
+
+**Decision**: There is no persistent spatial context or session memory layer in the MCP server. The server does not remember previously queried locations or build a "current location" state across calls.
+
+**Context**: A proposed feature was to maintain implicit state — if a user asks "find coffee shops" after previously mentioning "I'm in Shinjuku," the server would remember Shinjuku and use it as the implicit location for the next search.
+
+**Rationale**:
+- **Claude's conversation history already solves this.** Claude reads its own prior messages and can extract previously mentioned locations. A server-side memory layer would duplicate capability that already exists in the LLM.
+- **Composite tools reduce chaining need.** Tools like `maps_explore_area` and `maps_plan_route` accept multi-intent inputs that would otherwise require chaining with location state.
+- **Implementation risks outweigh benefits**:
+  - Implicit state leakage: state from one user's session could bleed into another in concurrent scenarios.
+  - Debugging opacity: errors become harder to trace when the server has hidden state.
+  - stdio transport has no session concept — each stdio connection is stateless by design.
+- **User value assessed at 3/10.** In testing, users could not perceive a meaningful difference. The friction of unexpected state (wrong implicit location) outweighed the convenience.
+
+---
+
+## ADR-007: stdio as Primary Transport
+
+**Decision**: The MCP server uses stdio (standard input/output) as its primary transport mechanism. HTTP/SSE is secondary.
+
+**Context**: MCP servers can expose transport via stdio (subprocess model) or HTTP+SSE (network server model). Both are valid per the MCP specification.
+
+**Rationale**:
+- **MCP Registry requirement**: The official MCP registry and most client integrations (Claude Desktop, Claude Code, Cursor) prefer or require stdio-based servers for local installation.
+- **Security model**: stdio servers run as a subprocess of the client, inheriting the client's trust context. No network port exposure, no authentication complexity.
+- **Deployment simplicity**: `npx mcp-google-map` works out of the box without configuring ports, firewalls, or SSL.
+- **Statelessness aligns with stdio**: Each stdio connection represents one session. This reinforces ADR-006 (no spatial context) — the transport model naturally discourages stateful designs.
+
+---
+
+## ADR-008: Search Along Route Uses Direct REST Calls
+
+**Decision**: The "search along route" capability calls the Google Maps REST API directly rather than using the official `@googlemaps/google-maps-services-js` client library.
+
+**Context**: Most tools in this project use the official client library for consistency and type safety. The route-based search requires fetching a polyline and then querying points along it — a pattern not natively supported by the client library.
+
+**Rationale**:
+- **Client library may not expose the required parameters or patterns** for buffered route searches. The REST API is always the source of truth; the client library is a convenience wrapper.
+- **Direct REST calls are straightforward**: for GET requests with query parameters, `axios` or `fetch` is sufficient and keeps the implementation explicit.
+- **Type safety can be maintained** by defining TypeScript interfaces for the REST response shapes — same outcome as using the library, without library constraints.
+- This is an exception to the general project preference for the client library, justified by the specific technical requirement.
+
+---
+
+## ADR-009: MCP Prompt Templates Removed
+
+**Decision**: MCP Prompt Templates (slash commands like `/travel-planner`) were evaluated and ultimately not shipped as a feature.
+
+**Context**: The roadmap spec (P1-1) proposed implementing MCP's `prompts` primitive to expose slash commands in clients like Claude Desktop. The intended value was giving non-technical users a one-click entry into geo agent mode.
+
+**Rationale**:
+- **Client support is low and inconsistent.** As of evaluation, most MCP clients either do not render prompt templates as slash commands or render them inconsistently. The feature would benefit a small fraction of users.
+- **SKILL.md already covers the use case** for Claude Code users — the skill system provides rich scenario guidance, chaining patterns, and example recipes that go beyond what prompt templates support.
+- **Maintenance cost**: Prompt template content would need to stay in sync with tool capabilities, adding to the already-significant 9-file update checklist (CLAUDE.md ADR).
+- **Revisit condition**: If MCP client support for prompts reaches broad adoption (Claude Desktop, VS Code extension, Cursor all render them consistently), this should be reconsidered. The 6-hour implementation estimate is low.
+
+---
+
+## ADR-010: Travel Planning Uses "Tool-Driven Diffusion," Not AI Prior Knowledge
+
+**Decision**: Travel planning workflows are designed so the AI discovers ground truth by calling tools, not by relying on training-data knowledge of specific places, hours, or transit schedules.
+
+**Context**: An AI could answer "what time does Kinkaku-ji open?" from training data. It could suggest a Tokyo itinerary without any tool calls based on memorized "best of Tokyo" patterns. This is faster but fragile.
+
+**Rationale**:
+- **Training data goes stale.** Business hours change, places close, new venues open. A tool call to `maps_place_details` returns current data; training knowledge reflects a past snapshot.
+- **Specificity requires data.** A user asking for restaurants near their hotel requires the actual hotel coordinates, not generic neighborhood knowledge. The tool call chain (geocode hotel → search nearby → get details) produces a personalized result that training data cannot replicate.
+- **Verifiability and trust.** When the AI cites data from a tool response (e.g., "Fushimi Inari opens at 6 AM according to Google Maps"), users can verify the source. When it speaks from training data, there is no audit trail.
+- **The SKILL.md geo-domain knowledge** (temple hours, transit rules, energy curves) is intentionally at the *pattern* level — it tells the AI *how* to plan, not *what* specific facts are. The facts come from tools. This separation is the core design principle.
+- Practical implementation: always geocode place names (don't assume coordinates), always fetch operating hours from `maps_place_details` (don't assume 9–5), always calculate transit time with `maps_directions` (don't estimate from distance).