AI Agent Observability for MCP Tool Changes: Prove Discovery Converged

An AI agent that uses MCP tools is not healthy merely because its process is alive, its server connection is open, or it received a tool list change notification. The practical check is stricter: after a relevant change, did the client complete a fresh tools/list traversal, follow pagination to the end, and replace its registry with the exact tool definitions it discovered? Treat that as a convergence test. Record the negotiated MCP protocol version and tools.listChanged capability, the last notifications/tools/list changed time, discovery start and completion times, every cursor, and canonical digests of the discovered and installed registries. Return converged , stale , incomplete , or unverifiable . Do not turn missing evidence into a green result. Define convergence at the protocol boundary The MCP lifecycle specification requires initialization before normal operation. Client and server negotiate a protocol version and capabilities, and both sides must respect that negotiation. A successful initialization proves that one session started under an agreed contract. It does not prove that a later tool change reached the client. The MCP tools specification supplies the next pieces: a server that supports tools declares the tools capability; listChanged says whether it will emit tool list change notifications; clients discover definitions through tools/list ; discovery can be paginated through nextCursor ; a tool definition includes more than its name, notably inputSchema and optional outputSchema , annotations, and execution metadata. This creates three separate events that monitoring must not collapse: 1. Change signal: the client receives notifications/tools/list changed . 2. Discovery: it starts a new tools/list traversal and reaches a response whose nextCursor is absent or null. 3. Registry install: the definitions used by the client match the completed discovery snapshot. The notification is a hint to refresh, not a receipt for completed refresh. A first page is activity, not a complete registry. Matching names are not matching contracts when a required argument, output schema, or execution property changed. Keep the evidence small but decisive A useful health record does not need prompts, tool arguments, credentials, or tool results. It needs enough safe metadata to answer whether the client and server still agree: Field What it establishes What it does not establish protocolVersion The MCP version negotiated for the session That a later server release remained compatible tools.listChanged Whether change notifications were negotiated That any notification was delivered or handled notificationAt A refresh became due That discovery started discoveryStartedAt and discoveryCompletedAt A bounded refresh ran after the signal That every page was fetched cursor chain Pagination ended without a gap That the client installed the result discovered registry digest Identity of the complete definition set That a tool call will succeed client registry digest Identity of what the client currently exposes to the agent That the agent will choose correctly Build the digest from a stable projection: name , title , description , inputSchema , outputSchema , annotations , and execution . Sort tools by name and canonicalize nested JSON before hashing. Decorative icons can be excluded if they do not affect selection or execution, but the projection itself must be versioned. RFC 8785 explains why repeatable hashing requires invariant JSON serialization and recursive property sorting. The compact recursive sorter used in this experiment is adequate for the fixture’s ordinary JSON values; it is not presented as a complete JCS implementation. Production code should use a reviewed canonicalization library, especially when numeric edge cases or signatures matter. Do not store raw secrets in the registry snapshot. Tool schemas should describe argument shapes, not credential values. If a description contains tenant data or internal paths, redact it before collection and record which projection version produced the digest. Reproduce a six case registry audit The retained fixture uses six synthetic observations: a complete two page baseline; a tool removal followed by a complete refresh; a change notification followed by no new discovery; page one with a remaining nextCursor ; the same tool name with a changed required input schema; a server that did not advertise listChanged , with no bounded refresh evidence. The core decision order matters: Run the fixture with Node.js: The exact replay returned: The counterexamples are more useful than the two green cases. notification without refresh has identical discovered and client digests, yet its discovery completed before the change signal. A digest match against an old snapshot is still stale. unfinished pagination also has matching digests for the one observed page, but nextCursor remains. A plausible page one match is incomplete evidence. The same name case changes read ticket from requiring only ticketId to requiring both projectId and ticketId . A name only inventory would call the registry unchanged. The canonical definition digest changes from c42521a2412558ca to c3837b93f14b688f , so the client’s old definition is classified stale. Turn the verdict into an operating decision Use converged narrowly. It means the observed client registry matches one fully traversed discovery completed after the relevant change signal. It does not prove transport reachability for the next call, valid authorization, correct tool behavior, a successful external effect, or the intended task outcome. Handle the other states without aggressive automation: Verdict Evidence Safe next move stale Refresh is older than the signal, or registry digests differ Stop selecting the affected definition; request one bounded refresh; inspect before retrying consequential work incomplete Discovery started but cursor traversal or completion evidence is missing Resume from the expected cursor if the client supports it, otherwise restart discovery once unverifiable No bounded discovery evidence exists Report the signal as unavailable; reconnect or schedule a controlled refresh according to the runtime’s policy converged Complete post change discovery and exact digest match Continue, while retaining separate call, effect, and outcome checks If the server did not advertise listChanged , silence is expected and cannot establish freshness. Define a bounded alternative: refresh on reconnect, before a high impact run, or at a measured interval that fits the server’s cost and rate limits. Record that policy so “no notification” is not mistaken for “no change.” Also separate registry health from task health. A tool can be present and correctly described while its credential is expired. It can return isError: false while the promised ticket, file, or deployment is absent. After any approved recovery, verify the external effect or task outcome instead of declaring success because discovery or a command completed. Preserve the product and authority boundary This check belongs in AI agent observability because tool availability and permission drift can block useful progress while the agent remains active. It is a health signal, not an authorization to restart a runtime, rotate credentials, invoke tools, or repeat spend. Consequential intervention should remain bounded, visible, and subject to human approval. Sidewisp’s intended direction is a health layer around existing agent runtimes: show evidence, freshness, severity, uncertainty, and the safest next action. The MCP convergence record in this article is an operating pattern and experiment, not a claim that Sidewisp currently collects it. Sidewisp is currently in private preview. The public site and article system are live. Production agent health collection, MCP runtime adapters, automated recovery, cron management, and token cost analytics are not generally shipped. Join the private preview if you want to help shape evidence contracts such as protocol negotiation, registry convergence, tool availability, and verified outcomes while keeping human authority explicit.