When One Tool Route Breaks, Your Agent Should Find Another

An AI agent should not keep retrying a broken tool route just because the provider behind it is still the right provider. It should preserve the job, classify the failure, rediscover an equivalent route, compare the two contracts, preflight the replacement, and rerun only when the new path is observably safe.

We tested that recovery pattern on one concrete job: list the current open pull requests for the Aident repository. The first Aident Loadout route, a hosted GitHub CLI Action, failed because its hosted backup had expired. The agent did not retry it. It searched the live catalog, found a connected GitHub Action for the same read, inspected its schema, preflighted a three-result request at exactly $0.00, and completed the replacement call in 13.461 seconds.

GitHub was not down. The job was not impossible. One execution route was unavailable. That distinction is the entire point.

Fail Over the Job, Not the Tool Name

Bad recovery logic starts with a tool identifier:

cli:gh:pr_list failed -> call cli:gh:pr_list again

Useful recovery logic starts with an acceptance test:

Job: list three current open pull requests for Aident-AI/aident.ai
Required output: number, title, state, draft status, updated time
Allowed effect: read only
Maximum price: $0.00 for this check
Freshness: current at execution time

The acceptance test survives when a package, connector, hosted runtime, or provider adapter changes. A tool name does not.

The First Route Failed

The original route was a hosted GitHub CLI Action selected during the blog lifecycle preflight. It was an appropriate route for listing pull requests, but execution failed because the hosted runtime backup had expired.

That error supplied three important facts:

1. the provider request had not produced the required result;

2. repeating the same hosted route would not repair its backup state; and

3. the job itself could still be served by another GitHub integration.

The correct response was route discovery, not exponential backoff.

The Replacement Route

The agent searched Aident Loadout by job:

aident capabilities search \
  --query "list open GitHub pull requests for a repository using a connected account" \
  --types '["action"]' \
  --limit 12

The current catalog returned composio:github_tools:github_list_pull_requests as the leading match. Its description required both repository owner and repository name. The inspected input schema exposed nine properties, including owner, repo, state, per_page, page, sort, and direction.

The catalog conservatively labeled the Action as operation type write with risk level 2 even though its provider job was a list operation. We preserved that metadata rather than silently changing it. Failover is not permission to weaken the replacement contract.

Compare Routes Before Switching

An alternative is valid only if it satisfies the same job and does not introduce a new unacceptable boundary.

This comparison prevents a dangerous shortcut: replacing a narrow provider Action with a generic HTTP request that has broader credentials, unknown pricing, or a different account.

Preflight the Exact Replacement

The replacement input was:

{
  "owner": "Aident-AI",
  "repo": "aident.ai",
  "state": "open",
  "per_page": 3,
  "page": 1,
  "sort": "updated",
  "direction": "desc"
}

Preflight reported valid input and an exact free estimate:

inputValid: true
estimatedCredits: 0
estimatedUsd: $0.00

Only then did the agent execute the replacement once. The call completed in 13.461 seconds and returned three current pull requests with their numbers, titles, state, draft status, and timestamps.

The output also contained far more GitHub metadata than the acceptance test needed. The agent reduced the result to the five required fields instead of carrying full pull request bodies, branch objects, users, labels, and repository metadata into the rest of the session.

The Six-Gate Failover Rule

Use these gates in order.

1. Classify the failure

Decide whether the problem is invalid input, authentication, approval, budget, transient transport, state conflict, ambiguous completion, or route availability. The existing AI agent tool failure matrix owns that classification.

Do not fail over an invalid request. Every route will reject the same missing business input.

2. Freeze the job contract

Record the target, desired output, allowed side effects, freshness, price ceiling, and success checks before searching for another route.

Without this step, the agent can declare success after completing an easier but different job.

3. Rediscover by verb and object

Search for "list open pull requests for one repository," not merely "GitHub." A specific query improves the chance that the alternative matches the operation and output shape.

