WenyuChiou/awesome-agentic-ai-zh / examples/stage-5/tool-calling-tutor
tool-calling-tutor
VerifiedUse when a tool-calling agent does not call a tool, sends wrong arguments, loops without stopping, or needs a function schema. Guides a four-branch diagnosis and five-step schema repair. Do not use for framework-specific, MCP-server, or production-observability questions.
| File | Kind | Size |
|---|---|---|
| README.en.md | markdown | 8.1 KB |
| README.md | markdown | 7.9 KB |
| README.zh-Hans.md | markdown | 8.0 KB |
| SKILL.md | skill md | 7.8 KB |
| evals/check_evals.py | script | 3.9 KB |
| evals/evals.json | config | 2.7 KB |
| references/debug-flowchart.en.md | markdown | 3.6 KB |
| references/debug-flowchart.md | markdown | 3.5 KB |
| references/debug-flowchart.zh-Hans.md | markdown | 3.5 KB |
| references/schema-evolution.en.md | markdown | 3.4 KB |
| references/schema-evolution.md | markdown | 3.2 KB |
| references/schema-evolution.zh-Hans.md | markdown | 3.2 KB |
| references/sdk-diff.en.md | markdown | 4.5 KB |
| references/sdk-diff.md | markdown | 4.5 KB |
| references/sdk-diff.zh-Hans.md | markdown | 4.5 KB |
| translations/SKILL.en.md | markdown | 8.0 KB |
| translations/SKILL.zh-Hans.md | markdown | 8.0 KB |
translations/SKILL.zh-Hans.md
View on GitHub---
name: tool-calling-tutor
description: >-
Use when a tool-calling agent does not call a tool, sends wrong arguments,
loops without stopping, or needs a function schema. Guides a four-branch
diagnosis and five-step schema repair. Do not use for framework-specific,
MCP-server, or production-observability questions.
---
# 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, first infer the route from an explicit symptom and briefly confirm it. Ask one multiple-choice question only when the symptom is not explicit:
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 解什么具体问题”。看 [debug-flowchart.zh-Hans.md](${CLAUDE_SKILL_DIR}/references/debug-flowchart.zh-Hans.md) Section A。
2. **多 tool 边界互相重叠**:两个 tool 的 description 都能套到 user query、LLM 选不出来、干脆都不选。
3. **问题本身用不到 tool**:user query 是“介绍一下 Python”这种纯知识题、tool list 里也没适合的、LLM 直接纯文字回答是正确的。
**怎么修**:把 `description` 从“**做什么**”改写成“**何时用**”。对照 [schema-evolution.zh-Hans.md](${CLAUDE_SKILL_DIR}/references/schema-evolution.zh-Hans.md) 的 bad → good A/B。
### (b) Tool 被调用、但参数错 → 看 parameters schema
先检查这 3 项:
1. **参数类型全用 `string`**:`{"value": {"type": "string"}}` LLM 不知道要传 number。改成 `{"type": "number"}`。
2. **没有 `required`**:模型可能漏传必填字段。明列 `"required": ["value", "unit"]`。
3. **enum 该用没用**:`unit: string` 让 LLM 传 `"C"` `"Celsius"` `"celsius"` 都有可能。改 `"enum": ["celsius", "fahrenheit"]`。
**对照** [schema-evolution.zh-Hans.md](${CLAUDE_SKILL_DIR}/references/schema-evolution.zh-Hans.md) 的 4 个改进。
### (c) ReAct loop 跑不停 / 漏步 → 看 control flow
跑不停的 3 个典型原因:
1. **忘记把 assistant response 加回 `messages`**——下轮 LLM 看不到自己上轮讲过什么、会无限重复
2. **`tool` message 没带 `tool_call_id`**——LLM 无法配对哪个 result 对应哪个 call、可能重新发起 tool call
3. **没设 `max_iter` safety net**——当 tool 结果写得不好、LLM 会无限调用
漏步(多步任务中间少一步)的原因:
1. **先确认当前支持**:用一个固定的简单 fixture 确认当前 SDK/client 与 model 支持 tool calling;再在相同 fixture、相同设置下比较多次结果。不要从 model 名称或大小推断能力。
2. **Tool description 没讲“必要前置”**:譬如 `to_percentage` 应该写“Convert a ratio (e.g., 0.31) into percentage. Call this LAST after dividing.”明示顺序。
**对照可跑范例** → [ReAct starter](https://github.com/WenyuChiou/awesome-agentic-ai-zh/tree/main/examples/stage-3/03-react-from-scratch) 跟 [multi-step starter](https://github.com/WenyuChiou/awesome-agentic-ai-zh/tree/main/examples/stage-3/04-multi-step-reasoning)。
### (d) 从零设计 schema → 走 5 步法
对任何新 tool,按这 5 步:
1. **Define**:一句话讲这个 tool 做什么(不超过 15 字)。写不出来 = tool scope 太大、要拆。
2. **Describe(LLM 视角)**:把 description 写成“**Use this when the user asks to / mentions / wants** ...”格式,不是“This function ...”。
3. **Type**:每个 param 用正确 type — `number` / `boolean` / `array` / `object`,不要全 `string`。
4. **Constrain**:`required` 列必填字段;模糊边界用 `enum` 收敛;`description` 补字段用途。
5. **Error pattern**:执行前验证 tool 名称与 args。把预期的 tool 错误放进关联 call ID 的 `{"error": "...", "retry_hint": "..."}` 结构化结果;非预期异常必须可见并写入 log。重试由应用的有界 policy(次数与规则)决定,不由 LLM 决定。
**Fork template**:直接 copy [single-turn starter.py](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/examples/stage-3/02-multi-tool-selection/starter.py) 或 [multi-turn starter.py](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/examples/stage-3/03-react-from-scratch/starter.py) 的 `TOOLS_SPEC` + `TOOL_IMPL` 结构、改成你的 tool。
## Step 3 — SDK 差异提醒
用户可能在 Anthropic / OpenAI / Ollama 之间切换、SDK shape 不同。看 [sdk-diff.zh-Hans.md](${CLAUDE_SKILL_DIR}/references/sdk-diff.zh-Hans.md) 的 3 行对照表。若未说明 SDK 或 model,问一次;接着用固定 fixture 确认当前 tool-calling 支持,并做同条件比较。
## Step 4 — Mock test first(强烈建议)
每个 tool-calling 程序都应该有 mock-based test、不打真 API:
- 依当前 SDK mock 对应的 response shape
- 对同一 fixture 保持 model 与设置一致
完整 mock pattern 对照 [test.py](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/examples/stage-3/03-react-from-scratch/test.py)。先把 test 跑通、再连真的 LLM。
## Step 5 — When to escalate / route away
这个 skill **不**处理:
- **LangChain / LangGraph / CrewAI / Pydantic AI** 等 framework 问题 → 路 Stage 4
- **MCP server / client** 设计 → 路 [cookbook 2:写你的第一个 MCP server](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/resources/cookbook.zh-Hans.md)
- **Production 监控 / observability / cost tracking** → 路 Stage 7
- **Prompt engineering 一般技巧** → 路 Stage 2
碰到这些情境、直接告诉用户“这个 skill 处理 tool-use mechanics、你这个问题需要 Stage X、建议去看 ...”、不要硬吃下去。
## Don't
- **不要直接帮用户写一整份 starter.py**——他们需要练 mental model、不是拿到答案 copy-paste。指他们 fork [Stage 3 starters](https://github.com/WenyuChiou/awesome-agentic-ai-zh/tree/main/examples/stage-3) 后改 `TOOLS_SPEC`。
- **症状已明确时不要重问 Step 1**——确认路线后继续;不明确才提问。
- **不要假设 user 用哪个 SDK 或 model**——先确认当前 tool-calling 支持。
- **不要把 schema-design 规则背一遍**——[schema cheatsheet](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/resources/schema-design-cheatsheet.zh-Hans.md) 已经写好,指过去就行。
## References
- [debug-flowchart.zh-Hans.md](${CLAUDE_SKILL_DIR}/references/debug-flowchart.zh-Hans.md) — “为什么 LLM 不调用我的 tool”4-symptom 诊断
- [schema-evolution.zh-Hans.md](${CLAUDE_SKILL_DIR}/references/schema-evolution.zh-Hans.md) — Bad → Good schema worked example(4 个改进步骤)
- [sdk-diff.zh-Hans.md](${CLAUDE_SKILL_DIR}/references/sdk-diff.zh-Hans.md) — Anthropic vs OpenAI-compat 并排表
- [schema-design-cheatsheet.zh-Hans.md](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/resources/schema-design-cheatsheet.zh-Hans.md) — 5 条黄金规则 + 5 个 anti-pattern
- [glossary.zh-Hans.md](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/resources/glossary.zh-Hans.md) — Agent / Tool Use / ReAct 名词定义
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |