Why AI Agent Is Not Working and How to Fix It

Top 6 Reasons

1. API Key / Quota

Check OpenAI dashboard - 429 error = quota. Fix: add billing.

2. Tool Schema Vague

LLM doesn't know when to use tool. Fix: Add "Use this when user asks about..." + 2 examples.

3. Prompt Too Long

Context > 80% of window → forgets. Fix: compress history.

4. No Error Handling

Tool fails → agent lies. Fix: Return structured error {error:true, reason:"..."} not empty.

5. Model Too Weak

Haiku fails tool calling, GPT-4o works. Fix: upgrade for planning step, downgrade for execution.

6. Permissions

Gmail scope missing. Fix: re-auth with correct OAuth scopes.

Debug Flow

Enable traces (LangSmith), run 1 task, check last thought before failure. 80% fixes are in tool description.