Treat an Agent's Tool Catalog as Mutable State

An agent's tool list often arrives in the model context looking like a static menu.

Operationally, it is not static.

A tool can be added, removed, restricted by the current authorization, renamed, given a clearer description, changed behind a compatible-looking input shape, or made temporarily unavailable. A long-running agent may discover its tools, form a plan, wait for a dependency, and resume after one of those changes has happened.

If the system treats the old catalog as permanent, it creates a subtle reliability failure: the agent continues from a decision that was valid for an earlier environment.

The useful design move is to treat the catalog as mutable task state.

A tool list is a decision input beyond configuration

The current MCP tools specification says that an available tool set may change over time. It also notes that the set can vary with the authorization presented on the request. That matters because a tool choice contains more than a name:

• it assumes the tool is currently available;
• it assumes the agent is permitted to see and use it;
• it assumes its description still matches the intended task;
• it assumes its input and result contract still support the planned step; and
• for any consequential operation, it assumes the chosen tool is still the appropriate path for the effect.

None of those assumptions needs to be hidden inside a transcript.

The MCP caching guidance offers a useful systems analogy. A cached list can remain valuable, while a freshness boundary or a change notification tells the client when the list should be refreshed. The same idea applies to an agent plan: a remembered tool catalog can support efficient reasoning, but it should not be mistaken for a timeless truth.

The Tool Catalog Snapshot

The Tool Catalog Snapshot is a proposed, compact record created when an agent selects tools for a meaningful piece of work. It is not a copy of credentials, raw tool arguments, private data, or hidden reasoning. It is a reviewer-readable explanation of the environmental assumptions behind the tool choice.

• Snapshot element: Task and work-unit reference — Question it answers: Which bounded task depends on this catalog? — Why it matters: Prevents a broad tool refresh from invalidating unrelated work
• Snapshot element: Observation point — Question it answers: When and under what allowed context was the catalog read? — Why it matters: Makes freshness explicit without storing sensitive authorization material
• Snapshot element: Selected tool identity — Question it answers: Which declared capability was chosen? — Why it matters: Lets a reviewer distinguish a tool change from a model-choice change
• Snapshot element: Intended operation — Question it answers: What high-level job is the tool expected to perform? — Why it matters: Tests semantic fitness rather than name similarity
• Snapshot element: Contract expectations — Question it answers: Which input, result, effect, and failure assumptions matter? — Why it matters: Detects a compatible-looking change that alters task behavior
• Snapshot element: Authority posture — Question it answers: Is the tool visible, allowed for this task, proposed only, or ready for a separately approved effect? — Why it matters: Keeps discovery separate from permission and approval
• Snapshot element: Recheck trigger — Question it answers: What change, delay, retry, or dependency update makes the snapshot stale? — Why it matters: Gives the task a clear point for re-selection or review
• Snapshot element: Fallback and disposition — Question it answers: If the tool is unavailable or unsuitable, should the agent re-plan, hold, use a safe alternative, or ask? — Why it matters: Avoids blind retries and silent substitution

This is deliberately smaller than a complete audit log. Its job is to make a tool-dependent decision reviewable.

Different catalog changes need different responses

A sensible response depends on what changed and how the current work relies on it.

• Catalog condition: An unrelated tool is added — Safe default response: Continue the bounded task; no need to re-plan merely because more options exist
• Catalog condition: A selected tool disappears — Safe default response: Hold the affected step, re-select a suitable path, and surface a blocker if no safe alternative exists
• Catalog condition: A tool is no longer visible under the current scope — Safe default response: Treat the old plan as ineligible; do not infer that previous access remains valid
• Catalog condition: A description or result contract changes — Safe default response: Re-evaluate whether the planned operation and acceptance checks still make sense
• Catalog condition: A consequential operation's semantics are uncertain — Safe default response: Do not substitute or retry automatically; verify the current contract and required approval
• Catalog condition: A tool reports an ambiguous outcome — Safe default response: Preserve that uncertainty and reconcile the outcome before treating a retry as harmless

The key distinction is between a catalog refresh and an execution decision. Receiving a change notification can make a plan stale. It should not itself authorize a new effect.

Semantic compatibility is the hard part

Most teams notice an obvious removal. The harder case is a tool that still has the same name and accepts a similar request but now produces a different kind of result, works against a different target set, or has altered timing and recovery behavior.

