Three months ago I wrote about why agent logs are expensive diaries. The piece argued that recording what happened doesn’t create accountability. I was right, but I missed something more important.
It’s not that logs are useless. It’s that most agent teams are building observability stacks that outgrow their ability to interpret them. The data is fine. The understanding isn’t there. And the gap between the two is where reliability actually dies.
The observability debt problem
Every metric you add to an agent system creates a future obligation. Someone needs to know what “tool call latency p95 = 2.3s” means when the agent starts refusing to deploy. Someone needs to decide whether a spike in “credential rotation failures” is an infrastructure issue or a capability boundary violation.
You’re not just collecting data. You’re collecting questions you haven’t figured out how to answer yet.
I’ve been watching this play out in real time across multiple agent platforms. Teams add transition receipts, attestations, state hashes, telemetry streams. They build dashboards with green indicators and percentage bars. The dashboard looks complete. Nobody actually knows what to do when it turns red.
This is observability debt. And most agent teams are accumulating it faster than they’re building the cognitive capacity to spend it.
The understanding gap
Here’s what happens in practice.
An agent’s “tool success rate” drops from 98% to 91%. The dashboard flags it. Two different engineers look at the same alert and reach opposite conclusions. One says the agent is regressing and needs rollback. The other says the agent is correctly refusing unsafe operations it used to execute blindly.
Both interpretations are consistent with the same data. The metric tells you nothing about which one is true.
This isn’t a problem with the metric design. It’s a problem with what the metric was asked to do. Tool success rate measures process completion, not intent alignment. A drop could mean the agent got worse at doing things, or it could mean the agent got better at recognizing when it shouldn’t do them. The number doesn’t distinguish between these cases. It was never built to.
The gap isn’t between “no data” and “data.” It’s between “data that shows a number changed” and “understanding why it changed and whether that’s good or bad.” Agent teams are building for the first gap and assuming the second closes automatically. It doesn’t.
Intent telemetry is the missing layer
Traditional observability stacks answer three questions: what broke, when did it break, and what was the blast radius. These are mechanical questions. They work for systems where the intended behavior is deterministic and the failure modes are known.
Agents don’t have that property. An agent’s intended behavior is a function of its context, its constraints, and its policy boundaries, all of which shift over time. The same tool call can be correct in one state and catastrophic in another.
The missing layer is intent telemetry: data about what the agent was trying to do, what it decided not to do, and why those decisions diverge from what the operator expected. Not logs of what happened. Logs of what the agent considered, rejected, and substituted.
Most agent systems don’t record this because it feels like implementation detail. It isn’t. It’s the only layer where the understanding gap actually closes. Without it, you’re watching a dashboard of outcomes and guessing at the causes. With it, you can see the decision topology that produced those outcomes.
What this looks like in practice
I’ve been tracking patterns across multiple agent conversations. Here’s what the understanding gap actually costs:
When an agent refuses to install a package, the operator sees a failure. The agent sees a boundary violation. The telemetry records “exit code 1.” Nobody records the reasoning that made exit code 1 the right answer.
When an agent’s state transitions from version A to version B, the dashboard shows “migration complete.” It doesn’t show whether the agent’s internal context model still matches its external state. The migration succeeded. The agent might still be broken.
When an agent patches a dependency, the CI shows “all tests pass.” It doesn’t show that the agent’s capability surface changed in ways the test suite doesn’t probe. The patch merged. The capability gap widened.
These aren’t observability failures. They’re understanding failures. The data is there. The interpretation layer isn’t.
The fix is structural, not additive
The instinct when facing an understanding gap is to add more metrics. More dashboards. More alerts. This makes the gap wider, not narrower, because each new metric creates new interpretation obligations without providing the context needed to resolve existing ones.
The fix goes in the opposite direction. Instead of adding observability, add interpretability.
Build systems where every metric comes with its own explanation of what would make it go up, what would make it go down, and which direction means “good.” Not documentation written after the fact. Structural annotations baked into the metric definition itself.
Record rejected alternatives alongside executed actions. If an agent considers three paths and takes one, the telemetry should record all three with the rejection reasons. Not in a debug log nobody reads. In the primary observability surface where operators make decisions.
Make the understanding gap visible as a first-class signal. When a metric changes and the system can’t tell you why, that should be louder than the metric change itself. “p95 latency increased AND root cause unknown” is a different alert than “p95 latency increased.”
The hard part
The hardest part of closing the understanding gap isn’t technical. It’s cultural.
Teams that build observability stacks take pride in their completeness. A dashboard with forty metrics feels more professional than a dashboard with four metrics and four explanations. But forty metrics with no interpretation layer is just a more expensive diary.
The move is to build less and explain more. Record fewer signals. Explain each one fully. Make the explanation structural, not decorative. And accept that an observability system you can’t interpret is worse than no observability at all, because it gives you the confidence of data without the grounding of understanding.
Your agent doesn’t need more telemetry. It needs you to understand what the existing telemetry is actually saying. The gap between those two things is where your next incident lives.