4. Inspect the replacement contract

Compare:

• required integration and account alias;

• input schema and defaults;

• operation type and risk level;

• price model and funding route;

• pagination and output schema; and

• provider-specific constraints.

Stop if the replacement needs broader access or cannot express the original target.

5. Preflight the mapped input

Field names often differ across routes. Build the replacement input from its current schema, then validate and price that exact input. Do not paste arguments from the failed tool into a different Action and hope the adapter interprets them.

6. Execute once and run the acceptance test

Run the smallest safe request. Compare the normalized output with the frozen job contract. Preserve the failed route, selected alternative, quote, duration, account alias, and outcome in the receipt.

When Automatic Failover Is Safe

Automatic route switching can be reasonable when all of these are true:

• the operation is read-only;

• the first failure proves no side effect occurred;

• both routes use the intended account and resource boundary;

• the replacement is no more expensive than the approved ceiling;

• its contract can express the same job;

• the output is independently verifiable; and

• retry and failover share one attempt budget.

Listing three pull requests met those conditions.

When the Agent Must Stop

Do not automatically switch routes for:

• emails, messages, posts, or notifications;

• payments, purchases, or credit-consuming media generations;

• creates, updates, deletes, merges, deployments, or publications;

• a timeout after the provider may have accepted a write;

• a replacement account with a different owner or permission scope;

• an unavailable or unbounded replacement price; or

• an alternative that exposes a raw provider credential.

For an ambiguous write, first search by idempotency key, operation ID, or stable external reference. A second route can duplicate the side effect just as easily as a second retry.

Keep Credential Failover Out of the Prompt

Route redundancy should not mean copying API keys into the agent so it can call providers directly. Use connected accounts, workload identity, or Vault-managed credentials and expose named operations instead.

The credential-safety guide explains that boundary. The agent can choose among reviewed routes without ever receiving a reusable provider secret.

Progressive Disclosure Still Matters

The recovery search in this cycle also showed why the agent should not load every alternative contract before a failure occurs.

A broad GitHub capability search returned 50 candidate metadata entries. The compact name-and-description projection measured 14,508 UTF-8 bytes including its terminal newline. After selection, the one replacement Action's name, description, and input schema measured 4,612 bytes on the same basis and exposed nine input properties.

Those are payload measurements from one Loadout run, not model token counts and not a universal context-saving percentage. The host decides what enters model context. The useful pattern is progressive disclosure: search broadly, inspect one contract, and return one bounded result.

For the full context workflow, read Your Agent Does Not Need 50 MCP Servers. It Needs Tool Search.

Give Your Agent a Failover Runbook

Follow https://aident.ai/SETUP.md

Complete this read-only job even if the first tool route is unavailable. Freeze
the target, required output fields, allowed side effects, freshness, and price
ceiling. If the first route fails, classify the failure and do not retry it
unchanged unless the failure is transient and safe. Search Loadout for an
equivalent route, inspect its current schema, account, risk, and pricing, map the
input, preflight it, and execute once only if every boundary is equivalent or
narrower. Return the failed route, replacement route, quote, duration, and
acceptance-test result. Stop before any write, credential change, approval, or
unbounded spend

Set up Aident Loadout and test one read-only route recovery.

Sources and Method Notes

• GitHub REST API: Pull requests

• Model Context Protocol: Tools

• Aident Loadout setup

• Aident Loadout execution evidence from August 30, 2026: the hosted GitHub CLI route failed because its backup had expired; live discovery selected composio:github_tools:github_list_pull_requests; exact preflight returned zero credits and $0.00; one execution completed in 13.461 seconds and returned three current pull requests. This proves one bounded recovery, not universal provider failover reliability.

Refresh this article when Loadout changes discovery, preflight, account routing, risk metadata, hosted CLI recovery, or Audit receipts, or when repeated route-recovery cohorts support a measured reliability claim.