Start with the real problem
A tool call is a structured request from the model asking ordinary software to perform an action, such as checking the weather or searching an order database.
A model can propose an action, but the application code must decide whether that action is valid and safe to execute. Tool calling is an agreed message process between model judgment and ordinary application code.
user request → model proposes call → validate and authorize → execute → return result → answerWhat you will learn
- Define tools with precise schemas and descriptions.
- Validate arguments and permissions before execution.
- Return tool results with the correct call identity.
- Design retries, timeouts, confirmation, and error handling.
How this connects to current AI systems
OpenAI, Gemini, and Claude support structured tool calls; SDKs may automate the loop, but the application code still executes and governs external actions.
1. Why This Module Exists
Every module so far has covered the AI generating text. This module covers something really different: the AI deciding to take an action — calling a tool (like checking a database, sending an email, or searching the web) instead of, or in addition to, generating a response. This is the direct bridge into how AI agents (Module 19) actually work.
2. The Idea, in Plain Language
Tool calling means giving an AI access to specific functions it can choose to use — and prompting is how you tell it what those tools do, and when it should (and shouldn’t) reach for them.
User
↓
LLM
↓
Determine whether a tool is needed
↓
Tool call (if needed)
↓
Tool result
↓
LLM
↓
Final answerThe AI doesn’t run the tool itself — it decides that a tool should be used and what to pass to it; your application actually executes the tool and returns the result.
3. Why Tool Descriptions Matter So Much
The AI decides whether and how to use a tool almost entirely based on how that tool is described to it — really similar to how a new employee would only know to use a specific system if someone explained what it does and when to reach for it.
A weak tool description
Tool name: lookup
Description: "Looks things up."Vague and unhelpful — the AI has almost no signal about what kinds of questions this tool is actually meant to answer, or when it should be preferred over just answering directly.
A strong tool description
Tool name: check_order_status
Description: "Looks up the current shipping status of a customer's
order using their order number. Use this whenever a customer asks
about the status, location, or expected delivery of a specific order.
Do NOT use this for general shipping policy questions — use the
knowledge base search tool for those instead."
Parameters: order_number (string, required)This tells the AI precisely when to use it, when not to (a direct, useful distinction from a similar-sounding tool), and exactly what input it needs.
4. When to Use a Tool vs. When Not To
This is a really important, often under-specified decision. Without clear guidance, an AI might reach for a tool unnecessarily, or fail to use one when it actually should.
"Use the check_order_status tool ONLY when the customer provides or
can provide a specific order number. If they haven't mentioned an
order number, ask for one first — do not guess or call the tool with
incomplete information.
For general questions about shipping policy (not a specific order),
answer directly using your own knowledge — do not call this tool."This kind of explicit boundary — what qualifies for tool use, what doesn’t, and what to do about missing required information — directly prevents both common failure directions: over-using a tool unnecessarily, and under-using one when it’s really needed.
5. Required Parameters and Validation
Tools typically need specific pieces of information to work correctly. Prompting should make clear what’s required, and what to do if something’s missing:
"The check_order_status tool requires an order_number. If the
customer's message doesn't include one, ask them for it directly
before attempting to call the tool. Never call the tool with a
guessed or placeholder order number."This prevents a really real failure mode: the AI calling a tool with made-up or incomplete information just to “try something,” producing an unreliable or outright wrong result.
6. A Real Example From a Developer’s Perspective
Say you’re building a customer support assistant with access to several tools:
System instructions:
You have access to these tools:
1. check_order_status(order_number): Use when the customer asks about
a SPECIFIC order's shipping status. Requires an order number -- ask
for one if not provided.
2. search_knowledge_base(query): Use for GENERAL policy or product
questions not tied to a specific order (return policy, shipping
times, product specs).
3. issue_refund(order_number, amount): Use ONLY after confirming with
check_order_status that the order qualifies for a refund per
policy. NEVER call this without first checking eligibility.
Rules:
- Always prefer answering directly if you're confident and no tool is
really needed.
- Never call issue_refund without first calling check_order_status in
the same conversation.
- If uncertain which tool applies, ask the customer a clarifying
question instead of guessing.Notice the explicit ordering rule for issue_refund — this is
directly borrowed from Module 6’s instruction-ordering lesson, applied
specifically to tool call sequencing, which matters enormously once
tools can take real, high-impact actions.
7. A Simple Agentic AI Example
Tool-use rules become the actual backbone of an agent’s operational behavior — this is where prompt engineering starts to overlap heavily with genuine agent design (Module 19 covers this fully):
"You are a scheduling agent with access to check_availability and
book_room tools.
Before calling book_room, you MUST have already called
check_availability for the same time slot in this conversation.
Never book a room without confirming availability first.
If check_availability shows no rooms free, suggest the next available
slot instead of failing silently -- do not call book_room at all in
that case."This single instruction block is doing real, safety-relevant work: enforcing a required sequence (check before booking) and defining fallback behavior for a specific failure case (no rooms available) — exactly the kind of precise, consequence-aware instruction real agents depend on.
8. How Is This Used in AI?
🤖 How Is This Used in AI?
Tool calling is the mechanism behind essentially every AI agent and “AI that can take actions” product — customer support bots that check real order data, coding assistants that can run code, scheduling assistants that check and book calendars. The reliability of all of these depends directly on well-engineered tool descriptions and usage rules, exactly as covered in this module.
9. When Should You Focus on This?
- Any time you’re building an AI system with access to real tools or functions, not just text generation
- Any time a tool call has real consequences (booking something, refunding money, sending a message) — the stakes make clear usage rules really important
- Any time you have multiple, similarly-named tools that could be confused for each other
10. When Is This Less Relevant?
- Simple, text-only prompts with no tool access at all — nothing here applies
11. Common Mistakes
Incorrect idea
Writing vague tool descriptions.
Why it is incorrect
As shown directly, “looks things up” gives the AI almost no useful signal — be as specific as you’d be explaining the tool to a new coworker.
Incorrect idea
Not specifying what NOT to use a tool for
Why it is incorrect
, especially when multiple tools could plausibly seem relevant to the same request. Explicit boundaries (as in the order-status vs. knowledge-base example) prevent this kind of confusion.
Incorrect idea
Not handling missing required parameters explicitly.
Why it is incorrect
Without guidance, the AI may call a tool with guessed or incomplete information rather than asking the user for what’s actually needed.
Incorrect idea
Not enforcing required sequencing for dependent tool calls.
Why it is incorrect
If one tool’s use should always precede another (check before booking, verify before refunding), that ordering needs to be stated explicitly — it won’t be inferred reliably on its own.
Analogy: Explaining Office Tools to a New Intern Think of prompting for tool calling like onboarding a new office intern:
- The Mistake (Vague Instructions): You show the intern the office systems and say: “Here is a desk lookup system, a phone, and a printer. Get to work.”
- The intern doesn’t know when to use what. They might call the CEO on the phone to ask about a standard return policy, or print out 1,000 blank pages.
- The Clear Guide (Optimal Tool Prompting): You give them a checklist:
- Tool A (Phone): “Use ONLY for client cancellations over $500. Requires customer_id.”
- Tool B (Database): “Use for checking shipping status. Never guess an order status from memory.”
- Policy: “Do not attempt to use the Phone tool until you have first verified the client’s record in the Database.”
- The intern doesn’t pick up the phone themselves; they look at the rules and tell you: “I need to make a phone call to customer_id 982.” You (the application wrapper) dial the number, listen, and tell the intern what was said.
📊 Visual Flowchart: The Tool Calling Lifecycle
Here is the sequence of events when an LLM decides to interact with external tools:
graph TD
classDef llm fill:#3498db,stroke:#333,stroke-width:1px,color:#fff;
classDef app fill:#2ecc71,stroke:#333,stroke-width:1px,color:#fff;
classDef tool fill:#f1c40f,stroke:#333,stroke-width:1px,color:#fff;
UserQuery["1. User Request:<br>'Where is order #4471?'"] --> LLMDecide["2. LLM Model Block:<br>Read query + Tool definitions.<br>Determine 'check_order_status' is needed."]:::llm
LLMDecide --> ToolCallPayload["3. LLM returns JSON Payload:<br>{ 'tool': 'check_order_status', 'order_number': '4471' }"]:::llm
ToolCallPayload --> AppExec["4. Application Code:<br>Intercept payload, query real database API."]:::app
AppExec --> ToolRun["5. Database Tool:<br>Fetch status: 'In Transit'"]:::tool
ToolRun --> InjectContext["6. Inject Tool Result into Messages:<br>{ 'role': 'tool', 'content': 'In Transit' }"]:::app
InjectContext --> LLMFinal["7. LLM Model Block:<br>Read original query + Tool result to write natural answer."]:::llm
LLMFinal --> UserAns["8. Response: 'Your order #4471 is currently in transit.'"]:::llm12. Limitations
- Even well-described tools and clear usage rules don’t guarantee the AI will always choose correctly — occasional misuse or missed tool calls remain possible, especially for ambiguous requests
- Prompt-level rules (like “always check before booking”) are a really important first layer, but for truly high-impact actions, many real systems add a second, code-level enforcement layer as well — similar to Module 9’s constraint discussion
- This module covers how to prompt for good tool-use decisions — the broader mechanics of tool calling APIs and formats vary by provider and are beyond prompting alone
The model proposes; the application executes
A model does not directly book a flight or query your private database.
It normally returns a structured proposal such as
get_weather({"city":"Pune"}). Your runtime—or an SDK-managed agent
loop—must validate the arguments, check the user’s permissions, execute
the real function, return its result to the model, and decide whether a
human confirmation is required.
User request → model proposes tool call → application validates
→ application executes → tool result returns to model
→ model explains the result to the userNever rely on the prompt for authorization. Enforce allowed tools, argument ranges, rate limits, secrets access, idempotency, and approval rules in code.
13. Quick Reference — The Whole Idea in One Diagram
Tool description: WHAT it does, WHEN to use it, WHEN NOT to,
WHAT parameters it needs
↓
Usage rules: required sequencing, missing-parameter handling,
"ask instead of guess" fallback
↓
AI decides: use a tool, or answer directly
↓
Reliability depends DIRECTLY on how well the above was specified14. Prompts in Code — Calling an LLM
Here’s how tool-calling prompts actually look in code — defining a tool’s description and rules, and handling the model’s decision to use it.
Example 1 — Simple
A single tool defined with a basic description, and a request that should trigger it.
import anthropic
client = anthropic.Anthropic()
tools = [{
"name": "check_order_status",
"description": "Looks up the shipping status of an order using "
"its order number. Use only when the customer "
"provides a specific order number.",
"input_schema": {
"type": "object",
"properties": {"order_number": {"type": "string"}},
"required": ["order_number"],
},
}]
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=200,
tools=tools,
messages=[{"role": "user", "content": "Where's my order #4471?"}]
)
print(response.content)Example 2 — Intermediate
Two tools with explicit “when to use / when not to” boundaries, and handling the model’s tool-use decision in code.
import anthropic
client = anthropic.Anthropic()
tools = [
{
"name": "check_order_status",
"description": "Use ONLY for questions about a SPECIFIC "
"order's status. Requires an order number.",
"input_schema": {
"type": "object",
"properties": {"order_number": {"type": "string"}},
"required": ["order_number"],
},
},
{
"name": "search_knowledge_base",
"description": "Use for GENERAL policy questions not tied to "
"a specific order (e.g. return policy).",
"input_schema": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
},
},
]
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=200,
tools=tools,
messages=[{"role": "user", "content": "What's your return policy?"}]
)
for block in response.content:
if block.type == "tool_use":
print(f"Model chose tool: {block.name} with input: {block.input}")
elif block.type == "text":
print(f"Model responded directly: {block.text}")Example 3 — Production Grade
A full tool-calling loop with a required sequencing rule enforced in
the system prompt AND checked in code — issue_refund is blocked in
code unless check_order_status was already called in this session,
exactly the defense-in-depth pattern from Module 9.
import anthropic
client = anthropic.Anthropic()
SYSTEM_PROMPT = """You have access to check_order_status and
issue_refund. NEVER call issue_refund without first calling
check_order_status for the same order in this conversation."""
tools = [
{
"name": "check_order_status",
"description": "Checks the status and refund eligibility of an order.",
"input_schema": {"type": "object",
"properties": {"order_number": {"type": "string"}},
"required": ["order_number"]},
},
{
"name": "issue_refund",
"description": "Issues a refund. Requires check_order_status "
"to have been called first for the same order.",
"input_schema": {"type": "object",
"properties": {"order_number": {"type": "string"},
"amount": {"type": "number"}},
"required": ["order_number", "amount"]},
},
]
def handle_conversation(user_message: str):
checked_orders = set() # code-level tracking, not trusting the prompt alone
messages = [{"role": "user", "content": user_message}]
response = client.messages.create(
model="claude-sonnet-4-6", max_tokens=300,
system=SYSTEM_PROMPT, tools=tools, messages=messages,
)
for block in response.content:
if block.type == "tool_use":
if block.name == "check_order_status":
checked_orders.add(block.input["order_number"])
print(f"Checking order {block.input['order_number']}...")
elif block.name == "issue_refund":
order = block.input["order_number"]
if order not in checked_orders:
# SAFETY CHECK -- enforced in code, not just the prompt
print(f"BLOCKED: refund attempted for {order} without "
f"a prior status check. Rejecting.")
continue
print(f"Issuing refund for order {order}: ${block.input['amount']}")
handle_conversation("Can I get a refund for order #4471, it never arrived?")The checked_orders set is doing real, necessary work — even though
the system prompt already states the sequencing rule, the code
independently verifies it before allowing a refund to proceed,
directly reflecting Section 12’s point that high-impact actions
deserve a second layer of enforcement beyond the prompt alone.
When to use it—and when not to
Use it when:
- fresh data or external action is required.
- a deterministic function is more reliable than model guessing.
Do not rely on it when:
- the model can answer directly from supplied information.
- a high-impact action lacks authorization or confirmation.
15. Interview Questions
Q: Why does a tool’s description matter so much for how reliably an AI uses it correctly?
Ans: The AI decides whether and how to use a tool almost entirely based on its description — a vague description (“looks things up”) gives it little signal about when the tool is actually appropriate, while a specific description stating exactly what the tool does, when to use it, when NOT to, and what parameters it needs gives the AI a much clearer basis for making the right decision, especially when multiple similar-sounding tools are available.
Q: Why is it important to specify what an AI should do when a required tool parameter is missing from the user’s message?
Ans: Without explicit guidance, the AI might call the tool with a guessed, placeholder, or incomplete value just to “try something,” producing an unreliable or incorrect result. Explicitly instructing the AI to ask the user for missing required information instead of guessing prevents this and leads to more reliable, accurate tool use.
Q: Why might a production system enforce required tool-call sequencing (like “always check status before issuing a refund”) in code, in addition to stating it in the system prompt?
Ans: Similar to Module 9’s constraint discussion, a prompt-level rule doesn’t guarantee the AI will follow it with absolute certainty on every request — for a sequencing rule protecting against a costly mistake (like issuing an unverified refund), relying on the prompt alone is a real risk. Independently tracking and enforcing the rule in code provides a second, more reliable safeguard, rather than trusting the prompt as the only line of defense.
Q: How does tool calling differ from the plain text-generation prompting covered earlier in this course?
Ans: Plain text generation asks the AI to produce a response directly. Tool calling asks the AI to decide whether an action is needed, and if so, which specific function to call and what parameters to pass — the AI’s output becomes a structured request for the surrounding application to execute, rather than the final response itself. This requires prompting not just for content, but for a really different kind of decision: whether and how to act, which is exactly the foundation AI agents (Module 19) build on.
16. What You Should Remember
- Tool descriptions need to specify what a tool does, when to use it, when NOT to, and what parameters it requires — vague descriptions produce unreliable tool-use decisions.
- Explicit rules for missing parameters and required sequencing between dependent tool calls directly prevent common, real failure modes.
- For really consequential tool calls, a prompt-level rule is a good first layer — but production systems often also enforce the same rule in code, exactly the defense-in-depth pattern from Module 9.
17. Quick Practice
Write a tool description for a send_email tool used by a customer
support assistant. Include what it does, when to use it, when NOT to,
and what should happen if required information (like a recipient
address) is missing.
18. Next Step
Next: Module 19 — Prompt Engineering for AI Agents — bringing everything from Level 3 and this module together into a complete picture of how an agent’s prompt shapes its entire behavior and control system.
- Author
- TechByteByByte Editorial Team
- Reviewed by
- TechByteByByte Admin
- Published
- Last reviewed