The openclaw-upgrade-orchestrator-mcp is a read-only MCP server for safe, catalog-grounded AI runtime upgrade orchestration (primarily OpenClaw), providing regression awareness, pre/post snapshot diffing, and provider-side drift detection — without ever executing upgrades itself.
Check current version (current_version): Retrieve the currently-installed OpenClaw version and detection method, confirming the backend is reading your deployment correctly.
List available upgrades (available_upgrades): See all newer versions with flags for CRITICAL regressions in their upgrade path, plus a recommended safest target version.
Capture a pre-upgrade snapshot (pre_upgrade_snapshot): Run all detection checks against your live deployment, persist the results, and receive a snapshot_id for later verification or rollback planning.
Get a step-by-step upgrade guide (upgrade_guide): Generate a full upgrade plan to a specified target, including pre-upgrade prep, upgrade commands, post-upgrade steps, rollback instructions, and known regression mitigations.
Verify the upgrade outcome (post_upgrade_verify): Diff post-upgrade state against a pre-upgrade snapshot, classifying results as new_failures, recovered, or unchanged_failures, with an overall outcome of success, degraded, or regressed.
Get a rollback guide (rollback_guide): Generate a recovery plan tied to a specific snapshot, including downgrade commands, state-restore steps, and risk notes.
Browse the regression catalog (regression_catalog): Query the full catalog of known OpenClaw regressions (8 entries in v1.0), each with severity, description, mitigation, and field report links — optionally filtered by version.
List stored snapshots (list_snapshots): View all previously captured snapshots with IDs, timestamps, versions, and summaries.
Detect provider-side drift: Monitor LLM provider behavior (e.g., latency, response length) to detect silent changes that may impact AI agent performance even without an explicit upgrade event.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@openclaw-upgrade-orchestrator-mcp check available upgrades for my OpenClaw deployment"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for safe AI agent runtime upgrades — version-aware regression catalog, pre/post snapshot diffing, step-by-step upgrade + rollback guides. Captures deployment state before upgrade, re-runs detection checks after, surfaces
new_failures(caused by the upgrade) separately fromunchanged_failures(pre-existing) andrecovered(fixed by the upgrade). Read-only by design — never executes the upgrade itself; the operator retains full agency. v1.0 ships with the OpenClaw regression catalog (8 entries grounded in real field reports); the same machinery accepts a custom catalog for any AI runtime via Custom MCP Build adapters. Keywords: AI runtime upgrade, regression detection, safe deployment, version-specific bug catalog, AI agent ops.
Production AI runtime upgrades — OpenClaw, Claude Code, agent harnesses, runtime servers — carry recurring regressions that you only find after upgrading. Recent examples:
The "claw tax." Anthropic announced standard Claude subscriptions would no longer cover usage through external "claw" harnesses like OpenClaw — forcing those workloads onto metered API billing — without a clean upgrade path. r/AI_Agents thread on the OpenClaw creator suspension (201 pts, April 12 2026) walks through the structural conflict.
OpenClaw 2026.4.8 brought a CPU-spike bug. 2026.4.23-26 broke Discord on_message. 2026.4.30+ surfaced OOM under sustained 200k-token contexts. The pattern: upgrade on Friday, hit a new failure mode on Tuesday, spend Wednesday-Thursday excavating release notes + field reports.
Claude Code itself has documented compaction failures at 48% context usage (GitHub Issue #23751) and the "1M context window does not work as marketed" complaint (GitHub Issue #35296) — recurring upgrade regressions in the underlying runtime, not just OpenClaw.
HERMES.md detection (the billing routing bug) is itself an upgrade regression — Anthropic added detection logic that fires false positives, and operators only discover it when they're already $200 deep in unintended API charges.
This MCP server moves the regression excavation upfront — before the upgrade, not after — and verifies the post-upgrade state by diffing against a snapshot you took beforehand. Read-only by design: never executes the upgrade itself; the operator retains full agency.
> claude: should I upgrade my 2026.4.23 deployment?
[MCP tools: current_version + available_upgrades]
Current: 2026.4.23
Recommended target: 2026.5.2 (no CRITICAL regressions in path)
Available upgrades:
2026.4.24-.26 HIGH R-73421 Discord-receive breakage
2026.4.27 — clean
2026.4.30 HIGH R-OOM-DURING-LARGE-CONTEXT (unfixed)
2026.5.1-.2 HIGH R-OOM + R-LOG-ROTATION-DROP (unfixed)> claude: walk me through upgrading to 2026.4.27.
[MCP tool: upgrade_guide]
2026.4.23 → 2026.4.27 — proceed with mitigations applied.
Applicable known regressions:
R-41372 (HIGH) — Cron --session web-search silent fail.
Mitigation: silentwatch-mcp covers detection until upgrade.
R-73421 (HIGH) — Discord-receive callbacks not firing.
Mitigation: `openclaw skill reload discord` after upgrade.
Pre-upgrade steps:
1. Capture pre-upgrade snapshot (call pre_upgrade_snapshot)
2. Verify backups: cp -r ~/.openclaw ~/.openclaw.backup-$(date +%Y%m%d)
Upgrade steps:
1. openclaw gateway stop
2. openclaw upgrade --to 2026.4.27
3. openclaw gateway start
Post-upgrade steps:
1. Run post_upgrade_verify(snapshot_id=<your-pre-upgrade-id>)
2. openclaw skill reload discord (R-73421 mitigation)
Rollback steps: stop → openclaw upgrade --to 2026.4.23 → restore backup → start.
Confidence: Path includes 2 HIGH regressions but no CRITICAL.> claude: I just upgraded. Verify it.
[MCP tool: post_upgrade_verify(pre_snapshot_id="snap-...")]
Upgrade 2026.4.23 → 2026.4.27: SUCCESS.
0 new failures, 1 recovered (skills.discord_receive_registered),
0 unchanged failures.v1.2 — provider-side regression detection. The other half of the upgrade-safety story: when the hosted LLM provider silently changes their model behavior with no upgrade event on your side. Source: Anthropic April 23 2026 post-mortem — Anthropic admitted silently changing Claude Code's default reasoning effort for 5 weeks (Mar 4 → Apr 7) without notification. Verbatim from a Phoenix user asking for the feature in their own community discussions (#10442): "Does Phoenix have a way to detect this kind of silent drift where surface metrics look healthy but the model is actually failing?" And from Om Patel @om_patel5 on X (171K views, 1.3K likes, 195 RTs): "OPUS 4.6 JUST ADMITTED ITS REASONING EFFORT IS SET TO 25 OUT OF 100" — operator extracted the current setting directly from the model. v1.3 backlog idea: add an active-extraction tool that runs scheduled probes ("what is your current reasoning_effort?") + records the model's self-reported settings over time, complementing v1.2's passive latency/response-shape fingerprinting. This server now does the passive part.
> claude: has Anthropic regressed something on their end in the last hour?
[MCP tool: detect_provider_regression(provider="anthropic")]
Severity: CRITICAL
provider: anthropic
current_window_hours: 1 sample_count: 50
baseline_window_hours: 168 sample_count: 1000
Alerts:
[CRITICAL] latency_p95: 3,200ms vs 1,500ms baseline (+113%)
[HIGH] latency_median: 1,500ms vs 800ms baseline (+87%)
[MEDIUM] response_length_median: 350 vs 800 (-56%)
Summary: anthropic: 3 alerts — worst is CRITICAL on latency_p95:
latency_p95 is 113% higher than baseline (3200 vs 1500) — likely regression> claude: capture the next 100 calls so I can see the fingerprint over time.
[MCP tool: record_provider_call (called by your LLM-client shim, once per response)]
After enough calls accumulate:
[MCP tool: get_provider_fingerprint(provider="anthropic", window_hours=24)]
provider: anthropic
window_hours: 24 sample_count: 240
fingerprint:
call_count: 240
median_latency_ms: 850
p95_latency_ms: 1620
median_response_length_tokens: 760
distinct_models: ["claude-sonnet-4-7"]
most_common_model_version: "claude-sonnet-4-7-20260301"Related MCP server: dep-diff-mcp
openclaw-upgrade-orchestrator-mcpThree things existing tools (vendor changelogs, internal runbooks, generic CI/CD orchestrators) don't do:
Catalog-grounded regression awareness. A generic upgrade tool tells you the version exists. This server tells you which versions have known issues, which fix versions remediate them, and which mitigations apply if you have to use the affected version.
Pre/post snapshot diffing tied to the catalog. The same checks run before + after the upgrade. The diff highlights new_failures (caused by the upgrade) separately from unchanged_failures (pre-existing) and recovered (fixed by the upgrade). No more "did this break in 2026.4.27 or was it already broken?"
Read-only by design. Never runs openclaw upgrade --to ... for you. Never modifies state. Operators retain full agency over the actual upgrade — this server gives them the information to make the decision, then verifies it after they execute.
Built for the production-AI operator who owns OpenClaw deployments and has been through enough upgrade-day fire drills.
Tool | What it returns |
| Currently-installed version + detection method |
| Newer versions with regression-count flags + recommended target |
| Captures every check's pass/fail state, persists with snapshot_id |
| Step-by-step plan: pre / upgrade / post / rollback steps + applicable regressions + confidence note |
| Diff post-upgrade against a stored pre-upgrade snapshot — new_failures / recovered / unchanged |
| Recovery plan for a given snapshot — downgrade command + state-restore steps + risk note |
| Full known-regression catalog, optionally filtered to one version |
| All stored snapshots (id + version + summary) |
| Append a single provider API call observation to the fingerprint history |
| Aggregate fingerprint over a window — call count, latency p50/p95, response-length distribution, distinct models, most-common headers |
| Compare current vs baseline window; flag distribution shifts with severity |
Resources:
upgrade://current — current version info
upgrade://snapshots — every stored snapshot
upgrade://catalog — full regression catalog
upgrade://provider-fingerprint (v1.2) — current Anthropic 1-hour fingerprint
Prompts:
plan-upgrade(target_version) — walks through the upgrade decision
verify-upgrade(pre_snapshot_id) — walks through post-upgrade verification
diagnose-provider-regression(provider) (v1.2) — walks through a no-user-upgrade-event regression
pip install openclaw-upgrade-orchestrator-mcpAfter install, run the bundled demo to see the upgrade-orchestrator analyze a representative deployment:
openclaw-upgrade-orchestrator-mcp-demoYou'll see a 5-step walkthrough: current version 2026.4.23, recommended upgrade target 2026.5.2 (heuristically skips broken middle versions), 2 known regressions affecting 2026.4.23 (R-41372 web-search silent fail + R-73421 Discord receive breakage), full 11-step upgrade plan with rollback commands, and pre-upgrade snapshot showing 1 of 6 checks would fail. Read-only — never executes any upgrade. No external I/O, no API keys — safe to run anywhere.
{
"mcpServers": {
"openclaw-upgrade": {
"command": "python",
"args": ["-m", "openclaw_upgrade_orchestrator_mcp"],
"env": {
"OPENCLAW_UPGRADE_BACKEND": "mock"
}
}
}
}Backend | Status | Description |
| ✅ v1.0 | 2026.4.23 deployment with active R-73421 Discord-receive breakage; in-memory snapshots; suitable for protocol verification + bundle demos. v1.2: also pre-populates a synthetic 7d-baseline + last-hour-regression-burst on Anthropic so |
| ✅ v1.0 | Reads |
8 hand-curated entries covering documented OpenClaw regressions:
R-41372-CRON-WEB-SEARCH-SILENT-FAIL (HIGH, 2026.4.20–2026.5.1)
R-63002-POST-UPGRADE-CPU-SPIKE (CRITICAL, 2026.4.8–2026.4.10)
R-73421-DISCORD-RECEIVE-BREAKAGE (HIGH, 2026.4.23–2026.4.27)
R-GATEWAY-PORT-CONFLICT-2026.4.15 (MEDIUM, 2026.4.15–2026.4.18)
R-OOM-DURING-LARGE-CONTEXT-2026.4.30 (HIGH, 2026.4.30–unfixed)
R-STATUS-RECONCILIATION-DRIFT-2026.4.5 (LOW, 2026.4.5–2026.4.10)
R-CLAWHUB-CACHE-POISONING-2026.3.28 (HIGH, 2026.3.28–2026.4.2)
R-LOG-ROTATION-DROP-2026.5.1 (MEDIUM, 2026.5.1–unfixed)
Use regression_catalog for the full, queryable list.
available_upgrades flags every version reachable from current and computes a recommended_target:
For each available version V > current:
applicable_regressions = regressions_in_path(current, V)
has_known_critical = any(r.severity == CRITICAL for r in applicable_regressions)
recommended_target = highest V with has_known_critical == Falseregressions_in_path(current, target) includes a regression if:
The target version is in the regression's range (post-upgrade deployment will be affected), OR
The current version is in the regression's range (current deployment is already affected — the operator should know whether the upgrade fixes it)
OpenClaw upgrades atomically (no execution on intermediate versions), so a regression strictly between current and target without affecting either endpoint is NOT included. This avoids over-conservative recommendations.
Version | Scope | Status |
v1.0 | mock + openclaw-system backends, 8 tools / 3 resources / 2 prompts, 8-entry regression catalog, 6 detection checks, GitHub Actions CI matrix, PyPI Trusted Publishing | ✅ |
v1.2 | Provider-side regression detection — | ✅ |
v1.3 | Catalog auto-fetch from upstream changelog feed; richer detection checks tied to OpenClaw's | ⏳ |
v1.4 | Custom catalog packs (operator can ship internal-only regression entries alongside the canonical catalog); rule-overrides | ⏳ |
v1.x | Webhook emit on detected regression; integration with CI to gate merges of OpenClaw-version bumps | ⏳ |
If your AI deployment uses a different runtime (custom agent harness, internal fork of OpenClaw, vendor-locked deployment) and you want the same regression-aware upgrade discipline, that's a Custom MCP Build engagement.
Tier | Scope | Investment | Timeline |
Simple | Single backend adapter for your existing version-source | $8,000–$12,000 | 1–2 weeks |
Standard | Custom backend + custom regression catalog (initial 10-15 entries from your incident history) + integration with your alerting | $15,000–$25,000 | 2–4 weeks |
Complex | Multi-deployment fleet view + auto-catalog ingestion from internal changelog + per-environment recommendation tuning | $30,000–$45,000 | 4–8 weeks |
To engage:
Email hello@temhan.dev with subject Custom MCP Build inquiry — upgrade orchestration
Include: 1-paragraph description of your runtime + which tier
Reply within 2 business days with a 30-min discovery call slot
This server is part of a production-AI infrastructure MCP suite — companion to silentwatch-mcp, openclaw-health-mcp, openclaw-cost-tracker-mcp, and openclaw-skill-vetter-mcp. Install all five for full operational visibility.
If you're running production AI and want an outside practitioner to score readiness, find the failure patterns already present (upgrade regression cycles being one of the most damaging), and write the corrective-action plan:
Tier | Scope | Investment | Timeline |
Audit Lite | One system, top-5 findings, written report | $1,500 | 1 week |
Audit Standard | Full audit, all 14 patterns, 5 Cs findings, 90-day follow-up | $3,000 | 2–3 weeks |
Audit + Workshop | Standard audit + 2-day team workshop + first monthly audit included | $7,500 | 3–4 weeks |
Same email channel: hello@temhan.dev with subject AI audit inquiry.
PRs welcome. Detection checks are pluggable — see src/openclaw_upgrade_orchestrator_mcp/checks/__init__.py for the contract.
To add a check:
Define def run(state: DeploymentState) -> CheckResult in the checks module
Register it in CHECKS: dict[str, callable]
Reference its check_id from a regression's detection_check_id in catalog.py
Add tests in tests/test_checks.py
To add a backend:
Subclass UpgradeBackend in backends/<your_backend>.py
Implement collect_state, save_snapshot, load_snapshot, list_snapshots
Register in backends/__init__.py
Add tests in tests/test_backends.py
To add a regression entry:
Append to CATALOG in catalog.py with stable regression_id
Reference an existing or new detection_check_id (or set to None for advisory-only)
Add a test confirming version-range membership in tests/test_catalog.py
Bug reports + feature requests: open a GitHub issue.
MIT — see LICENSE.
Production-AI MCP Suite (Gumroad bundle) — this server plus 4 others in one curated bundle with a decision tree, day-one drill, and Custom MCP Build CTA. $29.
silentwatch-mcp — cron silent-failure detection
openclaw-health-mcp — deployment health
openclaw-cost-tracker-mcp — token-cost telemetry
openclaw-skill-vetter-mcp — skill security vetting
openclaw-output-vetter-mcp — agent claim verification (inline grounding-check + swallowed-exception scanner + multi-turn transcript review)
AI Production Discipline Framework — Notion template, $19 — methodology these MCPs implement
SPEC.md — full server design
Built by Temur Khan — production AI engineer. Contact: hello@temhan.dev
List newer-than-current versions, flag any that carry CRITICAL regressions, and recommend the highest version with no CRITICAL regressions in its upgrade path.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully conveys the read-only behavior of listing, flagging, and recommending. It does not mention permissions or rate limits but is sufficient for a safe operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence efficiently conveys three key actions (list, flag, recommend) without extraneous words. It is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description provides a complete picture of what the tool does. It could mention output format but is sufficiently detailed for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters (0 params), so the baseline is 4. The description adds no parameter information, which is unnecessary given no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states three specific actions: listing newer versions, flagging CRITICAL regressions, and recommending a version. This distinguishes it from siblings like current_version (shows current) and regression_catalog (lists regressions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking upgrade options but does not explicitly state when not to use it or mention alternatives. It is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the currently-installed OpenClaw version + how it was detected. Run this first to confirm the backend can read your deployment.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It correctly implies a read-only operation (returning info, no side effects). However, it does not disclose whether authentication is needed or any preconditions, though for a simple version check this is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the core purpose. Every word adds value: the first sentence states the function, the second gives usage advice. No wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description partially explains what is returned ('version + how it was detected') but lacks exact format details. For a simple diagnostic tool in a context with upgrade-related siblings, it covers the essential purpose but could be more explicit about the return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and the description adds no parameter-level information. With schema coverage at 100% and no parameters, the baseline of 4 is appropriate; the description does not need to add param details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: return the installed OpenClaw version and detection method. It provides a specific verb-object pair ('Return the currently-installed OpenClaw version') and adds context about detection. However, it does not explicitly differentiate from sibling tools beyond implying it's the first step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage context: 'Run this first to confirm the backend can read your deployment.' This implies it should be used before other operations, but it does not provide when-not-to-use or mention alternative tools for version-related queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all stored snapshots (id, captured_at, version, summary).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the tool lists data, implying a read-only operation, but does not disclose potential pagination, performance impact, or whether the list is complete. Minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that conveys everything needed: the action, object, and output fields. No extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description covers the return fields and purpose adequately. It could mention if there is any filtering or ordering, but for a simple list tool it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so parameter semantics are trivial. The description does not need to elaborate on parameters, and the schema coverage is 100%. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all stored snapshots and enumerates the fields returned (id, captured_at, version, summary). It effectively distinguishes from sibling tools which are upgrade-specific actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for viewing snapshots but provides no explicit guidance on when to use it versus siblings like pre_upgrade_snapshot or regression_catalog. Usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take a fresh post-upgrade snapshot and diff against a stored pre-upgrade snapshot. Surfaces new_failures (most important), recovered checks, and unchanged failures. Outcome is one of 'success' / 'degraded' / 'regressed'.
| Name | Required | Description | Default |
|---|---|---|---|
| pre_snapshot_id | Yes | The snapshot_id returned by pre_upgrade_snapshot |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the output (surfacing failures, recovered, unchanged) and outcomes, but does not disclose if the tool modifies state (e.g., creates a snapshot) or if there are side effects. The phrasing 'Take a fresh post-upgrade snapshot' suggests a possible mutation, but it is ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: first states the action, second lists what is surfaced, third defines outcomes. No redundant information, and each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the key outputs and outcomes, and with only one well-documented parameter, it is fairly complete. However, it does not explain the format of the returned data or explicitly state the prerequisite of having a pre-upgrade snapshot, though this is implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (pre_snapshot_id) has 100% schema coverage, but the description adds value by specifying it is 'the snapshot_id returned by pre_upgrade_snapshot', which clarifies its origin beyond the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: takes a fresh post-upgrade snapshot and diffs against a pre-upgrade snapshot, surfacing new failures, recovered checks, and unchanged failures. It also defines the outcome categories (success/degraded/regressed). This distinguishes it from siblings like pre_upgrade_snapshot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage is after an upgrade and after a pre_upgrade_snapshot has been taken. It is clear about the context but does not explicitly state when not to use it or mention alternatives like regression_catalog.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run every detection check against the live deployment and persist the result as a Snapshot. Returns the snapshot_id you'll feed to post_upgrade_verify and rollback_guide.
| Name | Required | Description | Default |
|---|---|---|---|
| target_version | No | Optional — version you intend to upgrade to (stored in snapshot) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It implies running checks and persisting a snapshot, but does not explicitly state if this is a read-only or destructive operation. Returns snapshot_id, which is helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action, no filler. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional param, no output schema), the description is complete. It covers purpose, output, and usage with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single optional parameter. Description adds meaning by explaining target_version is stored in the snapshot, going beyond the schema's 'Optional — version'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Run every detection check' and resource 'Snapshot', clearly distinguishing from siblings like post_upgrade_verify and rollback_guide.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States that the snapshot_id is used for post_upgrade_verify and rollback_guide, giving clear context for when to use this tool. Does not explicitly mention when not to use it, but the guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return every known regression in the catalog, optionally filtered to a specific version. Each entry has id + version range + severity + description + mitigation + linked field reports.
| Name | Required | Description | Default |
|---|---|---|---|
| filter_version | No | Optional — only return regressions affecting this version |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses that the tool returns a list of regression entries with structured fields, implying a read-only query. However, it does not explicitly state that no data is modified or mention any other behavioral constraints (e.g., rate limits, authentication needs).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the first sentence delivering the core purpose. The second sentence lists the output fields, which is helpful though slightly verbose. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 required parameters, no output schema), the description is sufficient. It explains both input and output behavior. Minor gap: it does not specify behavior when no regressions match the filter or when the catalog is empty, but this is acceptable for a low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter, and the description reinforces its optional nature ('optionally filtered to a specific version'). Additionally, the description lists the exact fields of each entry (id, version range, severity, description, mitigation, linked field reports), which adds meaning beyond the schema's parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Return every known regression in the catalog,' which is a specific verb+resource combination. It optionally filters by version and enumerates the entry fields (id, version range, severity, etc.), distinguishing it from sibling tools like 'available_upgrades' or 'rollback_guide'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the tool returns regressions, optionally filtered by version. While it doesn't explicitly say when not to use it, the sibling tool names (all upgrade or snapshot related) make the usage context clear. No contradictions or misleading guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compose the rollback plan for a given pre-upgrade snapshot — downgrade command + state-restore steps + risk notes about data migration loss.
| Name | Required | Description | Default |
|---|---|---|---|
| snapshot_id | Yes | Pre-upgrade snapshot to roll back to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool produces a plan including risk notes, but does not explain if it modifies state, requires permissions, or any side effects beyond composition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence efficiently conveys purpose and contents. No redundant words, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately explains what the plan contains, but lacks details on output format (text/structured) or any prerequisites beyond the snapshot_id. For a simple tool with one parameter, this is nearly sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes 'snapshot_id' as 'Pre-upgrade snapshot to roll back to'. The description adds context by specifying 'pre-upgrade snapshot' and 'roll back plan', reinforcing the parameter's role. With 100% schema coverage, the description adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it composes a rollback plan for a pre-upgrade snapshot, listing specific components (downgrade command, state-restore steps, risk notes). This distinguishes it from siblings like upgrade_guide (upgrade planning) and list_snapshots (listing snapshots).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing a rollback plan for a snapshot, but does not explicitly state when to use this tool vs alternatives, nor does it provide exclusions or cross-references to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compose the step-by-step upgrade plan from current → target. Includes pre-upgrade prep steps, the upgrade itself, post-upgrade verification, rollback steps, and any applicable known regressions with their mitigations.
| Name | Required | Description | Default |
|---|---|---|---|
| target_version | Yes | Target version, e.g. '2026.4.27' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses key behavioral traits: the tool composes a plan covering prep, upgrade, verification, rollback, and known regressions. However, it does not mention whether any state is modified, auth requirements, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no waste. It front-loads the main action and then lists contents. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only one parameter and no output schema, the description is sufficiently complete. It covers all relevant aspects of the tool's output and inputs. Missing details about return format are not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'target_version', which includes an example. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Compose the step-by-step upgrade plan' with a specific verb and resource. It enumerates included sections (prep, upgrade, verification, rollback, regressions) and distinguishes from sibling tools like rollback_guide and post_upgrade_verify.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the primary tool for an upgrade plan, but it does not explicitly state when to use it versus alternatives or when not to use it. No exclusion criteria or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0available_upgradescurrent_versionlist_snapshotspost_upgrade_verifypre_upgrade_snapshotregression_catalogrollback_guideupgrade_guideScored across 8 tools
Each tool targets a distinct aspect of the upgrade workflow: version discovery, upgrade listing, snapshot management, pre/post verification, regression info, and plan generation. No two tools have overlapping purposes, ensuring clear selection.
All tool names follow consistent snake_case and are descriptive (e.g., available_upgrades, pre_upgrade_snapshot, rollback_guide). The pattern is predictable and clearly communicates each tool's function.
With 8 tools, the server covers the core upgrade orchestrator workflow without being bloated. Each tool serves a necessary role, making the set well-scoped for its domain.
The tool set covers most essential operations: version detection, upgrade listing, pre/post snapshots, verification, rollback, and regression catalog. The only minor gap is the lack of a tool to actually execute the upgrade, but the upgrade_guide provides step-by-step instructions.
Check exact npm/PyPI upgrades for evidence-backed breaking changes; query APIs and components.
Detect breaking changes, generate changelogs, diff, and validate OpenAPI specs.
Detects database migration table locks, terraform cost leaks, and OWASP API flaws.
Scans schema metadata to classify PHI, score HIPAA readiness, and generate compliant migrations.
