Module 7: Tools & APIs•Lesson 3 of 5

Common Failure Patterns

Learn from these mistakes so you don't make them.

Pattern 1: Tool Hallucination

Symptom: Agent "uses" a tool that doesn't exist

Agent: "Let me use the email_send tool to..."
(There is no email_send tool)

Cause: Agent doesn't know what tools are available

Fix: Ensure tool list is in system prompt; be explicit about available tools

Pattern 2: Wrong Tool Choice

Symptom: Agent uses a tool that can't solve the problem

User: "What's my next meeting?"
Agent: web_search("my next meeting")
(Searches the public web, not your calendar)

Cause: Tool descriptions are unclear or missing context

Fix: Better tool descriptions; provide examples of when to use each

Pattern 3: Tool Overuse

Symptom: Agent uses tools for everything, even simple questions

User: "What's 2+2?"
Agent: exec("python -c 'print(2+2)'")

Cause: Agent is over-cautious or poorly instructed

Fix: Instructions should clarify when tools are needed vs direct response

Pattern 4: Tool Underuse

Symptom: Agent hallucinates data instead of fetching it

User: "What's the current EUR/USD rate?"
Agent: "The EUR/USD rate is approximately 1.08..."
(Made up, could be wrong)

Cause: Agent doesn't recognize when current data is needed

Fix: Explicit rules about when to fetch vs when to use knowledge

Pattern 5: Infinite Tool Loops

Symptom: Agent keeps calling tools repeatedly

Agent: web_search("X")
Agent: web_search("X more details")
Agent: web_search("X additional info")
... forever

Cause: Agent doesn't know when to stop

Fix: Add stopping conditions; limit tool calls per turn

Pattern 6: Context Loss After Tools

Symptom: Agent forgets the conversation after using a tool

User: "Find hotels in Paris for my trip"
Agent: web_search("hotels in Paris")
Agent: "Here are some hotels. What would you like to know?"
(Forgot it's for user's specific trip)

Cause: Tool results overwhelm context

Fix: Agent should maintain context; summarize tool results

Pattern 7: Unsafe Tool Use

Symptom: Agent runs dangerous commands

Agent: exec("rm -rf /")
(Deletes everything)

Cause: No safety guardrails

Fix:

Allowlist safe commands
Require confirmation for destructive actions
Use trash instead of rm

Prevention Checklist

Tool descriptions are clear and specific
Examples show when to use each tool
Safety rules are explicit
Stopping conditions are defined
Context preservation is instructed
Dangerous operations require confirmation

Previous: The Rule of Thumb Next: Browser, Files, APIs