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.en.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 (the first thing you do)
When the user mentions a tool-calling problem, 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 won't call my tool** — model answers in natural language, no `tool_calls` triggered
2. **(b) Tool is called, but args are wrong** — right tool, but `arguments` are off (wrong type, missing field, nonsensical value)
3. **(c) ReAct loop won't stop / skips a step** — multi-step loop runs forever, or it skips a tool call in the middle
4. **(d) I'm starting from scratch, haven't written the schema** — user wants to build a new tool and design the schema
When the symptom is explicit, do not ask them to choose again: confirm the inferred route and continue. Each branch leads to a different reference.
## Step 2 — Branch by symptom
### (a) LLM doesn't call the tool → fix description and tool boundaries
Check these three items first:
1. **`description` is too generic**: writing "Process data / Convert a value / Search things" like a human-facing docstring — the LLM can't tell *when* this tool applies. See [debug-flowchart.en.md](${CLAUDE_SKILL_DIR}/references/debug-flowchart.en.md) Section A.
2. **Multiple tools have overlapping boundaries**: both descriptions match the user query — LLM can't pick — so it picks neither.
3. **The query genuinely doesn't need a tool**: "Tell me about Python" doesn't need any tool; pure text response is correct.
**Fix**: rewrite `description` from "**what it does**" to "**when to use it**". Compare with [schema-evolution.en.md](${CLAUDE_SKILL_DIR}/references/schema-evolution.en.md) for the bad → good A/B.
### (b) Tool called, args wrong → fix the parameters schema
Check these three items first:
1. **All params typed as `string`**: `{"value": {"type": "string"}}` — the LLM doesn't know to pass a number. Change to `{"type": "number"}`.
2. **No `required`**: the model can skip a mandatory field. List `"required": ["value", "unit"]`.
3. **Missing `enum`**: `unit: string` lets the LLM pass `"C"` / `"Celsius"` / `"celsius"` at random. Switch to `"enum": ["celsius", "fahrenheit"]`.
See [schema-evolution.en.md](${CLAUDE_SKILL_DIR}/references/schema-evolution.en.md) for the 4-step improvement.
### (c) ReAct loop won't stop / skips → check control flow
Three typical reasons a loop won't stop:
1. **Forgot to append assistant response to `messages`** — next round, the LLM can't see what it just said, infinite repeat
2. **`tool` message missing `tool_call_id`** — LLM can't pair which result goes with which call, may re-issue the call
3. **No `max_iter` safety net** — if a tool returns garbage, LLM keeps calling
Reasons for skipped steps in a multi-step task:
1. **Verify current support first**: use one fixed, simple fixture to confirm that the current SDK/client and model support tool calling. Then compare repeated results with the same fixture and settings. Do not infer capability from a model name or size.
2. **Tool description omits the prerequisite ordering**: e.g., `to_percentage` should say "Convert a ratio (e.g., 0.31) into percentage. Call this LAST after dividing." Make the order explicit.
**Compare runnable examples** → [ReAct starter](https://github.com/WenyuChiou/awesome-agentic-ai-zh/tree/main/examples/stage-3/03-react-from-scratch) and [multi-step starter](https://github.com/WenyuChiou/awesome-agentic-ai-zh/tree/main/examples/stage-3/04-multi-step-reasoning).
### (d) Designing from scratch → follow the 5-step recipe
For any new tool, do these 5 steps:
1. **Define**: one sentence on what this tool does (≤15 words). Can't write it = scope too big, split it.
2. **Describe (from the LLM's POV)**: write the description as "**Use this when the user asks to / mentions / wants** ...", not "This function ...".
3. **Type**: give each param the correct type — `number` / `boolean` / `array` / `object`. Don't default everything to `string`.
4. **Constrain**: list mandatory fields in `required`; use `enum` to collapse fuzzy boundaries; describe each field.
5. **Error pattern**: validate the tool name and args before execution. Put expected tool errors in a structured `{"error": "...", "retry_hint": "..."}` result tied to the call ID; keep unexpected exceptions visible and logged. An application-owned bounded retry policy (limits and rules) decides retries, not the 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) or [multi-turn starter.py](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/examples/stage-3/03-react-from-scratch/starter.py) — keep the `TOOLS_SPEC` + `TOOL_IMPL` structure, swap in your tool.
## Step 3 — SDK differences reminder
The user might be switching between Anthropic / OpenAI / Ollama — the SDK shape differs. See [sdk-diff.en.md](${CLAUDE_SKILL_DIR}/references/sdk-diff.en.md). If the SDK or model is unknown, ask once; then verify current tool-calling support and compare the same fixture under the same settings.
## Step 4 — Mock test first (strongly recommended)
Every tool-calling program should have mock-based tests that don't hit a real API:
- Mock the response shape of the current SDK
- Keep the model and settings fixed for the same fixture
Full mock pattern → [test.py](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/examples/stage-3/03-react-from-scratch/test.py). Get tests passing before using a real LLM.
## Step 5 — When to escalate / route away
This skill does **NOT** handle:
- **LangChain / LangGraph / CrewAI / Pydantic AI** framework questions → Stage 4
- **MCP server / client** design → [cookbook 2](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/resources/cookbook.en.md)
- **Production monitoring / observability / cost tracking** → Stage 7
- **General prompt engineering** → Stage 2
If the user asks about any of these, tell them "this skill handles tool-use mechanics; your question needs Stage X — see ..." and route — don't try to absorb it.
## Don't
- **Don't just write a complete `starter.py` for them** — they need the mental model, not a copy-paste answer. Point them to [Stage 3 starters](https://github.com/WenyuChiou/awesome-agentic-ai-zh/tree/main/examples/stage-3) and their `TOOLS_SPEC`.
- **Don't re-ask Step 1 when the symptom is explicit** — confirm the route, then continue; ask only when it is unclear.
- **Don't assume an SDK or model** — verify current tool-calling support first.
- **Don't recite all schema-design rules** — [the schema cheatsheet](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/resources/schema-design-cheatsheet.en.md) already has them.
## References
- [debug-flowchart.en.md](${CLAUDE_SKILL_DIR}/references/debug-flowchart.en.md) — 4-symptom diagnostic for "why won't the LLM call my tool"
- [schema-evolution.en.md](${CLAUDE_SKILL_DIR}/references/schema-evolution.en.md) — Bad → good schema worked example (4 improvements)
- [sdk-diff.en.md](${CLAUDE_SKILL_DIR}/references/sdk-diff.en.md) — Anthropic vs OpenAI-compat side-by-side
- [schema-design-cheatsheet.en.md](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/resources/schema-design-cheatsheet.en.md) — 5 golden rules + 5 anti-patterns
- [glossary.en.md](https://github.com/WenyuChiou/awesome-agentic-ai-zh/blob/main/resources/glossary.en.md) — Agent / Tool Use / ReAct term definitions
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 |