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 |
references/debug-flowchart.en.md
View on GitHub# Debug Flowchart: “Why won’t the LLM call my tool?”
> [繁體中文](./debug-flowchart.md) | [简体中文](./debug-flowchart.zh-Hans.md) | **English**
> Start with the symptom, then run the smallest check. This supports Step 2 in `SKILL.md`.
## Section A — Symptom (a): the LLM never produces tool_calls
The LLM saw `tools=[...]` but returned only text. Check these items:
```text
[ ] Is finish_reason "tool_calls" or "stop"?
[ ] Is message.tool_calls empty?
[ ] Does the user’s question actually need an external tool?
[ ] Does the sent schema match the current SDK format?
```
### Check these five items first
#### 1. The `description` is vague
```python
# ❌ No clear trigger
{"name": "get_data", "description": "Get data."}
# ✅ Clear trigger
{"name": "get_weather", "description": "Use this when the user asks about current weather, forecasts, or temperatures for a city."}
```
#### 2. Tool jobs overlap
```python
# ❌ search and lookup appear interchangeable
{"name": "search", "description": "Find information."}
{"name": "lookup", "description": "Look up data."}
# ✅ Each tool has a positive and negative boundary
{"name": "web_search", "description": "Use for current external information. Do not use for facts already provided by the user."}
{"name": "fact_lookup", "description": "Use for stored facts. Do not use for live news or prices."}
```
#### 3. The question does not need a tool
“What is Python?” usually does not need a weather or calculator tool. No tool call is not always a bug.
#### 4. The schema does not match the SDK
OpenAI-compatible schemas need `{"type": "function", "function": {...}}`; Anthropic schemas use `input_schema`. Clients can validate and report errors differently, so inspect the request, response, and application log.
#### 5. The current combination has no usable tool-calling support
Check the current SDK and model documentation, then run one **fixed test case (fixture)**—like asking the same test question every time. Keep the model, settings, and question unchanged when comparing. Do not infer support from a model name or size alone.
## Section B — Symptom (b): the tool is called, but its args are wrong
```python
# Expected
convert_temperature(value=32, unit="celsius")
# Possible output
convert_temperature(value="32 Celsius", unit="")
```
| What you see | Schema fix | What the app must still do |
|---|---|---|
| A number becomes text | `type: "number"` | Validate type and range again |
| A field is missing | `required` | Return a clear missing-value error |
| One unit has many spellings | `enum` | Accept only allowlisted values |
See [`schema-evolution.en.md`](schema-evolution.en.md) for the complete example.
## Section C — Symptom (c): the ReAct loop never stops
Check three things:
1. Append the complete assistant response to `messages`.
2. Return each result with the matching `tool_call_id` or `tool_use_id`.
3. Make the result self-contained, such as `{"city":"Taipei","forecast":"rain"}`, not just `"ok"`.
Every loop needs `MAX_STEPS`. Stop and report when the limit is reached; never retry forever.
## Section D — Symptom (d): a multi-step task skips a step
For example, the model divides two numbers but forgets to convert the ratio to a percentage. Check it this way:
1. Record the actual tool sequence for a fixed case.
2. State ordering in the description, such as `Call this last after dividing.`
3. Ask for a short, observable tool plan containing only steps and tool names. Do not request, store, or reveal hidden reasoning.
Runnable multi-step example: [Stage 3 multi-step reasoning](https://github.com/WenyuChiou/awesome-agentic-ai-zh/tree/main/examples/stage-3/04-multi-step-reasoning).
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: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |