> ## Documentation Index > Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt > Use this file to discover all available pages before exploring further. # Planning Modes > Understanding agent planning strategies **Planning mode** controls whether and how agents create execution plans before taking action. This is a powerful feature that can significantly improve performance on complex tasks. ## What is Planning? When planning is enabled, the agent: 1. **Analyzes the task** before taking any action 2. **Creates a step-by-step plan** of what it will do 3. **Executes the plan** methodically 4. **Adjusts the plan** if needed based on results Without planning, agents act more reactively, deciding their next step after each tool call. ## Planning Modes Cotool offers three planning modes: **No planning** - Agent acts immediately and reactively. **Behavior:** * Agent decides next action after each tool call * More exploratory, adaptive * Faster for simple tasks **Best for:** * Simple 1-3 tool call workflows * Well-defined, linear tasks * Speed-critical applications * Agents with very clear instructions **Example use case:** * Look up user in Okta → Post result to Slack * Check file hash in VirusTotal → Update Jira with score **Agent decides** whether planning would help. **Behavior:** * Agent evaluates task complexity * Plans for multi-step workflows * Acts immediately for simple tasks * Balances speed and thoroughness **Best for:** * Most agents (this is the default) * Mixed complexity workloads * When you're unsure **Example use case:** * Alert triage (may or may not need planning depending on alert type) * User requests (varies in complexity) **Always plan** before executing. **Behavior:** * Agent always creates detailed plan first * More structured, methodical * Better for complex multi-step tasks * Slightly slower but more reliable **Best for:** * Complex investigations (5+ tool calls) * Multi-system coordination * Tasks requiring specific sequencing * High-stakes workflows **Example use case:** * User offboarding (deprovisioning across 10+ systems) * Incident response coordination * Compliance audits with specific procedures ## How Planning Works ### Without Planning (Reactive) ``` Task: "Tell me about the IP 8.8.8.8" Step 1: Agent thinks "I should check IP_lookup" → calls ip_lookup Step 3: Agent has enough info → responds ``` **Pros:** Low latency, good for extremely simple tasks or when you know the task is simple and well-defined **Cons:** May take inefficient paths, might miss important steps ### With Planning (Deliberate) ``` Task: "Investigate suspicious login from user@example.com" Planning Phase: Agent creates plan: 1. Get user details from Okta (roles, groups, last login) 2. Get authentication events from past 24h 3. Extract all source IPs from those events 4. Check IPs against threat intel 5. Determine if activity is anomalous 6. Summarize findings Execution Phase: Agent follows plan systematically, adjusting if needed ``` **Pros:** Thorough, systematic, less likely to miss steps **Cons:** Slightly slower, less exploratory ## Choosing the Right Mode * Task is simple and well-defined * Speed is critical * Agent instructions are very explicit about steps * Typical run has 1-3 tool calls **Examples:** * Lookup and post result * Simple enrichment (check one indicator) * Status checks * Task complexity varies * You want balance of speed and thoroughness * You're unsure which mode is best * Agent handles diverse scenarios **Examples:** * Alert triage (varies by alert type) * User requests via Slack * General-purpose copilot agents **This is the recommended default.** * Task is consistently complex (5+ steps) * Order of operations matters * Missing a step would be problematic * Thoroughness > speed **Examples:** * User offboarding workflows * Compliance audits * Multi-system incident response * Scheduled reports with many data sources ## Real-World Examples ### Example 1: Alert Triage (Auto) ``` Agent configuration: - Planning Mode: Auto - Typical complexity: 3-7 tool calls Simple alert (agent skips planning): - Get alert details → check hash in VirusTotal → update ticket - 3 tool calls, completes in 10 seconds Complex alert (agent plans): - Creates plan: get alert → search logs → check indicators → correlate → determine severity → update ticket - 8 tool calls, completes in 45 seconds Result: Agent adapts to situation automatically ``` ### Example 2: User Lookup (Never) ``` Agent configuration: - Planning Mode: Never - Task: Always the same pattern Workflow: - Get Okta user details - Post to Slack Result: Fast, simple, no need for planning ``` ### Example 3: Offboarding (Always) ``` Agent configuration: - Planning Mode: Always - Task: 15+ steps across multiple systems Plan created: 1. Verify user in Okta 2. List all groups and roles 3. Remove from Okta groups 4. Disable AWS IAM access 5. Remove from Google Workspace 6. List Jira issues assigned to user 7. Reassign critical issues 8. Disable Slack account 9. Post summary to #security channel ... Result: Systematic, thorough, nothing missed ``` ## Impact on Performance | Metric | Never | Auto | Always | | ---------------- | ------------ | ------ | ----------------- | | Average Duration | Fastest | Medium | Slowest (+10-20%) | | Token Usage | Lowest | Medium | Highest (+15-25%) | | Reliability | Good | Better | Best | | Thoroughness | Good | Better | Best | | Best for | Simple tasks | Mixed | Complex tasks | **Speed vs Thoroughness**: Planning adds 10-20% overhead but significantly improves reliability for complex tasks. For most agents, "Auto" provides the best balance. ## Plan Visibility When an agent creates a plan, you can see it in the execution logs: ``` 📋 Plan Created: Step 1: Get SentinelOne alert details - Tool: get_sentinelone_alert - Purpose: Fetch full alert context Step 2: Search Splunk for related activity - Tool: search_splunk - Purpose: Find user activity in past 24h Step 3: Check file hash in VirusTotal - Tool: virustotal_check_hash - Purpose: Determine if file is known malware Step 4: Assess severity based on findings - No tool needed - Purpose: Analyze data and make determination Step 5: Update Jira ticket with findings - Tool: update_jira_ticket - Purpose: Post results for analyst ``` This visibility helps you understand the agent's approach and debug issues. ## Dynamic Plan Adjustment Agents can adjust their plans based on discoveries: ``` Original Plan: 1. Get alert 2. Search logs 3. Check VirusTotal 4. Update ticket Adjustment: → Step 2 failed (Splunk unavailable) → Agent adapts: "Skip log search, proceed with VirusTotal" → Continues with modified plan ``` This adaptive behavior works in all planning modes. ## Prompt Guidance for Planning You can influence how agents plan with prompt instructions: ### For "Auto" Mode ```markdown theme={null} When planning your approach: - For Critical alerts, always create a detailed plan - For Low severity alerts, act quickly without extensive planning - If more than 3 tools are needed, plan your approach first ``` ### For "Always" Mode ```markdown theme={null} Your plan should include: 1. All data gathering steps (list them) 2. Analysis phase (what you'll evaluate) 3. Decision criteria 4. Action steps Ensure your plan covers all requirements before executing. ``` ### For "Never" Mode ```markdown theme={null} Follow this sequence: 1. First, always call [specific tool] 2. Then, based on result, call [next tool] 3. Finally, [action] (Being explicit compensates for lack of planning) ``` ## Testing Planning Modes Use Builder to compare modes: Run agent with complex test case, note duration and quality Switch to different mode (e.g., Auto → Always) Execute identical test case * Which produced better output? * Which was more efficient? * Did Always mode catch steps Never mode missed? Choose mode that best balances quality and speed for your use case ## Common Pitfalls **Over-planning for Simple Tasks**: Don't use "Always" for agents that typically make 1-2 tool calls. You're just adding overhead. **Under-planning for Complex Tasks**: If your agent frequently misses steps or acts inefficiently, try "Auto" or "Always" mode. **Expecting Perfect Plans**: Plans are guides, not guarantees. Agents may deviate based on what they discover. ## Advanced: Plan Quality You can improve plan quality with: 1. **Clear system prompts**: Explain the typical workflow 2. **Context documents**: Provide runbooks or procedures 3. **Examples**: Show what good plans look like 4. **Evaluation criteria**: Define what "complete" means ## Monitoring Planning Track planning effectiveness with your internal monitoring and evaluation tools: * **Planning rate**: % of runs where planning occurred (for "Auto" mode) * **Plan adherence**: How closely the agent followed its plan * **Plan adjustments**: How often plans were modified * **Outcome comparison**: Planned vs unplanned success rates ## Best Practices Unless you have specific requirements, use "Auto" mode and let the agent decide when planning helps. In Builder, test with "Never" and "Always" to understand the quality/speed tradeoff for your specific agent. Simple agents → Never, Complex agents → Always, Variable agents → Auto When an agent fails, check if it planned (and if that plan was sound). This reveals prompt gaps. Planning mode is an optimization. Focus on prompt quality first, then tune planning mode.