🔧Understand Tool Use in AI Agents
Stop debugging agents by shouting 'why did it pick that tool' — separate the contract into schema, selection, and execution so each can fail (and be fixed) independently. By the end you'll design two tools for one of your own products with names, schemas, and descriptions you can defend in review.
Phase 1The Three-Part Contract: Schema, Selection, Execution
What tool use is and the three-part contract
Tool use is a contract, not a capability
6 minThe LLM never runs your tool. It emits structured arguments; you run the tool; you feed the result back. Three roles, one round trip.
The schema is the only thing the model sees
7 minThe model never reads your tool's source code. It picks tools and fills in arguments using only the name, description, and JSON Schema you wrote. Whatever you didn't say there, the model doesn't know.
Selection is search, not reasoning
7 minWhen the model picks a tool, it's pattern-matching the user's request against your tool descriptions — not deliberating like a programmer. Treat selection as a retrieval problem.
Execution is yours; the model is just waiting
7 minOnce the model emits tool_use, it stops. Nothing happens until your runtime calls the function and returns a tool_result. Every error, retry, timeout, and side effect lives in your code, not the model's.
Phase 2One Turn, End to End
Trace one tool-use turn end to end
Walk one turn — the four messages that matter
7 minA single tool-use turn is exactly four messages: user, assistant (with tool_use), user (with tool_result), assistant (final). Memorize the shape and you can debug any agent by inspecting the transcript.
Write a real schema — get_order_status
7 minA good JSON Schema is small, typed, and described at the field level. Every property gets a description; every required field is required for a reason.
Watch the model pick — and pick wrong
7 minMost wrong-tool selections come from missing 'when to use' clauses or from descriptions that are functional ('does X') instead of intentional ('use when user wants Y').
Return a useful tool_result, not a raw payload
7 mintool_result content is a message to the model. Pre-digest it: trim, format, summarize. The model reads tool_result with the same tokens-and-attention budget as user text.
The model keeps calling tools until you stop it
7 minAn agent loop is just: send messages, get response, if response contains tool_use, run tools, append results, repeat. The loop ends when the response has no tool_use or when you decide enough is enough.
Phase 3Production Failures: Descriptions, Parallelism, Errors, Stops
Descriptions, parallelism, errors, and stop conditions
Two parallel calls — when to encourage them, when to forbid
7 minModern models can emit multiple tool_use blocks in one assistant turn. That cuts latency for independent calls but creates havoc when calls have hidden dependencies.
Tool errors are messages, not exceptions
7 minWhen a tool fails, return a tool_result with is_error: true and a plain-English explanation. The model handles errors gracefully when you tell it the truth in a format it can read.
Stop conditions: budgets, signals, and forced answers
7 minAn agent without explicit stop conditions runs until you run out of patience or budget. Define the stop conditions you want and engineer them — don't hope the model figures them out.
Audit a tool description in 90 seconds
7 minA good tool description answers four questions in 3-5 sentences: what does it do, when do you call it, when do you NOT call it, and what does the user need to provide. Most descriptions answer only one.
Phase 4Capstone: Two Tool Designs You Can Defend
Design two real tools for your own product
Design two tools for one of your products
8 minDesign two tools for one of your products
Frequently asked questions
- What is tool use in an LLM agent?
- This is covered in the “Understand Tool Use in AI Agents” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
- Why does my agent pick the wrong tool or hallucinate arguments?
- This is covered in the “Understand Tool Use in AI Agents” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
- What's the difference between tool use and function calling?
- This is covered in the “Understand Tool Use in AI Agents” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
- How do I write a good tool description for an LLM?
- This is covered in the “Understand Tool Use in AI Agents” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
- How do parallel tool calls work and when should I use them?
- This is covered in the “Understand Tool Use in AI Agents” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
Related paths
🐍Python Decorators Introduction
Build one mental model for Python decorators that covers closures, argument passing, functools.wraps, and stacking — then ship a working caching or logging decorator from scratch in under 30 lines.
🦀Rust Lifetimes Explained
Stop reading `'a` as line noise and start reading it as scope arithmetic — one failing snippet at a time — until you can thread lifetimes through a small parser or iterator adapter without fighting the borrow checker.
☸️Kubernetes Core Concepts
Stop drowning in 30+ resource types. Build the mental model one primitive at a time -- pods, deployments, services, ingress, config -- then deploy a real app with rolling updates and health checks.
📈Big O Intuition
Stop treating Big O as math you memorized for an interview — build the intuition to spot O(n²) disasters, pick the right data structure without thinking, and rewrite a slow function from O(n²) to O(n) in under five minutes.