Skip to content

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

Merged
cablate merged 3 commits intomainfrom
fix/skill-tool-name-alignment
Mar 17, 2026
Merged

fix: align skill tool names with actual MCP names#52
cablate merged 3 commits intomainfrom
fix/skill-tool-name-alignment

Conversation

@cablate
Copy link
Copy Markdown
Owner

@cablate cablate commented Mar 17, 2026

Summary

Skill 文件裡的 tool 名稱(如 search-along-route)與實際 MCP 註冊名稱(maps_search_along_route)不一致,導致 AI agent 在測試中無法找到工具。

Changes

  • SKILL.md: Tool Map 表所有名稱改為實際 MCP tool name(maps_ prefix + 底線)
  • references/tools-api.md: 所有 section header、exec 範例、chaining patterns、recipe steps 對齊實際名稱
  • references/travel-planning.md: 所有 tool reference 對齊實際名稱

Also added

  • Known API Limitations section — maps_weather 不支援日本/中國/韓國,maps_distance_matrix transit 模式在日本回 null
  • 刪除過時的 "Future Composite Tools" section(三個 composite tools 都已實作)
  • Recipe 7 改為優先使用 maps_search_along_route

Context

在 6 組 travel-planning 實測中發現:AI 讀了 Skill 後搜尋 search-along-route,但實際 tool 名稱是 maps_search_along_route,導致完全找不到工具,只能 fallback 到 midpoint maps_search_nearby

Test plan

  • Build passes
  • 132 smoke tests pass
  • Prettier format check passes

🤖 Generated with Claude Code

cablate and others added 2 commits March 17, 2026 13:48
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>
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>
@cablate cablate force-pushed the fix/skill-tool-name-alignment branch from c3251b9 to 21dc54f Compare March 17, 2026 05:56
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>
@cablate cablate merged commit f97c158 into main Mar 17, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant