---
title: Next-Step Hints: Make MCP Tool Results Guide the Agent
description: Without hints, agents skipped steps on a live MCP server: no balance check, paging everything instead of the since cursor. How to add next-step hints.
canonical: https://spiritroom.app/blog/next-step-hints-in-tool-results/
published: 2026-10-21
updated: 2026-10-21
---

> Markdown version of https://spiritroom.app/blog/next-step-hints-in-tool-results/ for agents. Index: /llms.txt

[Blog](/blog/) / [Tool results and errors](/guides/tool-results-and-errors-for-agents/)

# Next-step hints: make every tool result tell the agent what to do next

The agent reads your tool results more closely than anything else you send it. That's the best place to say what comes next: not in a skill it may not have, or an instruction it read 20 calls ago.

Leonid Bugaev · Published 21 Oct 2026

**TL;DR**

- **Agents skip steps they aren't told about:** without skills, Claude skipped the credit-balance check in 2 of 2 spend-planning runs and paged through all records instead of the “since” tool in 2 of 2.
- **The result is where the agent looks.** Put one machine-readable next step there, plus a fallback.
- **Errors are results too:** a one-line error with “call X for valid values” beats “ask the user”.
- **Keep it small:** one next step and a short reason, not a restated playbook.
- **Partial evidence:** we measured the skipped steps; we haven't yet run hints alone as a controlled test.
[What agents skipped](#skipped)[Why results are the right place](#why)[The shape of a hint](#shape)[Hints in errors](#errors)[What not to do](#dont)[How we measured](#how-we-measured)[FAQ](#faq)

## What agents skipped

On a 99-tool production MCP server, without the vendor's skills, Claude Code and Codex got most answers right but missed the intended path:

- **Spend planning:** Claude previewed the plan in 2 of 2 runs but never checked the credit balance first. One Codex run also skipped it.
- **“What's new since yesterday”:** Claude answered right in 2 of 2 runs but paged through all records instead of the “since” tool built for it.

With the skills, both followed the playbook. Without them, nothing in the results said “check the balance next” or “use the since cursor”. More: [agent skills vs MCP server](/blog/agent-skills-vs-mcp-server/).

**See where agents go off your intended path.**

We trace your users' jobs call by call in the agent apps they use and show where a next-step hint would keep them on track.

[Test your MCP →](/#contact)

## Why results are the right place

- Instructions are read once, at the start, and some apps cut them. See [server instructions length](/blog/mcp-server-instructions-length/).
- Skills have to be installed, and aren't there in every app.
- The latest result is right in front of the model when it picks the next call.

## The shape of a hint

```
{
  "balance": 6567,
  "next": {
    "tool": "preview_plan",
    "args": {"max_credits": 3000},
    "why": "Preview before starting. Nothing is spent until the user confirms."
  },
  "if_blocked": {"tool": "get_spend", "why": "See what's already reserved."}
}
```

A compliance SaaS MCP server we studied does this in its start-here tool: the result names a focus area with the reason and the exact items, plus an `if_blocked` fallback that names another tool and its arguments.

- One next step, not a list.
- Include the arguments that are easy to get wrong: cursors, IDs, limits.
- For paged lists, say “next page: offset=10” in the summary line.

## Hints in errors

```
{"error": "list_items: status \"waiting\" is not valid. Use open, blocked, in_review or done. Call get_stats to get valid values.",
 "guidance": {"state": "fix_args", "next": "get_stats"}}
```

On our made-up task-tracker mock this one-line style was 51 tokens against 3,109 for a schema dump, and errors stopped with the fixed surface (4/30 runs with an error before, 0/30 after). Don't mark a typo as “ask the user”: see [agent refusal states](/blog/agent-refusal-states/).

**Go deeper:** [The two-step confirm pattern](/blog/mcp-two-step-confirm-spend/), [Make agents read your instructions first](/blog/get-instructions-first-24-of-24/), [The 12,689-token typo](/blog/verbose-validation-errors-tokens/).

## What not to do

- **Don't restate the playbook** in every result. The start-here result in that compliance example was 15,768 tokens, including a 3,552-token restatement of the instructions.
- **Don't hint at writes as if they were safe.** Pair them with a preview and a confirm.
- **Don't contradict yourself:** one server we tested told agents to stop and ask the user even on a version conflict whose text said to re-read and retry.

Back to [tool results and errors for agents](/guides/tool-results-and-errors-for-agents/).

## How we measured

- **Skipped steps:** 24 live read-only runs, Claude Code and Codex, with and without skills, 2 runs per cell, 16 Oct 2026. Direction, not rates.
- **Error hints:** a made-up task-tracker mock, 3 apps × 10 runs per surface, 21 Oct 2026; 95% Wilson ranges in the linked posts.
- **Example server:** read from its live tool list and one start-here call; not named.
- **Not yet tested:** hints alone, without skills, as a controlled change.

## FAQ

### How can tool results guide an agent's next call?

Add a small field to each result naming the next tool to call, with the arguments that matter and a one-line reason, plus a fallback if that step is blocked. Agents read results closely and act on them.

### What should a next-step hint contain?

The tool name, key arguments (such as a cursor or an ID), a one-line reason, and optionally an alternative. Keep it to one step.

### Should hints be prose or structured?

Both work; structured is easier to keep consistent: for example {"next": {"tool": "preview\_plan", "args": {...}, "why": "..."}}.

### Can a hint make an agent do something unsafe?

It shouldn't be able to. A hint suggests; spends and writes still need the user's yes and a confirm step on the server.

**See where agents go off your intended path.**

We trace your users' jobs call by call in the agent apps they use and show where a next-step hint would keep them on track.

[Test your MCP →](/#contact)

## Keep reading

- Up[Tool results and errors for AI agents (guide)](/guides/tool-results-and-errors-for-agents/)
- Related[Make the agent read your playbook first: 24 of 24 runs in Claude Code and Codex](/blog/get-instructions-first-24-of-24/)
- Related[Retry, fix the arguments, or ask the human? Refusal states agents can act on](/blog/agent-refusal-states/)
- Related[Stop agents spending money without asking: the two-step confirm pattern for MCP tools](/blog/mcp-two-step-confirm-spend/)