> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scoutos.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Planning Tools: Reliable Execution on Complex Tasks
> Give Scout agents a structured way to plan, track, and adapt multi-step work with the CreatePlan, GetNextStep, and UpdatePlan tools.
Language models are strong at reasoning one step at a time, but complex tasks expose a weakness: an agent juggling many tool calls can lose track of progress, forget the original goal, or fall into loops of repeated actions. Planning tools fix this. They give the agent a structured way to map out an approach before executing, track which steps are done, and adapt the plan as it learns new information. The result is dramatically more reliable execution on multi-step work.
## Why Planning Matters
Without planning, an agent improvises step by step. On a simple lookup that's fine — but on a task with five or ten interdependent steps, improvising leads to predictable failure modes:
* **Getting lost** — the agent forgets what it has already done and repeats work
* **Losing the goal** — after several tool calls, it drifts away from the original request
* **Looping** — it makes the same call again and again without making progress
* **Stopping early** — it declares the task complete when steps remain
With planning, the agent builds a roadmap first, works through it in a logical sequence, tracks completed and remaining work, and adjusts deliberately when something changes. In the **Logs** tab, the difference is stark: reactive backtracking versus a consistent, traceable sequence of steps with intentional adjustments.
***
## The Three Planning Tools
Planning is provided by three tools that work as a set. Each handles one part of the plan-execute-adapt loop.
### CreatePlan
`CreatePlan` builds a structured plan at the start of a complex task. The agent analyzes the request and its available tools, breaks the work into discrete steps, identifies dependencies between them, and estimates complexity. Agents use it when a task has more than a couple of steps or spans multiple tools.
```json theme={null}
{
"plan_id": "plan_abc123",
"task": "Research competitor pricing and create comparison report",
"steps": [
{
"id": 1,
"description": "Search web for current pricing of top five competitors",
"tools": ["web_search"],
"status": "pending"
},
{
"id": 2,
"description": "Scrape pricing pages for detailed feature comparison",
"tools": ["web_scrape"],
"status": "pending"
},
{
"id": 3,
"description": "Format data into comparison table",
"tools": [],
"status": "pending"
},
{
"id": 4,
"description": "Generate summary report with insights",
"tools": [],
"status": "pending"
}
]
}
```
### GetNextStep
`GetNextStep` returns the current step to work on, along with relevant context from prior steps, and marks it in progress. The agent calls it after finishing a step or whenever it's unsure what to do next. Because it carries context forward, the agent stays oriented across a long task.
```json theme={null}
{
"step_id": 2,
"description": "Scrape pricing pages for detailed feature comparison",
"tools": ["web_scrape"],
"status": "ready",
"context": {
"previous_step": "Found pricing pages for four of five competitors",
"urls_to_scrape": [
"https://competitor-a.com/pricing",
"https://competitor-b.com/pricing"
]
}
}
```
### UpdatePlan
`UpdatePlan` keeps the plan in sync with reality. The agent uses it to add or reorder steps, change descriptions, mark steps complete, or skip steps that turn out to be impossible. This is what makes a plan a living guide rather than a rigid script.
Add a step when the agent discovers new work:
```json theme={null}
{
"action": "add_step",
"after_step": 2,
"step": {
"description": "Research pricing for newly discovered competitor X",
"tools": ["web_search", "web_scrape"]
}
}
```
Complete a step and record the result:
```json theme={null}
{
"action": "complete_step",
"step_id": 2,
"result": "Successfully scraped pricing from all five competitors"
}
```
Skip a step that can't be done, with a reason:
```json theme={null}
{
"action": "skip_step",
"step_id": 2,
"reason": "Competitor B's pricing page requires login, cannot access"
}
```
***
## Enable Planning Tools on an Agent
Navigate to your agent in Scout Studio.
Click the **Tools** tab in the agent editor, then click **Add tool**.
Find the **Planning** section and add **CreatePlan**, **GetNextStep**, and **UpdatePlan**. They work as a set — adding only `CreatePlan` leaves the agent unable to track progress or adapt.
Save your agent, then update its instructions so it knows when to plan (see below).
Add all three tools, not just one. The planning loop breaks if any are missing: without `GetNextStep` the agent can't track progress, and without `UpdatePlan` it can't adapt when something changes.
***
## Writing Instructions for Planning
Enabling the tools isn't enough — the agent needs guidance on *when* to plan. Add a block like this to your agent's instructions:
```text theme={null}
For any task with more than two or three steps, start by calling
CreatePlan to break the work into a sequence of steps.
- After completing each step, call GetNextStep to retrieve the next
step and the context you need for it.
- When you discover new work, hit a blocker, or learn something that
changes your approach, call UpdatePlan to add, reorder, complete,
or skip steps.
- For simple, single-step requests (a quick lookup, a single
calculation), skip planning and answer directly.
Treat the plan as a guide, not a rigid script — adjust it as you learn.
```
***
## When to Use Planning Tools
Planning adds the most value when a task is genuinely multi-step. Match the tool to the work.
**Good use cases:**
* **Multi-step research** — gathering and synthesizing information across several sources
* **Cross-system data work** — pulling from Salesforce, HubSpot, and other tools, then combining the results
* **Open-ended problem solving** — for example, investigating why a conversion rate dropped
* **Tasks with dependencies** — customer onboarding or anything where later steps depend on earlier ones
**Skip planning for:**
* **Simple single-step tasks** — looking up today's weather
* **Fixed, well-defined workflows** — where the steps never change (use a [Workflow](/workflows/overview) instead)
* **Quick lookups** — finding a contact's email address
***
## Worked Example
**Request:** *"Identify our top 10 cold leads and write personalized re-engagement emails for each."*
**Without planning**, the agent might search the CRM, start drafting an email for the first lead it finds, get sidetracked gathering more context, lose track of how many emails it has written, and finish with an incomplete, inconsistent result — or not finish at all.
**With planning**, the agent calls `CreatePlan` and produces a structured approach:
```json theme={null}
{
"plan_id": "plan_leads_42",
"task": "Identify top 10 cold leads and write re-engagement emails",
"steps": [
{
"id": 1,
"description": "Query CRM for leads with no activity in 90+ days",
"tools": ["crm_search"],
"status": "pending"
},
{
"id": 2,
"description": "Rank inactive leads by deal value and select top 10",
"tools": [],
"status": "pending"
},
{
"id": 3,
"description": "Gather context for each lead (industry, last interaction, deal stage)",
"tools": ["crm_search"],
"status": "pending"
},
{
"id": 4,
"description": "Draft a personalized re-engagement email per lead",
"tools": [],
"status": "pending"
},
{
"id": 5,
"description": "Save email drafts back to the CRM",
"tools": ["crm_update"],
"status": "pending"
},
{
"id": 6,
"description": "Summarize the outreach strategy for the user",
"tools": [],
"status": "pending"
}
]
}
```
The agent then works through the plan with `GetNextStep`, looping over each lead in steps 3 and 4. When it discovers a surprise — say three of the top 10 leads were already contacted last week — it calls `UpdatePlan` to skip those and pull in three replacements, keeping the count at 10. The result: all 10 emails drafted, personalized, and saved, plus a clear strategy summary.
***
## Best Practices
**Let the agent decide when to plan.** Don't force planning on every task. Instruct the agent to plan for complex work and answer simple requests directly.
**Be clear about goals.** Guide the agent to consider what information it needs, the best order to gather it, and what might change its approach. A clear goal produces a better plan.
**Allow plan flexibility.** Plans are guides, not scripts. Make sure your instructions encourage the agent to use `UpdatePlan` when reality differs from the plan.
**Checkpoint progress.** Instruct the agent to report what it has accomplished at natural checkpoints, so you can follow along and catch a wrong turn early.
***
## Frequently Asked Questions
No. Planning tools are best for complex, multi-step tasks. For agents that handle simple lookups or run a fixed sequence, they add overhead without benefit.
Yes — they work together. `CreatePlan` builds the plan, `GetNextStep` walks through it, and `UpdatePlan` keeps it current. Skipping one breaks the planning loop: without `GetNextStep` the agent can't track progress, and without `UpdatePlan` it can't adapt.
There's a small upfront cost to build the plan, and planning uses a few more tokens. On complex tasks the agent is usually faster overall, because it wastes less effort backtracking and repeating work. On simple tasks, skip planning.
Yes. The **Logs** tab shows every `CreatePlan` and `UpdatePlan` call, so you can see the plan the agent built and how it adjusted along the way.
A plan is a starting point. The agent uses `UpdatePlan` to correct course as it works. If you consistently see poor plans, refine the agent's instructions to clarify the goal and constraints.