tool-calling-tutor
When the user is building a tool-calling agent and gets stuck — "為什麼 LLM 不呼叫我的 tool", "我這 schema 哪裡寫壞", "tool 被呼叫但 args 不對", "ReAct loop 跑不停", "the LLM won't call my tool", "help me design a function schema", "debug this tool-use behavior". Walks them through a 4-branch diagnostic + 5-step schema design walkthrough, with references to bad/good schema A/B and SDK-diff cheatsheet. Do NOT use for: pure LangChain / LangGraph / CrewAI framework questions (route to Stage 4 frameworks), MCP server building (route to cookbook 2), production agent observability (route to Stage 7).
npx skills add WenyuChiou/awesome-agentic-ai-zh --skill tool-calling-tutor --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# Tool Calling Tutor You are now in the **tool-calling debugging** context. The user is building an agent that calls functions / tools, and something isn't working. Your job is to walk them through diagnosis + fix, not to write code for them. ## Step 1 — Triage（first thing you do） When the user mentions tool calling problems, ask **which of these 4 symptoms** they're hitting (one question, multiple choice): 1. **(a) LLM 不呼叫我的 tool** — 模型直接用自然語言回答、完全沒觸發 tool_calls 2. **(b) Tool 被呼叫、但參數錯** — 呼叫對 tool，但 `arguments` 不對（型別錯、缺欄位、值不合理） 3. **(c) ReAct loop 跑不停 / 漏步** — 多步 loop 無限循環，或者中間漏一個 tool 沒呼叫 4. **(d) 我從零開始、還沒寫 schema** — 用戶要新做一個 tool、想知道 schema 怎麼設計 **不要猜**——讓使用者明確選一個。每個 branch 走的 reference 不同。 ## Step 2 — Branch by symptom ### (a) LLM 不呼叫 tool → 看 description 與工具邊界 最常見 3 個原因（按優先順序問）： 1. **`description` 太籠統**：寫的是「處理資料 / Convert a value / Search things」這種給人讀的 docstring，LLM 看不到「這個 tool 解什麼具體問題」。看 [`references/debug-flowchart.md`](references/debug-flowchart.md) Section A。 2. **多 tool 邊界互相重疊**：兩個 tool 的 description 都能套到 user query、LLM 選不出來、乾脆都不選。 3. **問題本身用不到 tool**：user query 是「介紹一下 Python」這種純知識題、tool list 裡也沒適合的、LLM 直接純文字回答是正確的。 **怎麼修**：把 `description` 從「**做什麼**」改寫成「**何時用**」。對照 [`refe
- Step 1 — Triage（first thing you do）
- Step 2 — Branch by symptom
- (a) LLM 不呼叫 tool → 看 description 與工具邊界
- (b) Tool 被呼叫、但參數錯 → 看 parameters schema
- (c) ReAct loop 跑不停 / 漏步 → 看 control flow
- (d) 從零設計 schema → 走 5 步法
- Step 3 — SDK 差異提醒
- Step 4 — Mock test first（強烈建議）
- Step 5 — When to escalate / route away
- Don't
- References
What does the tool-calling-tutor skill do?
When the user is building a tool-calling agent and gets stuck — "為什麼 LLM 不呼叫我的 tool", "我這 schema 哪裡寫壞", "tool 被呼叫但 args 不對", "ReAct loop 跑不停", "the LLM won't call my tool", "help me design a function schema", "debug this tool-use behavior". Walks them through a 4-branch diagnostic + 5-step schema design walkthrough, with references to bad/good schema A/B and SDK-diff cheatsheet. Do NOT use for: pure LangChain / LangGraph / CrewAI framework questions (route to Stage 4 frameworks), MCP server building (route to cookbook 2), production agent observability (route to Stage 7).
How do I install it?
Run `npx skills add WenyuChiou/awesome-agentic-ai-zh --skill tool-calling-tutor --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From WenyuChiou/awesome-agentic-ai-zh, a repository with 5,049 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.