When to Upgrade an Agent’s Model—and When to Fix Its Tools

My thesis: an agent team should upgrade its model only when a measured failure is attributable to the model and a candidate improves the outcomes that matter. When the evidence points to a tool, retrieval, permissions or orchestration problem, changing the model is an expensive way to avoid the diagnosis.

New model releases deserve evaluation, not automatic adoption. A newer model may be the right answer: perhaps it consistently misreads a class of requests, cannot follow a required output constraint, or falls short on a capability that the product now needs. But “the agent failed” is not a diagnosis. An agent is a system: model, prompts, context, retrieval, tools, permissions, orchestration and the surrounding application all affect what a user experiences.

The distinction matters because the remedy determines the work. Replacing a model can require new evaluation, rollout and monitoring. Fixing a tool may mean correcting a schema or an API response. Improving retrieval may mean changing a filter or indexing process. Those changes carry different risks, owners and timelines. A team that jumps straight to the model can spend its change budget on the wrong component and preserve the original failure.

I would make the burden of proof explicit: the proposed model change must explain a production problem better than competing causes, and it must improve a representative test set without unacceptable regressions. This is not a case for staying on an incumbent forever. It is a case for treating model selection as a diagnosis and a product decision, rather than a reaction to release cadence.

Start with the symptom, not the model

An agent failure is an observable gap between the intended result and what happened. “The answer was bad” is too broad to guide a fix. A useful incident description names the user’s request, the expected business outcome, the observed result and the point where the workflow diverged.

For example, suppose a support agent is asked to find an order and prepare a replacement. It returns a confident summary, but no replacement request is created. That outcome could reflect several distinct failures. The model may have misunderstood the request. Search may have returned the wrong order. The account identifier may have been absent. The tool may have rejected a valid request. Or the orchestration may have stopped after search instead of calling the replacement action.

Those causes can look similar in a chat transcript. A polished response does not prove that the task completed, and an awkward response does not prove that the model is the cause. “The agent said it would do it” and “the business operation happened” are separate observations. Record them separately.

A useful incident record includes the original input, relevant context supplied to the agent, tool calls and results, permission decisions, orchestration transitions, final response, and an independent check of the intended result. Redact or minimize sensitive data as appropriate for the team’s handling rules. The purpose is not to collect every possible trace forever; it is to preserve enough information to locate the failure and evaluate a proposed remedy.

Agent evaluations should assess outcomes as well as transcripts; the agent harness and evaluation harness are distinct. Anthropic’s explanation of agent evaluations is a useful reference for that distinction. For this decision, the practical implication is simple: inspect the path and confirm the result, not just whether the final wording sounds plausible.

Classify the failing layer

I use five working categories. They are not claims that every incident has a single cause; they are prompts for testing the likely cause before changing the model.

Model behavior is a plausible cause when the required information and available actions were correct, yet the model repeatedly interpreted the request incorrectly, chose an unsuitable action, or produced an unusable result. Look for a reproducible pattern across comparable inputs, not one surprising answer.

Retrieval or context is a stronger suspect when the needed fact was missing, stale, irrelevant or contradicted by the material supplied to the model. If the right policy document was never retrieved, a different model may sometimes cope better with partial context, but that does not establish that model substitution is the durable fix. First verify what the system supplied and why.

Tool behavior is implicated when the agent selected an appropriate action but the tool returned an error, incomplete data or an unexpected result. Inspect the request and response at the tool boundary. A model cannot reliably compensate for a tool that silently omits a required field or reports success before a downstream operation finishes.

Permissions are implicated when a valid action was unavailable or rejected because the user, agent or service identity lacked the required authority. The right remedy is a deliberate access decision, not a more forceful model. If the operation is supposed to be disallowed, the refusal is correct behavior, even if it frustrates the user.

Orchestration is implicated when the workflow called the wrong sequence, lost state, mishandled a timeout, or failed to resume after a recoverable error. The model might have chosen the right next action while the surrounding system never executed it. Trace the transition from decision to action and back again.

When causes interact, record that uncertainty. A model may choose a poor search query because the prompt omits a field; retrieval may then return a weak match; the workflow may accept it without confirmation. Assigning the incident to one category too early can turn a useful diagnosis into an argument about ownership. First establish which observations support each explanation.

Why model upgrades attract the wrong kind of confidence

A new model is visible, named and easy to discuss. A retrieval filter or state transition is less visible, even when it is the source of the defect. That asymmetry creates a predictable management trap: the team can point to an obvious candidate change before it has established that the candidate addresses the observed failure.

Benchmark results can help decide what to test, but they do not substitute for a workload-specific comparison. Your agent’s requests, context, tools and definition of success may differ from a general benchmark’s task. Start with what the product needs to accomplish. Then use benchmarks as supporting information rather than as a deployment instruction. The distinction is developed further in Benchmarks That Actually Matter for New Model Releases and What SWE-bench, Terminal-Bench and OSWorld Can—and Cannot—Tell You.

There are also real costs to model change even when the interface appears stable. A model change can alter choices, wording, tool use and failure patterns. The team must decide what “good” means, compare behavior on representative cases, and define how to detect a regression after deployment. That is justified when the change solves an important problem. It is waste when the actual defect is a broken dependency or missing context.

Do not reduce this argument to “the latest model is risky.” An incumbent can have serious weaknesses. It can fail on an important request class, create unacceptable operational burden, or be unsuitable for a changed product requirement. Holding the line is not a virtue in itself. It is the rational choice only while the incumbent is adequate and the alternative has not earned its place through evidence.

Likewise, do not make a single aggregate score carry the whole decision. A small improvement on common, low-impact tasks can conceal a regression in a less frequent, high-consequence workflow. Separate the dimensions that matter: task completion, incorrect action, refusal when action is permitted, time to completion, recoverability and the quality of the user-facing explanation. Weight them according to product consequences, and preserve the underlying examples so reviewers can understand what moved.

A practical diagnostic sequence

The sequence below is intentionally ordered to distinguish component failures before inviting a model change. It is not a claim that every team needs a large evaluation platform. A small, carefully documented sample can expose a clear tool defect; a high-impact workflow may justify more extensive evaluation.

First, define the outcome in observable terms. “Help the user with a refund” is not precise enough. “Identify the relevant transaction, determine eligibility under the supplied policy, and—if authorized—create the requested refund without exceeding the permitted amount” gives evaluators something concrete to verify. If the product cannot state an expected result, it is not ready to claim that a model improved it.

Second, reconstruct the failure from the information available at the time. Capture the request and the context presented to the agent. Note which tools were available, the action requested, the response received, any permission decision, and the next orchestration state. Do not infer that a tool was called because the model described calling it. Verify the actual event.

Third, test the non-model boundaries directly. Does the retrieval layer return the expected record for a known input? Does the tool accept a valid request and return an unambiguous result? Does the permission policy allow the intended operation for the correct identity? Does the workflow handle both success and the relevant error? These checks should use safe test data and avoid performing real external effects unless the environment and controls are deliberately designed for that purpose.

Fourth, replay representative cases with the current configuration. Include successful examples, the failure that prompted the investigation, and nearby cases that should produce a different decision. A “nearby” case is useful because it tests whether a fix generalizes. If a proposed change makes the failing request pass but also causes the agent to act on an ineligible request, the apparent improvement is not acceptable.

Fifth, vary one suspect at a time where practical. If the evidence suggests a missing retrieval result, compare the same model and request with corrected context. If the tool’s response shape is ambiguous, clarify the response while holding the model configuration constant. If the model still fails when the needed context and functioning actions are present, then a model comparison has a stronger basis.

Finally, define the decision before looking at results. Specify the minimum improvement needed on the target failure, the regressions that would block deployment, and the operational limits that matter. This helps prevent an attractive candidate from receiving a more forgiving standard than the incumbent.

flowchart TD
  accDescr: Workflow stages and decisions: Record the business failure, Inspect context, tools, permissions and orchestration, Is a non-model defect supported?, Fix that layer and replay cases, Does the task still fail?, Keep the model; monitor the fix, Compare models on the residual failure. The adjacent text explains the conditions and exceptions.
  accTitle: When to Upgrade an Agent’s Model—and When to Fix Its Tools workflow
    A["Record the business failure"] --> B["Inspect context, tools, permissions and orchestration"]
    B --> C{"Is a non-model defect supported?"}
    C -->|"Yes"| D["Fix that layer and replay cases"]
    D --> E{"Does the task still fail?"}
    E -->|"No"| F["Keep the model; monitor the fix"]
    E -->|"Yes"| G["Compare models on the residual failure"]
    C -->|"No"| G

The flowchart makes one point that is easy to lose in incident review: fixing a suspected dependency does not automatically close the case. Replay the task and verify the outcome. If the failure remains, the residual problem may be model behavior, a second defect, or an incomplete diagnosis. Compare models only against that residual problem, with the same inputs and a clear acceptance rule.

