**Symptom:** Tools raise exceptions or return errors

**Causes:**
- Invalid arguments from model
- Missing files or permissions
- Type mismatches

**Solutions:**
1. Validate tool arguments before execution
2. Add try/except in tool implementations
3. Return structured errors: `{"error": "..."}`
4. Improve tool descriptions so model sends correct args

**Debug:**
```python
def dispatch_tool(name: str, args: dict) -> dict:
  print(f"🔍 Dispatching: {name}")
  print(f"   Args: {args}")
  print(f"   Types: {[(k, type(v).__name__) for k, v in args.items()]}")
  
  try:
      result = tool_map[name](**args)
      print(f"   ✅ Success: {result}")
      return result
  except Exception as e:
      print(f"   ❌ Error: {e}")
      return {"error": str(e)}
```
            

              **Symptom:** Agent just talks about what it would do

**Causes:**
- Tool descriptions are unclear
- Model doesn't understand when to use tools
- Instructions don't encourage tool use

**Solutions:**
1. Improve tool descriptions - be specific about when to use each tool
2. Add examples in tool descriptions
3. Update instructions: "Use tools for all file operations"
4. Try a different model (some are better at tool calling)

**Debug:**
```python
# Check if tools are being sent to model
print(f"\n🔧 Available tools: {[t['name'] for t in tools]}")

# After model response
if not message.tool_calls:
  print("⚠️  No tool calls - agent chose not to use tools")
  print(f"   Response: {message.content[:200]}")
```
            

              **Symptom:** Agent doesn't handle denials well

**Causes:**
- Agent doesn't see the denial result
- Agent retries the same operation
- No guidance on what to do when denied

**Solutions:**
1. Return clear denial message: `{"status": "denied_by_user", "reason": "..."}`
2. Update instructions to handle denials gracefully
3. Log denials for analysis

**Debug:**
```python
def approve(tool_name: str, args: dict) -> bool:
  print(f"\n⚠️  Approval needed: {tool_name}")
  ans = input("Approve? [y/N] ").strip().lower()
  
  if ans != "y":
      print("❌ Denied - agent will see this in tool result")
      return False
  
  print("✅ Approved")
  return True
```