SuperAPI AI Directory
Partner中文AI newsFavorites
Skillstool-calling-tutor

tool-calling-tutor

Agents & models

View repository

Updated 10-16 09:05

About this skill

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) The LLM does not call my tool — the model answers directly in natural language and does not trigger tool_calls at all
  2. (b) The tool is called, but the arguments are wrong — it calls the right tool, but arguments is wrong (wrong type, missing field, unreasonable value)
  3. (c) The ReAct loop runs forever / skips a step — a multi-step loop runs infinitely, or a tool in the middle is skipped and not called
  4. (d) I am starting from scratch and have not written a schema yet — the user wants to create a new tool and wants to know how to design the schema

There is no need to ask again about clear symptoms; after confirming your inferred route, continue directly. Each branch follows a different reference.

Step 2 — Branch by symptom

(a) The LLM does not call the tool → look at the description and tool boundaries

First check these 3 items:

  1. description too vague: it says something like "process data / Convert a value / Search things", a docstring meant for humans to read, and the LLM cannot see "what specific problem this tool solves". See debug-flowchart.md Section A。
  2. Multiple tool boundaries overlap: the descriptions of two tools both fit the user query, the LLM cannot choose, and simply chooses neither.
  3. The question itself does not need a tool: the user query is a pure knowledge question like "introduce Python", and there is no suitable tool in the tool list, so the LLM answering directly in plain text is correct.

How to fix: rewrite description from "what it does" to "when to use it". Compare with the bad → good A/B of schema-evolution.md .

(b) The tool is called, but the arguments are wrong → look at the parameters schema

First check these 3 items:

  1. All parameter types use string：{"value": {"type": "string"}} The LLM does not know it needs to pass a number. Change to {"type": "number"}。
  2. There is no required: the model may omit required fields. Explicitly list "required": ["value", "unit"]。
  3. enum should be used but is not：unit: string lets the LLM pass "C" "Celsius" "celsius" are all possible. Change to "enum": ["celsius", "fahrenheit"]。

Compare schema-evolution.md 's 4 improvements.

(c) The ReAct loop runs forever / skips a step → look at control flow

The 3 typical reasons it runs forever:

  1. Forgetting to add the assistant response back to messages— the next round the LLM cannot see what it said in the previous round and will repeat infinitely
  2. tool The message does not carry tool_call_id— the LLM cannot match which result corresponds to which call and may initiate the tool call again
  3. Not setting max_iter safety net— when the tool result is poorly written, the LLM will call it infinitely

Reasons for skipping a step (missing one step in the middle of a multi-step task):

  1. First confirm what is currently supported: use a fixed simple fixture to confirm that the current SDK/client and model support tool calling; then compare each result with the same fixture and the same settings. Do not infer capability from the model name or size.
  2. The tool description does not state the "required prerequisite": for example, to_percentage should say "Convert a ratio (e.g., 0.31) into percentage. Call this LAST after dividing." to make the order explicit.

Compare runnable examples → ReAct starter and multi-step starter。

(d) Designing a schema from scratch → follow the 5-step method

For any new tool, follow these 5 steps:

  1. Define: describe in one sentence what this tool does (no more than 15 characters). If you cannot write it, the tool scope is too large and needs to be split.
  2. Describe (LLM perspective): Write description as "Use this when the user asks to / mentions / wants ..." format, not "This function ...".
  3. Type: Use the correct type for each param — number / boolean / array / object, don't list everything as string。
  4. Constrain：required for required fields; converge ambiguous boundaries with enum ;description to explain each field's purpose.
  5. Error pattern: Validate tool name and args before execution. Predictable tool errors return a {"error": "...", "retry_hint": "..."}linked to the call ID; unexpected exceptions must be visible and written to the log. Retries are determined by the application's bounded policy (count and rules), not by the LLM.

Fork template: Directly copy the single-turn starter.py or multi-turn starter.py 's TOOLS_SPEC + TOOL_IMPL structure, and change it into your tool.

Step 3 — SDK Differences Reminder

Users may switch between Anthropic / OpenAI / Ollama, and the SDK shapes differ. See the 3-row comparison table for sdk-diff.md . If the SDK or model is unspecified, ask once; then use a fixed fixture to confirm current tool-calling support and make an apples-to-apples comparison.

Step 4 — Mock Test First (Strongly Recommended)

Every tool-calling program should have a mock-based test, without hitting the real API:

  • Map to the response shape according to the current SDK mock
  • Keep the model and settings consistent for the same fixture

For the full mock pattern comparison, see test.py. Get the test passing first, then connect to the real LLM.

Step 5 — When to escalate / route away

This skill does nothandle:

  • LangChain / LangGraph / CrewAI / Pydantic AI and other framework issues → route to Stage 4
  • MCP server / client design → route to cookbook 2: Write Your First MCP Server
  • Production monitoring / observability / cost tracking → route to Stage 7
  • General prompt engineering techniques → route to Stage 2

When encountering these situations, tell the user directly: "This skill handles tool-use mechanics; your question needs Stage X; I suggest you look at ..." — don't try to force it.

Don't

  • Don't write a whole starter.py for the user directly— they need to practice the mental model, not get an answer to copy-paste. Point them to fork Stage 3 starters and then modify TOOLS_SPEC。
  • Don't re-ask Step 1 when the symptoms are already clear— once the route is confirmed, continue; only ask if it's unclear.
  • Don't assume which SDK or model the user is using— first confirm the current tool-calling support.
  • Don't recite the schema-design rules again——schema cheatsheet is already written; just point to it.

References