A hypothetical case: replacement requests that never happen

Consider a hypothetical mid-market retailer whose support agent can locate orders and submit replacement requests. In this scenario, the team has received reports that the agent tells customers a replacement is underway, but the replacement does not appear in the operations queue. The model vendor has announced a newer candidate, and a product leader suggests upgrading to see whether it handles the workflow better.

The team defines success as: identify the correct order, confirm the applicable replacement policy, submit the exact authorized request, and accurately tell the user whether submission succeeded. A successful tool response is not, by itself, the business outcome. The team also checks that a corresponding request exists in the intended test queue. This separates the model’s claim from the external result.

The first trace shows that, in several failures, order search returns a record but omits the fulfillment status required by the policy decision. The agent then gives a plausible explanation and ends the conversation. In another case, the request reaches the replacement tool, which rejects it because the customer identifier is missing. A third case shows no replacement action at all after a search timeout. Three superficially similar complaints point to three different boundaries.

The team’s first response is not to change the model. It corrects the search response in the test environment so the status is present, makes the missing identifier explicit in tool validation, and adjusts the workflow to distinguish a timeout from a completed search. These are hypothetical design changes, not claims about any particular platform. The team then replays a fixed set of cases to see which failure patterns remain.

Suppose the corrected test workflow now completes most eligible requests, but the agent still chooses the wrong policy branch for some cases where all required facts are present. That remaining issue gives the model candidate a fair test. The team compares incumbent and candidate against the same cases, with identical context, tools and permission rules. Reviewers assess both whether the policy decision is correct and whether the resulting action matches that decision.

For an illustrative calculation, assume the test set contains 80 cases: 40 routine eligible requests, 20 ineligible requests, 10 ambiguous requests that should be clarified, and 10 cases in which an allowed request must not be submitted because a required fact is missing. These counts are an assumed example, not a recommended sample size or a benchmark. A model that completes more routine cases but incorrectly acts in two ineligible cases may be worse for this workflow than one with a lower completion rate and no such actions. The team must decide that tradeoff based on the consequences, not hide it inside a blended percentage.

The decision could therefore be: keep the incumbent while completing the tool fixes; continue evaluating the candidate on the residual policy errors; and deploy only if it reduces those errors without breaching the agreed limits on incorrect actions, missing-information handling or truthful status reporting. If neither model meets the bar, the answer may be a workflow control, clearer policy representation, or a constrained human decision—not another model swap.

The important point is not that tool fixes always win. In this hypothetical, the tool and orchestration defects explain a material portion of the reported failures, while a residual model question remains. That is exactly when separating causes helps: it avoids crediting the model for work done by an improved tool, and it avoids blaming the model for failures it cannot resolve.

The migration test should make the decision inspectable

A migration decision should be reviewable by someone who did not run the experiment. Keep a compact record of the candidate, the incumbent, when the cases were run, the intended outcome, the important results and the decision. Model identifiers must be the identifiers actually used by the evaluating team; do not replace them with a display name or a remembered version label.

The table below is a reusable, hypothetical worksheet. Its identifiers are illustrative placeholders, not real vendor model IDs. The test date is stated so a team can replace it with its own actual execution date. “Not measured” is preferable to invented precision; an incomplete table should lead to a narrower conclusion, not a confident universal claim.

A table is not evidence simply because it has numbers in it. Each result needs a denominator, a definition and a traceable case set. If the team records “candidate: 92%,” it should be possible to answer: 92% of what, measured how, with which cases, and what counted as passing? Preserve examples of both improved and regressed behavior. They often explain a decision more usefully than a single headline score.

For agent workflows, the test should examine actions and outcomes as well as text. If a task can create, modify or send something outside the evaluation environment, design the test so that the effect is contained or safely simulated. A success message is not proof of completion, and a model’s assertion that it used a tool is not proof that a tool call occurred. Verify the relevant result through an independent record where the test setup allows it.

This article does not attempt to prescribe a particular latency measurement program or routing design. Teams examining end-to-end delay can use Benchmark Agent Tail Latency: Trace One Workflow End to End. Teams deciding how to choose among models at runtime can read Model Routing for Enterprise Agents: Cheap First, Escalate on Evidence. Those are different decisions from diagnosing whether a particular failure belongs to the model at all.

When a model upgrade is the right answer

An upgrade is well-founded when the team can describe a recurring, meaningful failure that persists with appropriate context, functioning tools, correct permissions and sound orchestration—and when a candidate reduces that failure on representative cases. The evidence need not establish that the candidate is better at everything. It should establish that the candidate is better for the product decision being made, within acceptable tradeoffs.

Sometimes the business requirement changes before the incumbent can meet it. A product may need a class of reasoning, instruction following or output consistency that the existing configuration does not reliably provide. In that case, the model may be the limiting component even if the surrounding system is healthy. The decision still benefits from a precise target: identify which user tasks must improve, and what behavior cannot regress.

A model change may also be justified if it simplifies the operating design or addresses a practical constraint the team has verified. But avoid treating expected simplicity as achieved simplicity. Record the actual integration work, behavior changes and operational effects after the evaluation. Do not assume that a candidate’s announcement or benchmark summary establishes what it will do inside your application.

A release evaluation can be staged rather than all-or-nothing. First test a defined set of historical or synthetic cases in a controlled environment. Then, if the results justify it, consider a limited production evaluation with a clear stop condition, safe handling of external effects and a way to return to the prior configuration. The details depend on the system; no rollout pattern removes the need to inspect actual outcomes.

For a focused process on assessing a specific new Claude release, see Evaluating a New Claude Release Without Re-Testing Everything. The useful principle is to reuse stable, relevant evaluation work where appropriate, while still testing the workflows and requirements that could be affected by the change. “We already tested a similar release” is not a substitute for checking a material change in your own application.

The counterargument: delay can become an excuse

The strongest case against my position is that a strict “prove it first” rule can become a permanent veto. Teams may lack a good evaluation set, leaders may deprioritize unglamorous maintenance, or an incumbent model may be merely familiar rather than fit for purpose. Waiting for perfect evidence can preserve a bad experience and make the product less competitive.

That is a real risk. The answer is not to lower the bar until any new release looks persuasive. It is to make evaluation proportionate and time-bounded. Define the unresolved task, assign an owner, choose an initial set of representative failures and set a decision date. If the data are too weak to support a major migration, they are also too weak to support complacency. The next action is to improve the evidence, not pretend the uncertainty has disappeared.

A second counterargument is that non-model fixes can accumulate into brittle special cases. That can happen. A series of narrow patches may make an agent harder to understand, and a model with stronger relevant behavior might simplify the system. Compare the whole proposed design, including its failure handling and maintenance burden, rather than defending each existing component automatically.

The distinction is between a reasoned system change and a release-driven substitution. If a better model allows the team to remove brittle workarounds while preserving required controls, that is a legitimate benefit to test. The team should still demonstrate that the simplification works on the cases those workarounds protected. Removing code is not a win if it returns a known failure to production.

There is also a practical risk in waiting too long to evaluate. If model selection is discussed only during incidents, the team is forced to compare under pressure, with poor case coverage and a deadline. Keep a modest, current evaluation set for important workflows and revisit it when the requirements or failure patterns change. The purpose is readiness to make a decision, not a standing obligation to upgrade.

Make the decision a product commitment, not a release ritual

A defensible decision has three parts: a named failure, evidence that locates it, and an acceptance rule for the proposed change. “The new model is smarter” supplies none of them. “The incumbent repeatedly fails to distinguish these policy cases when the required facts are present; the candidate corrects that failure on our reviewed set without increasing prohibited actions” is a testable claim—provided the team has actually measured it.

A hold decision should be just as specific. State what was tested, what did not justify migration, which defects were found elsewhere, and what event would reopen the decision. That might be a persistent residual failure, a changed product requirement, or a new evaluation result. A hold with no revisit condition can turn into neglect; a revisit condition keeps it deliberate.

For leadership, the most useful report is not a catalog of model features. It is an explanation of user impact, the suspected failure layer, the experiment performed, the remaining uncertainty and the next decision. If the issue crosses engineering and product boundaries, assign responsibility for the next investigation rather than leaving “the agent” as an ownerless system.

I recommend that CTOs treat model evaluation as part of operating the agent, but treat model replacement as a change that must earn approval through the same discipline as any other consequential system change. Begin with the failure users experience. Test the tools and context they depend on. Compare models only where a model-level question remains. Then decide from verified outcomes, not novelty or fear of falling behind.

If your team needs to establish a practical model-selection process, AI strategy and model selection is the relevant next step. The goal is not to pick a winner for every future release. It is to build a decision practice that makes clear when the model is the constraint—and when the better fix is elsewhere.

WANT TO TALK THROUGH YOUR SITUATION?

Talk it through with us. Thirty minutes, no slides.