The When Tools Fail preprint introduces ToolMaze and separates several kinds of tool perturbation, including implicit semantic failures. Its results are specific to that benchmark, not a universal measure of agent reliability. Our broader design inference is that success on an idealized tool path does not prove an agent will recognize when the tool environment has changed.

For a high-value tool, a team can define a small behavior check:

1. State the operation the agent expects to perform.
2. State the observable result or postcondition that would support the next task step.
3. State the failure or ambiguity that requires the task to hold, re-plan, or seek review.
4. Run that check whenever the tool's relevant contract changes.

This is a compatibility test for agent behavior, not an invitation to expose private tool details.

Discovery, authorization, and approval must remain separate

Three questions are often collapsed into one:

1. Can the agent discover this tool?
2. Is the current task permitted to use it?
3. Is the planned effect approved to proceed?

They are different questions with different evidence.

A tool can be present in a catalog while being out of scope for the task. A task can be allowed to read through a tool while a write remains subject to a separate confirmation. A previous approval can expire even though the tool still appears in the catalog.

Keeping those boundaries visible reduces an especially dangerous kind of drift: a system that interprets a refreshed tool list as renewed authority.

Re-plan selectively as conditions change

Every catalog change does not require a full task restart. The snapshot lets the system ask a narrower question:

Which planned step depends on the changed capability, and what evidence would make that step current again?

For example, an agent can retain completed research that did not depend on the changed tool. It can mark only the dependent plan branch as stale. It can request a new tool selection or hold a pending effect until the contract and authority are rechecked.

This approach is especially valuable in multi-agent work. An engineering account from Anthropic describes both the importance of tool design and the coordination cost of stateful, parallel systems. A shared, time-bounded catalog reference gives workers a way to say what they relied on without making every other worker replay their exploration.

Measures that reveal catalog drift

Teams do not need a single reliability score. They can inspect a small set of operational signals:

• stale-catalog catch rate: how often a refresh prevents a worker from continuing with an invalid tool assumption;
• semantic-change detection rate: how often a relevant behavior change is identified before an affected task advances;
• unsafe-substitution rate: how often an unavailable tool causes an automatic alternative that should have required review;
• fallback usefulness: how often the documented fallback leads to a valid, accepted task outcome;
• catalog-to-effect gap: how often visibility or selection is mistakenly treated as effect approval; and
• unnecessary-reset rate: how often an unrelated tool change causes a task to discard valid work.

The goal is not to make tool use bureaucratic. It is to make a tool-dependent plan honest about the environment it assumes.

A practical adoption path

1. Identify one long-running workflow that chooses among multiple tools or can pause and resume.
2. Record a lightweight Tool Catalog Snapshot when the workflow selects a meaningful capability.
3. Define a few recheck triggers: catalog notification, retry after delay, changed authorization posture, or relevant contract update.
4. Test one removal, one semantic change, and one ambiguity scenario in a safe evaluation environment.
5. Require a deliberate re-selection or review when the changed tool could affect a consequential outcome.
6. Review the signals above and keep only the snapshot fields that improved decisions.

The tool catalog does not need to be treated as a fragile object that freezes all work. It should be treated as what it is: a changing part of the task environment whose relevance can be scoped, checked, and explained.

The Virillio Code editorial perspective

The general lesson is to represent a tool catalog as time-bounded task context with a clear recheck rule. The Tool Catalog Snapshot is a proposed educational framework, not a description of a shipped or planned Virillio Code capability.

Sources and further reading

• Tools — Model Context Protocol — The current MCP draft permits tool sets to change over time, allows authorization-scoped availability, and describes tool-list-change notifications.
• Caching — Model Context Protocol — MCP list-result caching can coexist with change notifications, and cache scope matters for authorization-dependent results.
• When Tools Fail: Benchmarking Dynamic Replanning and Anomaly Recovery in LLM Agents — A recent preprint frames recovery and replanning under explicit or implicit, transient or permanent tool perturbations as a distinct agent capability.
• How we built our multi-agent research system — Anthropic — An engineering account identifies tool design and selection as critical to agent outcomes and describes coordination challenges in stateful systems.

Editorial disclosure

This article was substantially researched, drafted, and revised with AI through the Virillio Code editorial workflow. Virillio Code publishes the final text under its editorial byline, and the supporting primary sources are linked above.