---
title: "Agent Experience Optimization"
description: "Agent experience optimization fixes the step where an agent task dies, then remeasures. Start with the doc, the error, or the auth wall the agent actually hit."
canonical: "https://www.agentrail.co/blog/agent-experience-optimization"
author: "Vivek Mittal"
published: "2026-10-17T00:00:00Z"
last_updated: "2026-10-23T10:23:08.509Z"
---

# Agent Experience Optimization

Agent experience optimization fixes the step where an agent task dies, then remeasures. Start with the doc, the error, or the auth wall the agent actually hit.

![Agent Experience title on a dark blue gradient](https://images.ctfassets.net/1htfyfnn1o5y/XvsIRiugIRB7EX3t0gO4F/ea20094b318d5d7c6d85bd2c36cc98a3/hero_image-2.png?w=1600&fm=webp&q=72)

Agent experience optimization is the edit you make at the step where the task dies. A docs rewrite, a clearer error, a stable auth path, or a tool description can each be the right edit. They are not interchangeable. The step tells you which one.

The before-and-after numbers live in [how to measure agent experience](https://www.agentrail.co/blog/how-to-measure-agent-experience). That page owns agent experience metrics. This page owns the change. If you can't name the surface and the action that stopped the task, you're not optimizing yet. You're redecorating.

> **Key Takeaways**
>
> Start from the dead step: the surface and the action, not a sitewide checklist.
>
> Match the fix to the failure. A missing map, an unreadable page, a bad tool contract, and a mid-run crash are different jobs.
>
> Change one surface, repeat the same tasks on the same agent profile, and compare outcome with cost.
>
> A new MCP server or skill helps agents that load it. The doc or error they already touch helps the rest.
>
> Small, scoped results from Microsoft and Anthropic are reasons to test your own change. They are not your forecast.

## Optimization starts where the task stops

A task dies in a place. The place has a name. The docs returned a directory listing. The SDK readme described last year’s client. The MCP tool returned a stack trace. The API answered 401 with an HTML login page. The agent retried the same call until the context filled up.

Write that sentence before you open a pull request. [Agent analytics](https://www.agentrail.co/blog/agent-analytics) is where we reconstruct the task across website, docs, API, SDK, and MCP so the sentence is observable, not guessed. The metric you will compare later is whichever row in the measurement set moved. Often that is task completion, the terminal state, retries, or path cost. Do not build a new score for the edit.

## Read the step before you change the site

Agents are non-deterministic, so a bug report that says “it could not find the obvious page” isn't a diagnosis. Anthropic hit that wall on their research system. Users said agents missed information that looked obvious. The team could not tell bad queries from bad sources from tool failures until they had the production trace ([How we built our multi-agent research system](https://www.anthropic.com/engineering/multi-agent-research-system), 13 June 2025).

Class the stop. You only need five buckets.

1. The agent never found the page or the tool.
2. It found the URL and could not read the content.
3. It called a tool, and the call was the wrong tool or the wrong arguments.
4. A gate stopped it, and the gate was illegible. Auth, a paywall, and a bot rule sit here.
5. The run died in the middle, and the next attempt started over.

Each bucket has a different edit. A standards checklist that says “add llms.txt and an MCP card” skips the classification. Add the artifact that matches the bucket you saw.

## When the agent cannot find the page, fix the map it reads

Cloudflare’s docs work is the clearest public example of a map problem. A single `llms.txt` that lists thousands of pages does not fit a context window. The agent greps, misses, and greps again. Each loop spends thinking tokens and another fetch. They split `llms.txt` by top-level directory, pointed the root file at those directories, and dropped directory pages that only repeated the child links. They omit roughly 450 of those listing pages.

They then pointed one agent, Kimi-k2.5 via OpenCode, at their docs and at other large technical docs. On average, the agent on Cloudflare’s docs used 31% fewer tokens. It reached the correct answer 66% faster than on the average site that had not been refined the same way ([Introducing the Agent Readiness score](https://blog.cloudflare.com/agent-readiness/), 17 April 2026). That's their comparison, on that agent. It's a strong reason to look at the map your agent actually opens. It isn't a promise that your next `llms.txt` will post the same percentages.

If the dead step is “the tool list is unscannable,” the cousin fix is on the MCP side. [MCP observability](https://www.agentrail.co/blog/mcp-observability) is what to record on the call. [MCP analytics](https://www.agentrail.co/blog/mcp-analytics) is which tools get used and which get abandoned. Record the call before you merge a new tool.

## When the agent cannot read the page, change the bytes

Markdown negotiation is a readiness check. It is also an optimization, and it fails in a specific way. As of February 2026, Cloudflare tested seven agents. Only Claude Code, OpenCode, and Cursor sent `Accept: text/markdown` by default. The others still needed a URL they could fetch. Cloudflare’s fallback is `/index.md` on the page URL, rewritten to the markdown response, and linked from `llms.txt`. On their own pages, markdown instead of HTML cut tokens by up to 80% in some cases. Again, their measurement.

Structure changes the path even when you are not negotiating content type. The July 2026 prototype study, cited in [what is agent readiness](https://www.agentrail.co/blog/what-is-agent-readiness), cut average steps from 9.31 to 6.49. The agent-ready pages replaced the human-oriented ones, and the models stayed fixed ([arXiv:2607.12056](https://arxiv.org/abs/2607.12056)). The success-rate side of that preprint stays in the definition essay. The step drop is the optimization point. Fewer steps means the dead ends got shorter.

If the fact the agent needs appears only after JavaScript runs, many agents never see it. Put the fact in the HTML, the markdown, or the spec. Then remeasure. Don't assume the format change helped because the file exists.

## When the tool call is wrong, fix the contract

Tool descriptions are part of the prompt whether you think of them that way or not. Anthropic built a tool-testing agent that used a flawed MCP tool, then rewrote the description to avoid the failures it hit. After dozens of attempts, later agents using the new description finished tasks in 40% less time, because they skipped most of the mistakes (same 13 June 2025 research essay). That's one internal loop. Copy the method. Don't copy the 40% onto your roadmap as a target.

The error body is the other half of the contract. In their 11 September 2025 essay on tools, Anthropic says a validation failure should return a specific, actionable correction. An opaque code or a traceback does not steer the next call ([Writing effective tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents)). They also namespace tools so overlapping names stop competing. Claude Code caps tool responses at 25,000 tokens by default, so one fat payload doesn't end the task. Lots of errors on invalid parameters usually means the description or the examples are thin. Lots of repeated calls usually means pagination, filters, or defaults are wrong.

Watch the dead step to see which of those you have. A wrong tool name is a description problem. A right tool with a bad argument is a schema and example problem. A right call that returns junk is a response-design problem.

## When the run dies in the middle, resume

Agents hold state across many calls. A small failure compounds because the next decision is conditioned on a broken step. Anthropic’s rule from the research system is practical. Don't restart the whole task. Restarts cost tokens and throw away work the user already waited for. Resume from the last good point. Tell the agent the tool is failing so it can adapt. Pair that with ordinary retry limits and checkpoints, so a loop cannot run forever.

Separate a crash from a refusal. A correct refusal is the agent stopping because the action is unsafe or the fact is absent. If your before-and-after treats that stop as a failure, you will “optimize” it away. The terminal-state split is defined with the other [agent experience metrics](https://www.agentrail.co/blog/how-to-measure-agent-experience). Use it when you score the rerun.

## Change one surface, then compare

Microsoft’s method is the one to steal, and their numbers are the ones to leave in their lab. Hold the model, the harness, the prompt, and the workspace fixed. Change one thing. Run the same tasks again. They treat five runs as enough to see a stable pattern on the tasks they care about. Call the result lift when outcomes improve, and drag when they don't. Refuse the lift when the cost jumps out of proportion ([What is Agent Experience (AX)?](https://developer.microsoft.com/blog/what-is-agent-experience-ax/), 6 October 2026). A result belongs to that agent profile. When the profile changes, run again.

Three of their measurements show why intuition is a weak optimizer. Each one is scoped to the scenarios they ran.

On SharePoint Framework upgrades, five runs in GitHub Copilot Chat with Claude Sonnet 4.6 on Windows passed 30 of 80 configuration checks. Telling the agent to use a specific CLI raised that to 75 of 80. That instruction only helps a developer who knows the CLI, or who installed a skill that carries it. The trace showed the agent already fetched the release notes. They fixed the notes. After that, every run used the CLI without being told, and no extra skill was required.

A documentation tip that pointed at the right tool got 1 of 5 runs to use it. A warning that named the failing approach got 5 of 5.

A JSON input mode added for agents looked helpful. With ordinary arguments, every profile they tested got all 5 runs right. In JSON mode, Claude Haiku 4.5 got 2 of 5 deployments right, and every model cost 4 to 11 times more per task.

None of those ratios is your ratio. They're evidence that a plausible agent-friendly change can be drag, and that the surface the agent already reads can beat a new extension.

## Add a protocol after the dead step asks for it

Skills, MCP servers, and instruction files shape agents that load them. They do nothing for the agent that never installs them. Microsoft’s order follows from that. Fix the docs and the interfaces agents already use. Reach for a new extension last.

MCP belongs in the product when you have tools to expose and the dead step is an action the agent cannot call. A content site with no tools does not gain a task by publishing a card. Auth belongs in the fix when the dead step is a login wall the agent cannot see through. The public version of that problem is part of readiness. The [readiness essay](https://www.agentrail.co/blog/what-is-agent-readiness) defines the scan. Optimization begins when you know which check, or which live step, is the one that stopped the work.

## Frequently asked questions

### Where should agent experience optimization start?

Start at the step where the task stopped. Name the surface and the action. Then change that surface. A sitewide pass over every new agent standard comes after you know which failure you have.

### Should we ship an MCP server first?

Ship MCP when agents need to call tools and the current path cannot express that call. If the trace shows a bad description, a bad error, or a doc the agent already fetched, fix that first. A server nobody can find is a discovery problem, not a protocol trophy.

### How many runs do we need before we trust a fix?

Microsoft’s working rule is five runs of the same task on one recorded agent profile, with and without the change. NVIDIA’s eval write-up asks for a range across three to five trials. Use more when the effect is small. Write the profile next to the result.

### Is a docs change better than a skill?

It is better when the agent already reads the doc. Microsoft’s release-notes fix reached every run they measured, with no skill installed. A skill helps the developers who install it. Measure both against the same tasks if you are unsure which one you have.

## Fix the step, then look again

Name the dead step. Change one surface that step actually touched. Run the same tasks on the same profile, or watch the same production journey, and read the result with the [metric set](https://www.agentrail.co/blog/how-to-measure-agent-experience). Lift that costs several times more per finished task is still a decision, and it is a worse decision if you never saw the cost.

We reconstruct those journeys across the website, the docs, the API, the SDK, and MCP. Recommendations, which are included, rank fixes from the journeys and can carry a prompt or a pull request. Readiness scans are included too. Journeys are metered. The numbers are on [pricing](https://www.agentrail.co/pricing).