Agent Debugging Prompt
Prompt
Debug this AI agent issue: Agent description: {agent_description}. Expected behavior: {expected}. Actual behavior: {actual}. Error messages: {errors}. Tools available: {tools}. Recent conversation/log: {log_excerpt}. Analyze: 1) Is the system prompt clear enough? 2) Are tool definitions correct? 3) Is the agent choosing the wrong tool or wrong parameters? 4) Is context being lost? 5) Provide specific fixes.Variables
agent_description
expected
actual
errors
tools
log_excerpt
About This Prompt
Structured approach to diagnosing and fixing issues with AI agent behavior, tool use failures, and reasoning errors.
Example Output
**Agent Debug Report**
**Issue:** Agent calls search_web tool when it should use query_database for customer lookups.
**Root Cause Analysis:**
1. **System Prompt Clarity: ISSUE FOUND**
- The system prompt says 'look up customer information' but doesn't specify WHICH tool to use for customer lookups vs. general knowledge questions
- Fix: Add explicit routing rules: 'For customer data, ALWAYS use query_database. For general knowledge, use search_web.'
2. **Tool Definitions: ISSUE FOUND**
- search_web description: 'Search for information' (too broad)
- query_database description: 'Query the database' (too vague)
- Fix: search_web → 'Search the public internet for general knowledge, news, and non-company information'
- Fix: query_database → 'Query the internal customer database by name, email, or account ID. Use this for ALL customer-related lookups.'
3. **Parameter Mapping: OK**
- When the agent does use query_database, parameters are correct
4. **Context Loss: NOT AN ISSUE**
- Conversation history is preserved correctly
**Recommended Fixes (priority order):**
1. Update tool descriptions to be specific and mutually exclusive
2. Add routing examples to system prompt
3. Add a negative example: 'Do NOT use search_web for customer data'
Usage Tips
- Check tool descriptions for overlap first
- Add explicit routing rules to system prompt
- Include negative examples (what NOT to do)
- Log tool selection decisions for debugging