> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withgauge.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Improve agent results
> Test documentation or skill changes against an eval or preference prompt and inspect the evidence before shipping.
Use an optimization to test whether a change to your docs or skills helps agents do better. Gauge runs the task with the change and compares the results. Each test is called a **trial**.
Optimizations is enabled per organization. Where available, use the measurement's **Improve** section. Organizations still using the earlier workflow can create [legacy content experiments](/agents/guides/legacy-content-experiments). With Optimizations enabled, old experiments remain readable but cannot be authored or modified.
## Plan a useful comparison
Start with completed results and a specific problem. For example, an agent repeatedly misuses an API because the setup page omits a required initialization step.
In **Improve**, choose the page or skill you want to change from the available options. Make a change that helps developers use your product. Keep the task and pass criteria the same so you can tell whether the change helped.
Choose one agent and model. Set how many rounds to try and how many times to run each trial. More runs give you more evidence, but cost more. Review the estimate before starting.
## Start from the CLI
List available models, ask Gauge to identify problems in the eval, and estimate the cost of a small test:
```bash theme={null}
gauge models list
gauge optimizations diagnose --eval
gauge optimizations estimate \
--eval --target --samples 1 --rounds 3
```
Use a target from the model catalog in place of ``. To optimize preference, replace `--eval ` with `--preference `.
Add `--no-auto-adopt` if you want to review changes before Gauge uses them in later trials:
```bash theme={null}
gauge optimizations start \
--eval --target \
--samples 1 --rounds 3 --no-auto-adopt
gauge optimizations watch
```
Alternatively, `--effort low|medium|high|xhigh` selects a preset plan. Do not combine `--effort` with `--samples` or `--rounds`.
Gauge sets aside the estimated credits when you start. Use `--credit-cap` to choose a different amount. Gauge stops launching trials when the budget runs out, but sessions already running can still cost more than estimated.
## Review trials and adoption
```bash theme={null}
gauge optimizations get
gauge optimizations trials list
gauge optimizations trial
gauge optimizations change
```
Read the proposed change and compare the results. Open the sessions to see why the score changed. Repeat important tests: one better run does not prove that the change will help every time.
When a finished trial is marked `BETTER`, you can adopt it:
```bash theme={null}
gauge optimizations adopt
```
**Adopt** means Gauge uses the change as the starting point for later trials. CLI starts do this automatically unless you add `--no-auto-adopt`. Your original eval settings and published site stay unchanged.
## Pause, cancel, and ship
```bash theme={null}
gauge optimizations pause
gauge optimizations resume
gauge optimizations cancel
```
Pause lets current sessions finish and stops new ones from starting. Cancel stops the optimization, ends its running sessions, and returns credits it set aside but did not use. An optimization can also stop at its round limit, target score, budget, repeated lack of improvement, or an error.
Review the final change and publish it through your usual content or code workflow. For a docs rewrite, `gauge optimizations change --body` prints the page body. A shipping marker in Gauge records your action; it is not a deployment.
After publishing, run the task again against your live docs or skill. Try other relevant tasks and models too, to check that the change helps beyond this one eval.