Skip to main content
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. 
{
  "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. 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "action": "skip_step",
  "step_id": 2,
  "reason": "Competitor B's pricing page requires login, cannot access"
}

​
Enable Planning Tools on an Agent

1

Open your agent

Navigate to your agent in Scout Studio.
2

Go to the Tools tab

Click the Tools tab in the agent editor, then click Add tool.
3

Add all three planning tools

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.
4

Save and update instructions

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: 
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 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: 
{
  "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.