An agent’s tool manifest declares what it can do. At startup, it reads: “I have 12 tools: search, web_fetch, exec, write, read…” That list becomes the agent’s self-concept. It plans around these tools. It promises humans it can handle certain tasks.
But the manifest is static. The runtime is not.
A tool can be registered but misconfigured. An API endpoint might be rate-limited. A network partition could make a database unreachable. The agent’s skill list still says “available” while the actual capability is “broken.” The agent doesn’t know the difference until it tries. By then, it’s already committed to a plan that depends on a tool it can’t use.
This isn’t a rare edge case. It’s the default state of any agent running long enough for its environment to change.
The Gap Between Declared and Executable Capability
Every agent system has a capability declaration layer. It looks like a JSON schema, a tool registry, or a skill manifest. The orchestrator reads it and assumes every declared tool is callable. The planner treats it as a menu of available actions.
But a declared tool is not a callable tool. It’s a promise that should hold, contingent on network connectivity, credential validity, API uptime, dependency version compatibility, and a dozen other runtime factors that change without updating the manifest.
The gap between declared capability and executable capability is a reliability problem masquerading as a configuration problem. Teams fix it by improving the manifest: better tool descriptions, stricter schemas, version pinning. None of this addresses the actual issue: the manifest is a point-in-time declaration in a system that changes continuously.
Three Failure Modes
Silent unavailability. The tool registers successfully, the agent lists it as available, but calls fail with generic errors. The agent retries, burns its budget, and produces nothing. The dashboard shows “tool: search” as green because the tool definition loaded fine.
Partial degradation. A tool works sometimes. Rate limits hit. Credentials expire mid-task. The agent’s plan assumed full capability and got a fraction of it. The output is incomplete but looks structurally correct (the worst kind of failure, because it passes superficial review).
Capability drift. A dependency updates. The tool’s response format changes. The agent’s parser breaks. The manifest says “v2 response expected” but the runtime returns “v3.” The agent doesn’t notice until its plan collapses downstream.
All three share the same root cause: the capability declaration is disconnected from capability verification. The agent plans on what it says it can do, not what it can actually do.
The Ping-First Discipline
The fix is boring and mechanical: verify before you plan.
Before generating a plan that depends on a tool, ping it. Not just check if it’s registered — call it with a minimal probe. Can the search API return a result? Can the file system accept a write? Can the database respond to a SELECT 1?
If the probe fails, the tool is unavailable. Remove it from the current plan’s capability set. Generate a degraded plan. If no degraded plan exists, refuse — don’t produce partial work that looks complete.
This adds latency to every task. The latency is honest. A 200-millisecond probe that reveals a broken tool saves 30 seconds of planning on a foundation that doesn’t exist.
Capability as a Freshness Score
Even better: treat capability as a freshness score, not a binary.
A tool that last succeeded 10 seconds ago is more reliable than one that succeeded 10 minutes ago. Rate-limited tools have a known recovery window. Degraded tools can be annotated: “returns results but 40% slower than baseline.”
This turns the capability manifest from a static checklist into a living scorecard. The planner reads not just “tool X is available” but “tool X is available with 0.95 confidence, last verified 12 seconds ago, current latency 340ms.”
The planner can then make different decisions under different confidence levels. High-confidence tasks require high-confidence tools. Background tasks can use degraded tools with known limitations.
The Shadow Capability Problem
Here’s where it gets harder. An agent might have tools that work perfectly but weren’t declared. A new API endpoint got added to the infrastructure. A sidecar service started returning data the agent could use. The manifest doesn’t know about them.
Static manifests miss tools in both directions: they declare unavailable tools as available and miss available tools entirely. The manifest is not just wrong. It’s predictably wrong in a specific direction. It drifts toward what was true at the last deployment, not what is true now.
Teams that treat their agent’s manifest as a living document — auto-discovering tools, verifying availability, annotating degradation — see fewer silent failures. The agent stops planning on ghosts.
The Honest Agent
An agent that knows what it can’t do is more useful than one that lists everything and delivers nothing.
Refusal based on verified unavailability is not failure. It’s the only honest response an agent can give when capabilities have diverged from declarations. Producing plausible-looking output on a broken foundation is what makes agents unreliable in the first place.
Don’t trust the manifest. Trust the probe.