Your AI agent skips steps. Give it a todo list.

You give an agent a real job: "audit these ten endpoints, fix the auth bug in each, run the tests, write up what changed."

It starts well. Six endpoints fixed, some tests run, a tidy summary. The last four endpoints? Never touched.

No crash. No error. It just lost track.

If you've built anything agentic, you've seen this. Here's a small tool that fixes most of it, and how we run it in ByteChef, an open-source workflow automation and AI agent platform built on Java and Spring.

Why agents drop steps

Language models pay less attention to whatever sits in the middle of a long context. As an agent works, its context fills with tool calls and results, and the original plan drifts into that middle zone.

The Spring AI team covered this in their TodoWrite post and borrowed the fix from Claude Code: don't keep the plan in your head. Write it down as a checklist and keep it current.

The TodoWrite tool

TodoWriteTool lives in the spring-ai-agent-utils library. The model sees a tool called TodoWrite. Every call sends the whole list, and each item has three fields:

• content - the task as an instruction: "Update the Spring Boot version"
• activeForm - the same task while it runs: "Updating the Spring Boot version"
• status - pending, in_progress or completed

One rule does most of the work: only one task can be in_progress at a time. The tool rejects a list with two tasks in progress and tells the model to finish the current one first. That forces the agent to work in order instead of starting everything at once.

A few more details from the tool's instructions:

• Use it for jobs with 3+ distinct steps, not for single simple requests. The agent decides when a job needs a plan.
• Only mark a task completed when it's fully done. If tests fail or the work is partial, keep it in_progress.
• If something blocks a task, add a new task for the blocker.

Why writing it down works

A checklist only helps if the agent keeps reading it. That's the real trick.

Each TodoWrite call carries the full current list in its arguments. During a run, the agent's tool-calling loop keeps every tool call and result in the conversation. So whenever the model picks its next step, the latest list is right there: three done, one in progress, six pending.

The plan can't fall out of attention because it gets written again on every update.

Spring AI vs. ByteChef setup

In plain Spring AI, you wire this up yourself: add the tool to a ChatClient, configure MessageChatMemoryAdvisor and ToolCallAdvisor so tool messages actually reach the model, and add chat memory if you want follow-ups.

In ByteChef, the AI Agent component already runs the tool-calling loop and keeps tool messages in the conversation. The Todo Write Tool is one element you drop into the agent's Tools slot. Here's the entire wrapper:

TodoWriteTool todoWriteTool = TodoWriteTool.builder()
    .build();

return ToolCallbackProvider.from(ToolCallbacks.from(todoWriteTool));

That's it. The library does the work, the AI Agent provides the loop.

	Spring AI	ByteChef
Add the tool	In code, on a ChatClient	Todo Write Tool element on an AI Agent
Tool messages reach the model	Configure advisors	Built into the agent loop
Chat memory	Add it yourself	Add a Chat Memory element

Same tool, same three statuses, same one-in-progress rule.

Try it: a Spring Boot 4 migration planner

Spring Boot 4 migrations are a good stress test. Lots of small steps (Java version, dependencies, Jakarta changes, config properties, tests), and skipping one is easy.

The Spring Boot 4 migration planner template is three steps:

1. New Chat Request - a message arrives in the workflow chat.
2. AI Agent - an Anthropic model, Chat Memory for follow-ups, and the Todo Write Tool.
3. Reply - the answer goes back to the chat.

The system prompt does the rest:

You are a senior Java engineer. For any request with 3 or more distinct
steps, first create a todo list with the TodoWrite tool. Keep exactly one
task in_progress at a time, mark each task completed as soon as it is done,
and update the list after every step. Finish with a short summary.

To run it:

1. Import the template into a project.
2. Add your Anthropic connection to the model under the AI Agent.
3. Open the workflow chat and ask for something multi-step, like: "Plan and walk me through migrating a Spring Boot 3.5 service on Java 17 to Spring Boot 4."

Before answering, the agent calls TodoWrite with a plan. Exact tasks depend on the model, but expect something like:

[ ] Upgrade the service to a supported Java version
[ ] Update the Spring Boot version and the dependency BOM
[ ] Fix renamed and removed configuration properties
[ ] Update tests and run the build
[ ] Summarize the changes

Here's the first TodoWrite call from a real test run, from the AI Agent's Logs tab. One task in progress, the rest pending:

Then it works through the list one task at a time, calls TodoWrite after each step, and ends with a summary. The Agent Playbook in the editor shows every update as a tool-call card, so you can watch the list change.

If the agent skips the list on a big job, make the request more explicit about its steps or tighten the system prompt.

Why it earns its place

It looks almost too simple to matter. On long tasks it's one of the most useful tools you can give an agent:

• It fights lost-in-the-middle by design. The plan is rewritten on every update, so no step quietly disappears.
• One task in progress keeps the agent focused. It finishes what it started instead of leaving half-done work.
• It makes the work visible. You see what's done and what's next. That's the fastest way to check the agent understood the job.

It also pairs well with the other agent utils: File System, Shell, Grep and Glob tools give an agent hands. The todo list gives it a plan to use them on.

Wrapping up

The tools that make agents reliable are rarely the flashy ones. TodoWrite is a checklist, but one the agent writes itself and re-reads at every step. That's exactly what a long task needs.

Got an agent that drops steps on long jobs? Import the migration planner template, add your Anthropic connection, and give it a ten-step job.

This is Part 3 of our AI Agentic Patterns series. Part 1 covered Agent Skills. If you like where ByteChef is going, a star on GitHub helps a lot.

Originally published on the ByteChef blog.