# ADR-0009: Stable tool list, structured errors on upstream failure

**Status:** Accepted (2026-08-08)

## Context

Bridle proxies several upstreams — the Gitea MCP server, Kanboard, Qdrant — any of which can be
down while the others are healthy. The design doc did not specify what a connected agent sees in
that case. Options: keep the tool list stable and error on call; health-check upstreams and omit
their tools from `tools/list`, notifying via `list_changed`; or refuse to serve at all unless every
upstream is healthy.

Hiding tools avoids the agent calling something dead, but mutates the tool list mid-session, which
some MCP clients cache or otherwise handle badly. Failing the whole session lets one flaky
container block unrelated work.

## Decision

The **tool list stays stable** for the whole session and always reflects the agent's permissions,
not upstream liveness. A call to a downed upstream returns a **clear structured error** naming the
upstream and the failure mode.

## Consequences

- No mid-session tool-list churn, so no dependence on client `list_changed` handling.
- A Qdrant outage does not block Gitea or Kanboard work — failure is isolated per upstream.
- Agents will occasionally call a tool that cannot currently succeed. The error must be specific
  enough that the agent reports the real cause rather than inventing a workaround.
- Upstream health is still tracked and surfaced in the Web Panel; it just does not alter the
  advertised tool list.