Blog / Tool results and errors

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

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.

Why results are the right place

• Instructions are read once, at the start, and some apps cut them. See 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.

Go deeper: The two-step confirm pattern, Make agents read your instructions first, The 12,689-token typo.

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.

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.